Contributing

Contributing

How to build and submit a new agent, skill, or prompt.

---

Before You Start

1. Search agents/ — check that the agent doesn't already exist
2. Open an issue using the New Agent template and describe your idea
3. Wait for a thumbs-up before building — this avoids duplicate effort and ensures the agent fits the repo's scope

---

Adding a New Agent

File structure

Every agent must have all four files:

agents/<platform>/<your-agent-name>/
├── README.md          ← quick start, use cases, related agents
├── agent.md           ← full spec: input, output, system prompt
├── example-input.md   ← real, paste-ready input + 2–3 variations
└── example-output.md  ← verified output from that exact input

Templates

cp templates/agent-template.md agents/<platform>/<name>/agent.md

The template has every required section with guidance comments.

Naming

• Folder name: kebab-case (e.g. memory-leak-detector, api-contract-reviewer)
• Agent file: always agent.md
• Platform folder: use existing folders (android, ios, flutter, react-native, unity, unreal, cross-platform)

---

Writing agent.md

Required sections

Section	What to Include
## Purpose	One sentence — what it does and what problem it solves
## Input Format	Code block showing the exact input schema + a Fields table
## Output Format	The exact output structure the agent produces
## System Prompt	The full prompt in a fenced code block — what you paste into the LLM
## Example	One complete input + one complete output (real, tested)
## Notes	Edge cases, version requirements, LLM compatibility

System Prompt rules

• Written in second person: "You are a senior Android engineer..."
• State the exact output format the LLM must follow
• End with: "Output MUST follow the exact format specified. Do not add extra sections or omit any section."
• Keep under 600 tokens — longer prompts break in constrained sessions

Severity levels (for review agents)

Level	When to Use
CRITICAL	Crash, memory leak, data loss, security vulnerability, severe perf issue
WARNING	Technical debt, anti-pattern, will cause problems at scale
INFO	Style, minor improvement, optional enhancement

---

Writing example-input.md

• Use real code with intentional issues — not toy pseudocode
• Include 2–3 variations at the bottom to show other scenarios the agent handles
• The main example should produce the full output format when run

---

Writing example-output.md

This must be the real output from testing the agent — not a manually written example.

Process:

1. Copy the system prompt into Claude Sonnet 4.6 or GPT-4o
2. Paste the content from example-input.md
3. Run it — get the actual output
4. Paste the full output into example-output.md
5. Run it once more with a different input to verify consistency

An agent whose example-output.md was hand-written will be rejected.

---

Adding a New Skill

skills/<platform>/<skill-name>.md

Copy templates/skill-template.md. A skill must have:

• Purpose — one sentence
• When to Use — 2–3 bullet points
• Skill Prompt — the self-contained prompt block
• Example — real input and output
• Composition Example — how to use with an agent or another skill

Keep skills focused on one concern. If it does two things, split it into two skills.

---

Adding a New Prompt

prompts/<platform>/<prompt-name>.md

Copy templates/prompt-template.md. A prompt must have:

• Purpose — one sentence
• Prompt — the full text with [PASTE YOUR CODE HERE] placeholder
• Example Usage — the prompt with real content substituted in + expected output
• Variations — 1–2 modifications for related use cases

---

Quality Bar

An agent is rejected if:

• example-output.md contains placeholder text (<output here>, ...)
• The system prompt is over 600 tokens
• The output format is non-deterministic (two runs produce structurally different output)
• The input format has unlabelled or ambiguous fields

An agent is accepted if:

• It solves a problem developers actually hit in production
• A first-time user can fill the input format correctly without reading the full spec
• The output is structured enough to be machine-parseable
• The example was tested on at least one real-world code file

---

Pull Request Checklist

Before opening a PR:

• All four files exist: README.md, agent.md, example-input.md, example-output.md
• Every section in agent.md is filled — no placeholder text
• example-output.md is real output from testing the system prompt
• No sensitive data in examples (real API keys, PII, production crash logs from real users)
• The agent was tested on Claude Sonnet 4.6 or GPT-4o
• A GitHub issue was opened and approved before building

---

What to Contribute Next

See docs/roadmap/github-issues.md for 10 planned agents with full specifications ready to implement.

---

Home · Using Agents · FAQ