propose-ast-grep-rule
Skill0 starsChanged 7 months agoMITView on GitHub
Propose and add a new ast-grep rule to the project. Use when you notice a pattern-level mistake in the codebase that would repeat, or when a convention from docs/conventions.md isn't yet enforced by a linter. This is how the repo's lint suite grows.
In this repository8 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- add-browser-mcpSkill
- add-packageSkill
- add-visual-lintingSkill
- mine-ast-grep-rulesSkill
- post-friction-lessonSkill
- versionSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
13 rules. About 0 are common, 4 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 32
If you hit the threshold from a single dramatic incident (the one time it caused a production bug), add an entry to docs/lessons.md first …
- Very specific: line 45
If the MCP tools are unavailable (ast-grep not in the tool list), fall back to the ast-grep playground …
- Distinctive: line 49
Describe the pattern plainly: Write two code samples as strings: one that should fail the rule, one that should pass.
- Very specific: line 55
Use Grep on tools/ast-grep/rules/ to see what's already there.
- Very specific: line 57
Dump the AST for your fail sample: Call dump_syntax_tree with the fail sample and language.
- Very specific: line 59
Draft the rule: Create tools/ast-grep/rules/<kebab-id>.yml.
- Very specific: line 83
Preview repo hits with
find_code_by_rule: Call it with your rule against the workspace. - Distinctive: line 84
If the code should be fixed, fix it in the same commit as the rule
- Very specific: line 85
If the code is a legitimate exception, add the path to the rule's ignores *with a comment* explaining why
- Distinctive: line 86
If too many legitimate exceptions pile up, the rule is wrong — go back to step 4
- Distinctive: line 91
When is suppression legitimate?
- Very specific: line 93
Register a fix exemplar: Add an entry to tools/check/fixes.ts keyed by the rule id, with a one-line fix: and a docs: anchor into …
- Very specific: line 101
Prefer
kind:overpattern:: when possible — kind-based rules are more precise and tolerate more syntactic variation.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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
propose-ast-grep-rule
Adds a new structural lint rule to tools/ast-grep/rules/. This is the repo's primary adaptive mechanism — when a pattern causes confusion twice, it becomes a rule.
When to use this skill
- You caught yourself or the user making the same mistake twice
- You found a code pattern that violates
docs/conventions.mdbut isn't enforced - oxlint doesn't have a rule for it, or the existing rule is too broad
- The pattern is expressible structurally (AST shape), not just textually
When NOT to use this skill
- The check is better done with TypeScript types (let
tschandle it) - oxlint already has a rule — enable that instead
- It's a one-off — wait for a second occurrence before committing to a rule
- The "rule" is really a style preference with no functional impact — style is the formatter's job, not the linter's
The two-evidence threshold
Don't propose a rule from a single example. One occurrence could be an accident; a rule is a commitment. The threshold for promoting friction to a rule is:
- You've seen the pattern fail twice in different contexts, OR
- The pattern is in
docs/conventions.mdand went un-enforced
If you hit the threshold from a single dramatic incident (the one time it caused a production bug), add an entry to docs/lessons.md first and tag it — when you see it again, promote it.
MCP over guesswork
This skill drives the ast-grep MCP server registered in .mcp.json. Do not guess YAML syntax — the MCP tools give you ground truth from the same ast-grep engine pnpm check uses.
| Tool | When to call it |
dump_syntax_tree | Before writing a rule: see the exact AST kinds to match on |
test_match_code_rule | After drafting the rule: verify the fail/pass samples |
find_code | Sanity check a pattern without promoting it to a full rule |
find_code_by_rule | Preview real hits in the repo before committing the rule |
If the MCP tools are unavailable (ast-grep not in the tool list), fall back to the ast-grep playground (https://ast-grep.github.io/playground.html) and pnpm exec ast-grep scan --rule-id <id> — but prefer MCP when it's there, because it keeps the loop inside the conversation.
Steps
- Describe the pattern plainly. Write two code samples as strings: one that should fail the rule, one that should pass. Put them in your scratchpad before you touch YAML.
- Check for existing coverage.
Use Grep onpnpm exec oxlint --rules # list what oxlint enforcestools/ast-grep/rules/to see what's already there. If coverage exists and is wrong, fix the existing rule. Don't stack new rules on top. - Dump the AST for your fail sample. Call
dump_syntax_treewith the fail sample and language. Read the tree to pick the rightkind:orpattern:— guessing leads to rules that match nothing or everything. Draft the rule. Create
tools/ast-grep/rules/<kebab-id>.yml. Required fields:id: <kebab-id> # must match filename language: TypeScript severity: error # or warning for advisory rules message: "<see message format below>" note: | <why the rule exists, what to do when it fires, when it's legitimate to suppress> rule: <the structural pattern> files: - "apps/**/*.ts" - "packages/**/*.ts" ignores: - "**/*.d.ts" - "**/dist/**" - "**/node_modules/**"See
docs/conventions.md#ast-grep-rule-message-formatfor themessage:shape — single line, literal fix exemplar, conventions anchor.- Verify with
test_match_code_rule. Paste the YAML plus each sample; confirm the fail sample matches and the pass sample does not. Iterate until both hold. If matches are surprising, dump the tree again — your mental model of the AST is probably wrong. - Preview repo hits with
find_code_by_rule. Call it with your rule against the workspace. For each hit:- If the code should be fixed, fix it in the same commit as the rule
- If the code is a legitimate exception, add the path to the rule's
ignoreswith a comment explaining why - If too many legitimate exceptions pile up, the rule is wrong — go back to step 4
- Write the
note:carefully. The note is what a future LLM will read when the rule fires on its code. A good note answers three questions:- Why is this pattern wrong?
- What's the replacement pattern?
- When is suppression legitimate?
- Register a fix exemplar. Add an entry to
tools/check/fixes.tskeyed by the rule id, with a one-linefix:and adocs:anchor intodocs/conventions.md. This feeds the normalized diagnostic stream (ADR 0002). - Update
docs/lessons.mdto record what prompted the rule. Link the lesson to the rule id. - Run
pnpm check. Confirm the new rule plus any code fixes land cleanly.
Rule-writing tips
- Prefer
kind:overpattern:when possible — kind-based rules are more precise and tolerate more syntactic variation.pattern: "class $X { $$$ }"is fragile;kind: class_declarationis robust. - Use
stopBy: endfor relational rules (inside,has) so the search reaches the end of the direction instead of stopping at the first ancestor/descendant. - Use
not:sparingly. Negated rules are harder to read and debug. Prefer a narrower positive rule. - Test the edge cases you care about. Template literals, async functions, JSX, generics — AST matching can be surprising.
- Set
severity: warningif the rule has occasional false positives. Errors block commits; warnings inform. Don't block commits for a rule you're not confident in.
Anti-patterns
- Writing a rule so specific it only catches the one case that annoyed you. Rules should generalize.
- Writing a rule that duplicates oxlint. Use oxlint's rule with configuration instead.
- Silently deleting a rule because it fires on code you don't feel like fixing. If the rule is consistently wrong, open an ADR under
docs/decisions/and discuss the convention it enforces.
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.

