From a81088203b8f7f4d440d8be9521abfa1b489876a Mon Sep 17 00:00:00 2001 From: aleonard Date: Sat, 10 Oct 2026 00:28:37 +0200 Subject: [PATCH] =?UTF-8?q?docs(contributing):=20=F0=9F=93=9D=20add=20cont?= =?UTF-8?q?ribution=20guide=20and=20PR=20template?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/pull_request_template.md | 15 +++++++ CONTRIBUTING.md | 69 ++++++++++++++++++++++++++++++++ README.md | 2 + 3 files changed, 86 insertions(+) create mode 100644 .github/pull_request_template.md create mode 100644 CONTRIBUTING.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..334fd60 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,15 @@ +## What does this change? + +Describe the problem and how this change addresses it. Link a related issue if one exists. + +## How can someone use or review it? + +Include a usage example for a new or changed skill. For security policy changes, explain any changes to approvals or access boundaries and what requires external enforcement. + +## Verification + +List checks actually performed and their results. Note any checks not performed or blocked, with a reason. + +- [ ] I kept this PR focused on one purpose. +- [ ] I updated relevant documentation and links. +- [ ] I checked that no credentials, secrets, or private data are included. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..3f87478 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,69 @@ +# 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 + +- 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. + +## 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. diff --git a/README.md b/README.md index db93c82..40b0744 100644 --- a/README.md +++ b/README.md @@ -105,6 +105,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