# Contributing

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:

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

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

```bash
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:

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