locksmith
AGENTS.md4 starsChanged 6 months agoApache-2.0View on GitHub
Invoke these via the agent's skill mechanism. Each skill's SKILL.md carries the full step list. release-prep and version-bump never run git push, git tag, or gh pr create themselves - they print the commands for the human maintainer to run. When invoking any superpowers skill (brainstorming, writing-plans, executing-plans, subagent-driven-development, debugging, code-review, etc.), use codegraph_* tools for code navigation - not grep or ad-hoc file reads. CodeGraph is faster and returns structural information (callers, callees, blast radius) that grep cannot. Dispatched…
- Commits and pushes
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,439 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository8 other files it gives its agents.
- .claude/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- .cursor/rules/codegraph.mdcCursor rule
- changelogSkill
- check-licensesSkill
- release-prepSkill
- verificationSkill
- version-bumpSkill
The file
We split this AGENTS.md into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 27
When invoking any superpowers skill (brainstorming, writing-plans, executing-plans, subagent-driven-development, debugging, code-review, …
- Distinctive: line 42
Use codegraph for structural questions — what calls what, what would break, where is X defined, what is X's signature.
- Very specific: line 59
Don't grep first: when looking up a symbol by name.
- Very specific: line 60
Don't chain
codegraph_search+codegraph_node: when you just want context — codegraph_context is one call.
≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md 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
Locksmith - Project Rules
- Overall rules: CLAUDE.md (must read)
- Contributing rules: CONTRIBUTING.md (must read)
- Makefile commands: Makefile (must read)
- Changelog: CHANGES.md
Project skills (.claude/skills/)
Invoke these via the agent's skill mechanism. Each skill's
SKILL.md carries the full step list.
| Skill | When to use |
verification | Final gate on every plan: lint, race, coverage, build, GPG, docs, CHANGES.md. Runs .scripts/verification.sh. |
check-licenses | After any change to go.mod / go.sum. Audits Apache-2.0 compatibility and updates LICENSE. |
release-prep | On develop before cutting a release. Verifies docs reflect each accumulated ## Development bullet, then drives version-bump. Read-only. |
version-bump | Driven by release-prep. Bumps sdk/version/VERSION, syncs README install pin, invokes changelog. Prints git commands; never executes push/tag. |
changelog | Compresses ## Development into a versioned section; triages into BREAKING / Features / Fixes. |
release-prep and version-bump never run git push, git tag,
or gh pr create themselves - they print the commands for the
human maintainer to run.
Superpowers + CodeGraph
When invoking any superpowers skill (brainstorming, writing-plans,
executing-plans, subagent-driven-development, debugging,
code-review, etc.), use codegraph_* tools for code navigation -
not grep or ad-hoc file reads. CodeGraph is faster and returns
structural information (callers, callees, blast radius) that grep
cannot. Dispatched sub-agents inherit this rule. See the CodeGraph
section below for the tool table.
<!-- CODEGRAPH_START -->CodeGraph
This project has a CodeGraph MCP server (codegraph_* tools) configured. CodeGraph is a tree-sitter-parsed knowledge graph of every symbol, edge, and file. Reads are sub-millisecond and return structural information grep cannot.
When to prefer codegraph over native search
Use codegraph for structural questions — what calls what, what would break, where is X defined, what is X's signature. Use native grep/read only for literal text queries (string contents, comments, log messages) or after you already have a specific file open.
| Question | Tool |
| "Where is X defined?" / "Find symbol named X" | codegraph_search |
| "What calls function Y?" | codegraph_callers |
| "What does Y call?" | codegraph_callees |
| "What would break if I changed Z?" | codegraph_impact |
| "Show me Y's signature / source / docstring" | codegraph_node |
| "Give me focused context for a task/area" | codegraph_context |
| "Survey an unfamiliar module/topic" | codegraph_explore |
| "What files exist under path/" | codegraph_files |
| "Is the index healthy?" | codegraph_status |
Rules of thumb
- Trust codegraph results. They come from a full AST parse. Do NOT re-verify them with grep — that's slower, less accurate, and wastes context.
- Don't grep first when looking up a symbol by name.
codegraph_searchis faster and returns kind + location + signature in one call. - Don't chain
codegraph_search+codegraph_nodewhen you just want context —codegraph_contextis one call. codegraph_exploreis the heavy hitter for unfamiliar areas — it returns full source from all relevant files in one call, but is token-heavy. If your harness supports parallel subagents (e.g., Claude Code's Task tool), spawn one for explore-class questions to keep main session context clean.- Index lag: the file watcher debounces ~500ms behind writes; don't re-query immediately after editing a file in the same turn.
If .codegraph/ doesn't exist
The MCP server returns "not initialized." Ask the user: "I notice this project doesn't have CodeGraph initialized. Want me to run codegraph init -i to build the index?"
<!-- CODEGRAPH_END -->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.