diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..2d1320e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,75 @@ +# Contributing to Agent Toolbox + +Contributions and pull requests are welcome, including small documentation fixes. You can improve existing skills and policies, add reusable workflows, or share practical examples. + +## Start with a focused change + +Read the [README](README.md) and the relevant skill's `SKILL.md` before starting. Check existing issues and pull requests to avoid duplicating work. + +- Fix unclear instructions or broken links. +- Add examples showing how to use an existing skill. +- Improve a security rule and explain the scenario it addresses. +- Propose a new skill that solves a concrete, reusable problem. + +For a large change, open an issue first to discuss the scope. Small fixes can go straight to a pull request. + +## Open a pull request + +1. Fork this repository into your own GitHub account. +2. Clone your fork and create a branch: + + ```bash + git clone https://github.com/YOUR-USERNAME/agent-toolbox.git + cd agent-toolbox + git switch -c docs/your-change + ``` + +3. Make a focused change and perform the relevant checks below. +4. Review the diff and stage only the files you intend to contribute. For example, for a README change: + + ```bash + git diff + git add README.md + git diff --cached + git commit -m "docs(readme): 📝 clarify setup instructions" + git push -u origin docs/your-change + ``` + +5. Open a pull request from your fork's branch into `zmo2s/agent-toolbox:main`. Explain the problem, your solution, and the checks you performed. Link related issues and describe expected behavior with a concrete example when changing a skill. + +## Adding or updating a skill + +Follow the existing layout: + +```text +.codex/skills/your-skill-name/SKILL.md +``` + +Use a lowercase, hyphenated folder name. Start `SKILL.md` with YAML metadata: + +```yaml +--- +name: your-skill-name +description: Explain what the skill does and when to use it. +--- +``` + +Keep instructions focused on the intended task. Include practical usage examples and document prerequisites or limitations. Add supporting files only when they serve the skill, and link new skills from the README resource table. + +Security guidance should distinguish instructions for the agent from controls enforced by permissions, sandboxing, or the database. Explain changes to approval requirements and access boundaries. Never include real credentials, secrets, or private data in examples. + +## Checks before submitting + +- Run `git diff --check` to catch whitespace errors. +- For documentation, verify relative links and examples against the repository. +- For skill changes, check the metadata and try a relevant example in a safe environment. Describe what you actually verified. +- For JavaScript changes, run `npm test` with Node.js installed and add or update tests when behavior changes. +- Record checks that were skipped or blocked and explain why. Documentation-only changes do not require the JavaScript test suite. + +Use commit subjects in the repository's format: `(): `. The [Good Commit skill](.codex/skills/good-commit/SKILL.md) contains examples. + +Keep unrelated changes out of your PR. Maintainers may ask for revisions before merging; opening a PR does not automatically publish its changes on the default branch. + +## Give and receive feedback + +Be respectful and constructive when reviewing others' work. Explain the reason for a suggested change, ask questions when intent is unclear, and include reproduction steps for problems you find. When requesting a review, point out the behavior or instructions you would like someone to check. diff --git a/README.md b/README.md index 5de069c..b10bad5 100644 --- a/README.md +++ b/README.md @@ -116,6 +116,8 @@ agent-toolbox/ Ideas, improvements, and pull requests are welcome! Help improve existing policies, add reusable skills, or share practical workflows. +Start with the [contribution guide](CONTRIBUTING.md) for fork and branch instructions, skill structure, and checks before opening a PR. Small documentation fixes are welcome too. + Keep each PR focused, explain the problem it solves, and include usage examples and any checks you performed. For security-related changes, describe what the policy asks an agent to do and which protections require external enforcement. ## License