agentleFS
robmclartyrobmclarty/trailhead/.claude/skills/propose-ast-grep-rule/SKILL.md

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.

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
  1. Very specific:

    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 …

    line 32
  2. Very specific:

    If the MCP tools are unavailable (ast-grep not in the tool list), fall back to the ast-grep playground …

    line 45
  3. Distinctive:

    Describe the pattern plainly: Write two code samples as strings: one that should fail the rule, one that should pass.

    line 49
  4. Very specific:

    Use Grep on tools/ast-grep/rules/ to see what's already there.

    line 55
  5. Very specific:

    Dump the AST for your fail sample: Call dump_syntax_tree with the fail sample and language.

    line 57
  6. Very specific:

    Draft the rule: Create tools/ast-grep/rules/<kebab-id>.yml.

    line 59
  7. Very specific:

    Preview repo hits with find_code_by_rule: Call it with your rule against the workspace.

    line 83
  8. Distinctive:

    If the code should be fixed, fix it in the same commit as the rule

    line 84
  9. Very specific:

    If the code is a legitimate exception, add the path to the rule's ignores *with a comment* explaining why

    line 85
  10. Distinctive:

    If too many legitimate exceptions pile up, the rule is wrong — go back to step 4

    line 86
  11. Distinctive:

    When is suppression legitimate?

    line 91
  12. Very specific:

    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 …

    line 93
  13. Very specific:

    Prefer kind: over pattern:: when possible — kind-based rules are more precise and tolerate more syntactic variation.

    line 101

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.md but 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 tsc handle 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.md and 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.

ToolWhen to call it
dump_syntax_treeBefore writing a rule: see the exact AST kinds to match on
test_match_code_ruleAfter drafting the rule: verify the fail/pass samples
find_codeSanity check a pattern without promoting it to a full rule
find_code_by_rulePreview 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

  1. 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.
  2. Check for existing coverage.
    pnpm exec oxlint --rules  # list what oxlint enforces
    Use Grep on tools/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.
  3. Dump the AST for your fail sample. Call dump_syntax_tree with the fail sample and language. Read the tree to pick the right kind: or pattern: — guessing leads to rules that match nothing or everything.
  4. 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-format for the message: shape — single line, literal fix exemplar, conventions anchor.

  5. 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.
  6. 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 ignores with a comment explaining why
    • If too many legitimate exceptions pile up, the rule is wrong — go back to step 4
  7. 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?
  8. 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 docs/conventions.md. This feeds the normalized diagnostic stream (ADR 0002).
  9. Update docs/lessons.md to record what prompted the rule. Link the lesson to the rule id.
  10. Run pnpm check. Confirm the new rule plus any code fixes land cleanly.

Rule-writing tips

  • Prefer kind: over pattern: when possible — kind-based rules are more precise and tolerate more syntactic variation. pattern: "class $X { $$$ }" is fragile; kind: class_declaration is robust.
  • Use stopBy: end for 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: warning if 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.