Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
88 lines (61 loc) · 2.52 KB

CONTRIBUTING.md

File metadata and controls

88 lines (61 loc) · 2.52 KB

Contributing to Awesome Codex Subagents

Thanks for contributing.

This repository is a curated collection of Codex-native subagents (.toml files). Contributions should prioritize practical usefulness, clear scope, and compatibility with official Codex behavior.

How to Contribute

Add a New Subagent

  1. Choose the correct category under categories/.
  2. Add one .toml file for the new agent.
  3. Update both:
    • README.md (main category listing)
    • categories/<category>/README.md (linked bullet + short description)
  4. Keep agent names sorted alphabetically where possible.
  5. Open a PR with the use case and why this agent is distinct.

Improve an Existing Subagent

  1. Keep the role bounded (avoid broad persona text).
  2. Preserve Codex-native format.
  3. Update relevant README descriptions if behavior or intent changed.
  4. Include before/after rationale in your PR.

Required Agent Format

Each agent must be a valid TOML file and include:

  • name
  • description
  • developer_instructions

Common optional fields:

  • model
  • model_reasoning_effort
  • sandbox_mode
  • mcp_servers

Authoring Quality Bar

developer_instructions should be concrete and task-shaped. Use this structure:

  • Working mode
  • Focus on
  • Quality checks
  • Return
  • Do not ... unless explicitly requested by the parent agent.

Avoid:

  • Unsupported tool/platform assumptions
  • Generic roleplay text with no output contract
  • Scope creep instructions ("always do everything")

Model and Sandbox Guidance

  • Prefer gpt-5.4 for complex reasoning/review roles.
  • Prefer gpt-5.3-codex-spark for lighter search/synthesis roles.
  • Use read-only by default for review/research agents.
  • Use workspace-write only when the agent must implement changes.

Validation Checklist (Before PR)

  • All links in README.md and category READMEs resolve.
  • New/edited .toml files parse correctly.
  • Agent name is unique across repository.
  • Main and category READMEs include the new agent.
  • Descriptions stay concise and accurate to current behavior.

Pull Request Checklist

  • Added/updated agent TOML file(s)
  • Updated main README.md
  • Updated category README.md
  • Verified links and TOML validity
  • Included clear PR description and motivation

Style Notes

  • Keep documentation in English.
  • Prefer precise, practical wording over marketing language.
  • Keep descriptions short; keep instructions high-signal.

License

By contributing, you agree your contributions are provided under the repository license terms.