Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 75 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -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: `<type>(<scope>): <emoji> <description>`. 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.
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading