Skip to content
Skills Library
Programming · Building & coding

codemod

/codemod

Codemod (JSSG, ast-grep, workflows) best practices for writing efficient, safe, and maintainable code transformations. This skill should be used when writing, reviewing, or debugging codemods, AST transformations, or automated refactoring tools. Triggers on tasks involving codemod, ast-grep, JSSG, code transformation, or automated migration.

Repository
dot-skills ↗
Licence
MIT
Last repository change
15.08.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
54
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 15.08.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Codemod (JSSG, ast-grep, workflows) best practices for writing efficient, safe, and maintainable code transformations. This skill should be used when writing, reviewing, or debugging codemods, AST transformations, or automated refactoring tools. Triggers on tasks involving codemod, ast-grep, JSSG, code transformation, or automated migration.

Original author description

Codemod (JSSG, ast-grep, workflows) best practices for writing efficient, safe, and maintainable code transformations. This skill should be used when writing, reviewing, or debugging codemods, AST transformations, or automated refactoring tools. Triggers on tasks involving codemod, ast-grep, JSSG, code transformation, or automated migration.

How it works

  1. When to Apply
  2. Rule Categories by Priority
  3. Quick Reference
  4. How to Use
  5. Full Compiled Document
Original SKILL.md headings · 124 lines, 700 words
SKILL.md preview
---
name: codemod
description: Codemod (JSSG, ast-grep, workflows) best practices for writing efficient, safe, and maintainable code transformations. This skill should be used when writing, reviewing, or debugging codemods, AST transformations, or automated refactoring tools. Triggers on tasks involving codemod, ast-grep, JSSG, code transformation, or automated migration.
---

# Codemod Best Practices

Comprehensive best practices guide for Codemod (JSSG, ast-grep, workflows), designed for AI agents and LLMs. Contains 48 rules across 11 categories, prioritized by impact to guide automated refactoring and code generation.

## When to Apply

Reference these guidelines when:
- Writing new codemods with JSSG or ast-grep
- Designing workflow configurations for migrations
- Debugging pattern matching or AST traversal issues
- Reviewing codemod code for performance and safety
- Setting up test fixtures for transform validation

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | AST Understanding | CRITICAL | `ast-` |
| 2 | Pattern Efficiency | CRITICAL | `pattern-` |
| 3 | Parsing Strategy | CRITICAL | `parse-` |
| 4 | Node Traversal | HIGH | `traverse-` |
| 5 | Semantic Analysis | HIGH | `semantic-` |
| 6 | Edit Operations | MEDIUM-HIGH | `edit-` |
| 7 | Workflow Design | MEDIUM-HIGH | `workflow-` |
| 8 | Testing Strategy | MEDIUM | `test-` |
| 9 | State Management | MEDIUM | `state-` |
| 10 | Security and Capabilities | LOW-MEDIUM | `security-` |
| 11 | Package Structure | LOW | `pkg-` |

## Quick Reference

### 1. AST Understanding (CRITICAL)

- [`ast-explore-before-writing`](references/ast-explore-before-writing.md) - Use AST Explorer before writing patterns
- [`ast-understand-named-vs-anonymous`](references/ast-understand-named-vs-anonymous.md) - Understand named vs anonymous nodes
- [`ast-use-kind-for-precision`](references/ast-use-kind-for-precision.md) - Use kind constraint for precision
- [`ast-field-access-for-structure`](references/ast-field-access-for-structure.md) - Use field access for structural queries
- [`ast-check-null-before-access`](references/ast-check-null-before-access.md) - Check null before property access

### 2. Pattern Efficiency (CRITICAL)

- [`pattern-use-meta-variables`](references/pattern-use-meta-variables.md) - Use meta variables for flexible matching
- [`pattern-avoid-overly-generic`](references/pattern-avoid-overly-generic.md) - Avoid overly generic patterns
- [`pattern-combine-with-rules`](references/pattern-combine-with-rules.md) - Combine patterns with rule operators
- [`pattern-use-constraints`](references/pattern-use-constraints.md) - Use constraints for reusable matching logic
- [`pattern-use-relational-patterns`](references/pattern-use-relational-patterns.md) - Use relational patterns for context
- [`pattern-ensure-idempotency`](references/pattern-ensure-idempotency.md) - Ensure patterns are idempotent

### 3. Parsing Strategy (CRITICAL)

- [`parse-select-correct-parser`](references/parse-select-correct-parser.md) - Select the correct parser for file type
- [`parse-handle-embedded-languages`](references/parse-handle-embedded-languages.md) - Handle embedded languages with parseAsync
- [`parse-provide-pattern-context`](references/parse-provide-pattern-context.md) - Provide context for ambiguous patterns
- [`parse-early-return-non-applicable`](references/parse-early-return-non-applicable.md) - Early return for non-applicable files

### 4. Node Traversal (HIGH)

- [`traverse-use-find-vs-findall`](references/traverse-use-find-vs-findall.md) - Use find() for single match, findAll() for multiple
- [`traverse-single-pass-collection`](references/traverse-single-pass-collection.md) - Collect multiple patterns in single traversal
- [`traverse-use-stopby-for-depth`](references/traverse-use-stopby-for-depth.md) - Use stopBy to control traversal depth
- [`traverse-use-siblings-efficiently`](references/traverse-use-siblings-efficiently.md) - Use sibling navigation efficiently
- [`traverse-cache-repeated-lookups`](references/traverse-cache-repeated-lookups.md) - Cache repeated node lookups

### 5. Semantic Analysis (HIGH)

- [`semantic-use-file-scope-first`](references/semantic-use-file-scope-first.md) - Use file scope semantic analysis first
- [`semantic-check-null-results`](references/semantic-check-null-results.md) - Handle null semantic analysis results
- [`semantic-verify-file-ownership`](references/semantic-verify-file-ownership.md) - Verify file ownership before cross-file edits
- [`semantic-cache-cross-file-results`](references/semantic-cache-cross-file-results.md) - Cache semantic analysis results

### 6. Edit Operations (MEDIUM-HIGH)

- [`edit-batch-before-commit`](references/edit-batch-before-commit.md) - Batch edits before committing
- [`edit-preserve-formatting`](references/edit-preserve-formatting.md) - Preserve surrounding formatting in edits
- [`edit-handle-overlapping-ranges`](references/edit-handle-overlapping-ranges.md) - Handle overlapping edit ranges
- [`edit-use-flatmap-for-conditional`](references/edit-use-flatmap-for-conditional.md) - Use flatMap for conditional edits
- [`edit-add-imports-correctly`](references/edit-add-imports-correctly.md) - Add imports at correct position

### 7. Workflow Design (MEDIUM-HIGH)

- [`workflow-order-nodes-by-dependency`](references/workflow-order-nodes-by-dependency.md) - Order nodes by dependency
- [`workflow-use-matrix-for-parallelism`](references/workflow-use-matrix-for-parallelism.md) - Use matrix strategy for parallelism
- [`workflow-use-manual-gates`](references/workflow-use-manual-gates.md) - Use manual gates for critical steps
- [`workflow-validate-before-run`](references/workflow-validate-before-run.md) - Validate workflows before running
- [`workflow-use-conditional-steps`](references/workflow-use-conditional-steps.md) - Use conditional steps for dynamic workflows

### 8. Testing Strategy (MEDIUM)

- [`test-use-fixture-pairs`](references/test-use-fixture-pairs.md) - Use input/expected fixture pairs
- [`test-cover-edge-cases`](references/test-cover-edge-cases.md) - Cover edge cases in test fixtures
- [`test-use-strictness-levels`](references/test-use-strictness-levels.md) - Choose appropriate test strictness level
- [`test-update-fixtures-intentionally`](references/test-update-fixtures-intentionally.md) - Update test fixtures intentionally
- [`test-run-on-subset-first`](references/test-run-on-subset-first.md) - Test on file subset before full run

### 9. State Management (MEDIUM)

- [`state-use-for-resumability`](references/state-use-for-resumability.md) - Use state for resumable migrations
- [`state-make-transforms-idempotent`](references/state-make-transforms-idempotent.md) - Make transforms idempotent for safe reruns
- [`state-log-progress-for-observability`](references/state-log-progress-for-observability.md) - Log progress for long-running migrations

### 10. Security and Capabilities (LOW-MEDIUM)

- [`security-minimize-capabilities`](references/security-minimize-capabilities.md) - Minimize requested capabilities
- [`security-validate-external-inputs`](references/security-validate-external-inputs.md) - Validate external inputs before use
- [`security-review-before-running-third-party`](references/security-review-before-running-third-party.md) - Review third-party codemods before running

### 11. Package Structure (LOW)

- [`pkg-use-semantic-versioning`](references/pkg-use-semantic-versioning.md) - Use semantic versioning for packages
- [`pkg-write-descriptive-metadata`](references/pkg-write-descriptive-metadata.md) - Write descriptive package metadata
- [`pkg-organize-by-convention`](references/pkg-organize-by-convention.md) - Organize package by convention

## How to Use

Read individual reference files for detailed explanations and code examples:

- [Section definitions](references/_sections.md) - Category structure and impact levels
- [Rule template](assets/templates/_template.md) - Template for adding new rules

## Full Compiled Document

For a complete guide with all rules expanded, see [AGENTS.md](AGENTS.md).
Files in this package (54)
  • AGENTS.md 10 KB
  • README.md 4 KB
  • SKILL.md 8 KB
  • metadata.json 1 KB
  • assets/templates/_template.md 1 KB
  • references/_sections.md 2 KB
  • references/ast-check-null-before-access.md 2 KB
  • references/ast-explore-before-writing.md 1 KB
  • references/ast-field-access-for-structure.md 2 KB
  • references/ast-understand-named-vs-anonymous.md 1 KB
  • references/ast-use-kind-for-precision.md 1 KB
  • references/edit-add-imports-correctly.md 2 KB
  • references/edit-batch-before-commit.md 2 KB
  • references/edit-handle-overlapping-ranges.md 2 KB
  • references/edit-preserve-formatting.md 2 KB
  • references/edit-use-flatmap-for-conditional.md 2 KB
  • references/parse-early-return-non-applicable.md 2 KB
  • references/parse-handle-embedded-languages.md 2 KB
  • references/parse-provide-pattern-context.md 2 KB
  • references/parse-select-correct-parser.md 2 KB
  • references/pattern-avoid-overly-generic.md 1 KB
  • references/pattern-combine-with-rules.md 2 KB
  • references/pattern-ensure-idempotency.md 2 KB
  • references/pattern-use-constraints.md 2 KB
  • references/pattern-use-meta-variables.md 2 KB
  • references/pattern-use-relational-patterns.md 2 KB
  • references/pkg-organize-by-convention.md 2 KB
  • references/pkg-use-semantic-versioning.md 2 KB
  • references/pkg-write-descriptive-metadata.md 2 KB
  • references/security-minimize-capabilities.md 2 KB
  • references/security-review-before-running-third-party.md 2 KB
  • references/security-validate-external-inputs.md 2 KB
  • references/semantic-cache-cross-file-results.md 2 KB
  • references/semantic-check-null-results.md 2 KB
  • references/semantic-use-file-scope-first.md 2 KB
  • references/semantic-verify-file-ownership.md 2 KB
  • references/state-log-progress-for-observability.md 2 KB
  • references/state-make-transforms-idempotent.md 2 KB
  • references/state-use-for-resumability.md 2 KB
  • references/test-cover-edge-cases.md 2 KB
  • references/test-run-on-subset-first.md 2 KB
  • references/test-update-fixtures-intentionally.md 2 KB
  • references/test-use-fixture-pairs.md 2 KB
  • references/test-use-strictness-levels.md 2 KB
  • references/traverse-cache-repeated-lookups.md 2 KB
  • references/traverse-single-pass-collection.md 2 KB
  • references/traverse-use-find-vs-findall.md 1 KB
  • references/traverse-use-siblings-efficiently.md 2 KB
  • references/traverse-use-stopby-for-depth.md 2 KB
  • references/workflow-order-nodes-by-dependency.md 2 KB
  • references/workflow-use-conditional-steps.md 2 KB
  • references/workflow-use-manual-gates.md 2 KB
  • references/workflow-use-matrix-for-parallelism.md 2 KB
  • references/workflow-validate-before-run.md 2 KB

Versions

The database has no other skills named codemod.

Database snapshot: 13.11.2026 · package version 235ae343c9a3 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100jscodeshift
    jscodeshift codemod development best practices from Facebook/Meta. This skill should be used when writing, reviewing, or debugging jscodeshift codemods. Triggers on tasks involving AST transformation, code migration, automated refactoring, or codemod development.
  • 100codemod-react-pipeline
    Guided, scripted pipeline for running JSX/TSX/React codemods safely across large legacy codebases. Use when you need to scaffold a codemod, dry-run it, validate its findings, and apply it across many files (50 to 100k+) without breaking the build. Walks the full inner/outer loop…
  • 100ast-grep
    Searches and rewrites syntax with ast-grep. Use for AST-pattern codemods or authoring, testing, and configuring structural lint rules.
  • 100ast-grep
    Code search, analysis, and refactoring using ast-grep (sg). Use for AST-based code modifications, structural search, and linting.
  • 100ast-grep
    Searches and rewrites code by AST shape across 25 languages. Use when the target is a syntax pattern (every call/class/import shaped like X, a codemod, a YAML rule) rather than literal text; for plain strings, comments, or filenames, use rg.
  • 90migrasutra-codemod-pilot
    Use when migration work needs the safe automated code transformations specialist: evaluate codemod tooling and prepare dry-run patches inside isolated workspaces with no unreviewed source mutations.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.