add-gather-agent
Skill8 starsChanged 7 months agoApache-2.0View on GitHub
Read these files before touching anything: - prompts/patterns.md — anatomy of a gather prompt (evidence requirement, numbered output fields) - schemas/tooling.json — example schema with additionalProperties: false and enum fields - lib/gather.sh lines 24-65 — where to add your run_agent call in run_agents_parallel - lib/gather.sh lines 67-102 — critical-failure gating and get_failed_agents check list - tests/helpers/mock_claude.bash — how dispatch mode matches agent names to fixture files - tests/unit/agent_run.bats — the test setup pattern (envelope, dispatch, assertions) Choose a kebab-case name…
In this repository22 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- .github/workflows/CLAUDE.mdCLAUDE.md
- lib/CLAUDE.mdCLAUDE.md
- prompts/CLAUDE.mdCLAUDE.md
- schemas/CLAUDE.mdCLAUDE.md
- scripts/CLAUDE.mdCLAUDE.md
- tests/CLAUDE.mdCLAUDE.md
- add-bats-testSkill
- add-edge-testSkill
- add-integration-testSkill
- add-synthesis-fixtureSkill
- audit-prompt-schema-syncSkill
- bundle-and-verifySkill
- check-ci-locallySkill
- debug-agent-failureSkill
- fixture-syncSkill
- pre-pr-checklistSkill
- rebuild-test-imageSkill
- release-ultrainitSkill
- run-testsSkill
- tune-synthesis-contextSkill
- validate-generated-artifactSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 2 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
Read these files before touching anything:
- Distinctive: line 30
Critical agent?: Only add to the critical list if synthesis cannot proceed without this agent's findings
- Very specific: line 54
Create schemas/<agent-name>.json.
- Very specific: line 80
Use "enum" for all categorical fields — downstream jq select() relies on exact string matching
- Very specific: line 81
Use "type": "array" (never nullable) for optional collections — consumers use .field[]?
- Very specific: line 82
Use "$defs" for repeated item shapes (see schemas/commands.json)
- Very specific: line 106
Create tests/fixtures/findings/<agent-name>.json with realistic data matching your schema:
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Before You Start
Read these files before touching anything:
prompts/patterns.md— anatomy of a gather prompt (evidence requirement, numbered output fields)schemas/tooling.json— example schema withadditionalProperties: falseand enum fieldslib/gather.shlines 24-65 — where to add yourrun_agentcall inrun_agents_parallellib/gather.shlines 67-102 — critical-failure gating andget_failed_agentscheck listtests/helpers/mock_claude.bash— how dispatch mode matches agent names to fixture filestests/unit/agent_run.bats— the test setup pattern (envelope, dispatch, assertions)
Steps
1. Name and scope the agent
Choose a kebab-case name (e.g., dependency-graph). Decide:
- Model tier:
haikufor simple file scanning (matches identity, tooling, commands, docs-scanner, security-scan);sonnetfor reasoning (matches git-forensics, patterns, structure-scout) - Tool allowlist:
Read,Bash(find:*),Bash(cat:*)for file reading; addBash(git:*)only for git history; addGlobfor pattern matching - Critical agent? Only add to the critical list if synthesis cannot proceed without this agent's findings
2. Write the system prompt
Create prompts/<agent-name>.md:
You are analyzing a software codebase. Your goal: [one sentence].
For this codebase, determine:
1. [output field 1 — instructions on what to look for and where]
2. [output field 2]
...
For every finding, cite the specific file path(s) where you found evidence.
Do NOT invent patterns. Only report what you can prove exists in the files.
Return results as structured JSON matching the schema provided.The evidence-requirement sentence is mandatory in every gather prompt — see prompts/patterns.md for the exact phrasing used across agents.
3. Write the JSON schema
Create schemas/<agent-name>.json. All schemas must use "additionalProperties": false at every nested object level:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"additionalProperties": false,
"required": ["findings"],
"properties": {
"findings": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": ["name", "category"],
"properties": {
"name": { "type": "string" },
"category": { "type": "string", "enum": ["A", "B", "C"] },
"evidence_files": { "type": "array", "items": { "type": "string" } }
}
}
}
}
}- Use
"enum"for all categorical fields — downstreamjq select()relies on exact string matching - Use
"type": "array"(never nullable) for optional collections — consumers use.field[]?safely - Use
"$defs"for repeated item shapes (seeschemas/commands.json) - Validate before wiring:
jq empty schemas/<agent-name>.json
4. Wire into gather.sh
Open lib/gather.sh. Find the run_agents_parallel call in gather_evidence() (lines 24-65). Add your agent as a new argument string:
run_agents_parallel \
"run_agent identity ..." \
... \
"run_agent <agent-name> \
'@${SCRIPT_DIR}/prompts/<agent-name>.md' \
'${SCRIPT_DIR}/schemas/<agent-name>.json' \
'Read,Bash(find:*),Bash(cat:*)' \
haiku gather"Always use the @ prefix for the prompt path — this is required for prompts with shell-special characters (apostrophes, parens, backticks) and prevents ARG_MAX issues on large prompts. Always use $SCRIPT_DIR for absolute paths.
Also add <agent-name> to the core_agents array and the get_failed_agents check (lines 67-77). If critical, add to critical_agents array too.
5. Create the test fixture
Create tests/fixtures/findings/<agent-name>.json with realistic data matching your schema:
{
"findings": [
{
"name": "example-finding",
"category": "A",
"evidence_files": ["lib/example.sh", "schemas/example.json"]
}
]
}The filename must exactly match the agent name passed to run_agent(). This is the three-way identity: fixture filename = agent name = findings file name. A mismatch silently breaks mock dispatch routing. This file contains only the structured_output value — the mock dispatch wraps it via make_claude_envelope.
6. Add the dispatch entry to integration tests
In tests/integration/gather_phase.bats, find the dispatch setup block and add:
make_claude_envelope \
"$(cat "$BATS_TEST_DIRNAME/../fixtures/findings/<agent-name>.json")" "0.15" \
> "$MOCK_CLAUDE_DISPATCH_DIR/<agent-name>.json"Also update the systemic-failure test that pre-creates exactly 4 of 8 findings — if you add a 9th core agent, the threshold math changes (3+ of 9 now requires updating).
7. Add a unit test
Create tests/unit/<agent-name>_run.bats:
setup() {
load '../helpers/test_helper'
_common_setup
load '../helpers/mock_claude'
setup_mock_claude
}
teardown() { _common_teardown; }
@test "run_agent <agent-name>: writes findings on success" {
make_claude_envelope \
"$(cat "$BATS_TEST_DIRNAME/../fixtures/findings/<agent-name>.json")" "0.15" \
> "$MOCK_CLAUDE_RESPONSE"
run run_agent "<agent-name>" \
"@${SCRIPT_DIR}/prompts/<agent-name>.md" \
"${SCRIPT_DIR}/schemas/<agent-name>.json" \
"Read,Bash(find:*)" "haiku" "gather"
assert_success
assert_file_exists "$WORK_DIR/findings/<agent-name>.json"
}
@test "run_agent <agent-name>: skips when findings exist and FORCE=false" {
echo '{"findings":[]}' > "$WORK_DIR/findings/<agent-name>.json"
FORCE=false run run_agent "<agent-name>" "..." "..." "..." "haiku"
assert_success
run grep 'CALL:' "$MOCK_CLAUDE_LOG"
assert_failure # mock was not called
}Verify
# Validate schema is well-formed
jq empty schemas/<agent-name>.json
# Syntax-check gather.sh after wiring
bash -n lib/gather.sh
# Run all tests
make test-unit
make test-integration
make test-allCommon Mistakes
- Missing
additionalProperties: falseon nested objects — this is the single most common schema error. Every"type": "object"at every nesting level needs it, or Claude can hallucinate extra fields. - Inline prompt with shell-special characters — prompts containing apostrophes, parens, backticks, or
$break parallel temp-script expansion. Always use the@/absolute/pathform. See PR #2 andtests/edge/special_characters.bats. - Wrong fixture filename — the fixture must be named exactly
<agent-name>.jsonwhere<agent-name>matches the first arg torun_agent(). A mismatch silently falls through toMOCK_CLAUDE_RESPONSE. - Not updating
core_agentsarray — if you add the agent torun_agents_parallelbut not tocore_agents(and optionallycritical_agents) inlib/gather.sh, the failure-gating logic ignores it completely.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

