Contributing

May 20, 2026 ยท View on GitHub

Thanks for helping improve Agent Workflow Kit.

This repository is mostly documentation and reusable agent workflow rules. Contributions should keep the project tool-neutral, practical, and easy to copy into real repositories.

Before You Start

  • Read README.md or README.zh-CN.md for the project shape.
  • Check whether your change affects both the human guide and the agent-facing skill packages.
  • Keep examples conservative. Do not imply that a tool is required when it is only an optional reference.

Keep Content Synchronized

When changing public guide content, update both languages when applicable:

  • docs/guide.md
  • docs/guide.zh-CN.md

When changing homepage content, update both:

  • README.md
  • README.zh-CN.md

When changing agent workflow rules, check the skill packages too:

  • skills/agent-workflow-kit/SKILL.md
  • skills/agent-workflow-kit-zh-cn/SKILL.md
  • skills/*/references/agents-templates*.md
  • skills/*/references/engineering-references*.md

If a reference is removed from the guide, remove it from the matching skill reference files unless there is a clear reason to keep it.

Optional References

Engineering reference links are optional references, not install requirements or endorsements. Before adding one, consider:

  • Is the source authoritative for the scenario?
  • Is it maintained or intentionally stable?
  • Is the license compatible with being referenced?
  • Does the guide explain when to use it and when not to use it?

Do not add references only because they are popular.

Validation

Run the docs check before opening a pull request:

ruby scripts/check-docs.rb
git diff --check

If public link checks are flaky locally, run the structural check:

SKIP_LINK_CHECK=1 ruby scripts/check-docs.rb

Pull requests and pushes run structural checks in CI. Public link checks run separately on a schedule or manually, and are not intended to block unrelated documentation changes.

Commit Style

Use short, descriptive commit messages. Conventional Commit style is welcome but not required.

Examples:

docs: clarify optional references
docs: sync Chinese skill reference catalog
ci: make link checks non-blocking