Agent-Skills.md

Agent Skills: ast-grep for TypeScript & React

Use this skill when writing, debugging, or reviewing ast-grep patterns, YAML rules, or codemods against TypeScript or React (.ts/.tsx) code — searching for JSX elements, props, hooks, imports, or type constructs, and rewriting them. Covers the TS/React-specific traps — the tsx-vs-typescript language split, JSX and TypeScript node kinds, fragment matching, rewrites, and the @ast-grep/napi API. Complements the general-purpose ast-grep skill (rule mechanics) — reach for this one whenever the target code is TypeScript or React.

UncategorizedID: pproenca/dot-skills/ast-grep-typescript-react

Repository

pproenca/dot-skills
pproencaLicense: MIT
20717

Install this agent skill to your local

pnpm dlx add-skill https://github.com/pproenca/dot-skills/tree/HEAD/skills/.experimental/ast-grep-typescript-react

Skill Files

Browse the full folder contents for ast-grep-typescript-react.

Download Skill

Loading file tree…

skills/.experimental/ast-grep-typescript-react/SKILL.md

Skill Metadata

Name
ast-grep-typescript-react
Description
Use this skill when writing, debugging, or reviewing ast-grep patterns, YAML rules, or codemods against TypeScript or React (.ts/.tsx) code — searching for JSX elements, props, hooks, imports, or type constructs, and rewriting them. Covers the TS/React-specific traps — the tsx-vs-typescript language split, JSX and TypeScript node kinds, fragment matching, rewrites, and the @ast-grep/napi API. Complements the general-purpose ast-grep skill (rule mechanics) — reach for this one whenever the target code is TypeScript or React.

ast-grep for TypeScript & React

The wrong defaults a capable model hits when pointing ast-grep at .ts/.tsx code — mostly cases where a rule silently matches nothing because the language or a node kind was guessed wrong. This skill assumes you already know ast-grep's rule mechanics (patterns, meta-variables, all/any/has/inside, constraints); it corrects only what TypeScript and React add on top.

For general ast-grep rule-writing mechanics, use the companion ast-grep skill.

When to Apply

  • Writing an ast-grep pattern or YAML rule whose target is .ts or .tsx code
  • Searching for JSX elements, props, React hooks, imports, or TS type constructs
  • Building a codemod that rewrites JSX or TypeScript (rename a component, strip React.FC, migrate imports)
  • A rule "matches nothing" on TSX and you don't know why (usually the language or a node kind)
  • Driving ast-grep programmatically from a JS/TS script via @ast-grep/napi

First moves when a TS/React rule misbehaves

  1. Check the language. JSX-bearing files must run under tsx, never typescript. This is the single most common cause of silent no-match. See lang-tsx-for-jsx.
  2. Debug the pattern's AST. ast-grep run --pattern '<your pattern>' --lang tsx --debug-query=ast on a real snippet shows the node kinds and reveals ERROR nodes. Trust this over guessed kind names.
  3. Wrap fragments. If the pattern is an attribute, prop, or type annotation, it needs context + selector. See ctx-fragment-context-selector.

Rule Categories

| # | Category | Prefix | Covers | |---|----------|--------|--------| | 1 | Language Selection | lang | tsx-vs-typescript split, scanning .ts + .tsx, languageGlobs | | 2 | Fragment Matching | ctx | context/selector for JSX attrs, props, type annotations | | 3 | JSX Node Kinds | jsx | self-closing vs paired elements, attribute-value metavariables | | 4 | TypeScript Constructs | ts | type-only imports, as casts, React.FC generics | | 5 | Rewrites & Codemods | fix | re-emitting JSX metavars so children/props aren't dropped | | 6 | Programmatic Use | napi | @ast-grep/napi Lang.Tsx, NapiConfig shape |

Quick Reference

1. Language Selection (lang)

  • lang-tsx-for-jsx — Use tsx for any JSX; typescript parses JSX as ERROR and matches nothing
  • lang-scan-ts-and-tsx — Cover both .ts and .tsx; languageGlobs for reuse (+ the <T>-cast caveat)

2. Fragment Matching (ctx)

3. JSX Node Kinds (jsx)

4. TypeScript Constructs (ts)

5. Rewrites & Codemods (fix)

6. Programmatic Use (napi)

How to Use

Read the individual reference file for the decision you're making — each is self-contained with a canonical example. references/_sections.md defines the categories; AGENTS.md is the full compiled index.

Related Skills

  • ast-grep — general ast-grep rule-writing mechanics (patterns, composition, constraints, testing). This skill layers TS/React specifics on top of it.