CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

ast-grep

AST-aware structural code search and rewrite via ast-grep.

Quality

75%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./optional-skills/software-development/ast-grep/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

88%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This is a high-quality, operational skill body: copy-paste-ready commands throughout, an explicit dry-run-first workflow with validation and feedback loops for a batch-rewrite tool, and well-signaled one-level-deep references. The only notable defects are deliberate-but-token-costly repetition of the core invariants and two referenced install scripts that are absent from the bundle.

Suggestions

Ship the referenced install.sh and install.ps1 (or drop the claims about them and point to references/install.md), since the body and the helper's error hints both direct the user to files that do not exist.

DimensionReasoningScore

Conciseness

The body is dense and tool-specific with no explanations of concepts Claude already knows — every section teaches ast-grep behavior (wildcards, two-pass writes, --lang inference), fitting 'efficient; minor instances of over-explanation that could be trimmed'. It falls short of 5 because the critical gotchas (two-pass trick, regex misuse, single-quoting) are each restated two to three times across 'Three things', the helper sections, and 'Invariants'.

4 / 5

Actionability

Every section delivers copy-paste-ready commands: 'python scripts/ast_grep_helper.py search 'console.log($MSG)' --lang ts src/', 'sg run -p ... -r ... --update-all src/', plus documented flags (--globs, -C, --json-out) and concrete debug idioms like '--debug-query=ast --stdin <<< ...'. Examples cover search, dry-run replace, apply, scan, validate, and the 0-match debugging path.

5 / 5

Workflow Clarity

The rewrite workflow is an explicit numbered sequence with validation and a feedback loop — search to confirm, dry-run, inspect the summary, 'If wrong: refine pattern, go back to step 1', then --apply, followed by 'git diff --stat' review — which is exactly the anchor-5 pattern. The 0-match section adds a prioritized diagnostic loop with error recovery ('Do not blindly retry'), satisfying the batch/destructive-operation validation requirement.

5 / 5

Progressive Disclosure

Structure is strong: a prioritized 'Required reading' list gives each of the 7 reference files a one-level-deep pointer with explicit read-when conditions, and the scripts/ helper is real and matches the body's claims. It misses 5 because the body references 'install.sh (POSIX) and install.ps1 (Windows)' as shipped platform scripts, but neither file exists in the bundle — a broken reference the helper script also points to.

4 / 5

Total

18

/

20

Passed

Description

53%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is concise, in third person, and accurately scoped to ast-grep's niche, but it reads as a definition rather than a trigger. It answers 'what' cleanly while omitting 'when' entirely, and it under-sells the tool's capabilities (scan rules, codemods, 25 languages) that would generate natural trigger matches.

Suggestions

Add a 'Use when...' clause naming concrete trigger phrases, e.g. 'Use when the user asks to find/rewrite code by structure, run a codemod, or apply bulk pattern-driven edits across many files.'

Include the natural synonyms users actually say — codemod, refactoring, find-and-replace, lint rules — so the skill triggers on phrasing beyond the technical term 'AST'.

Mention the additional capabilities (YAML lint rules/sg scan, 25 languages) to broaden trigger coverage and make specificity more comprehensive.

DimensionReasoningScore

Specificity

The description names the domain ("AST-aware structural code search") and two concrete actions ("search and rewrite") plus the tool name ("via ast-grep"), matching the 'names domain and 1-2 concrete actions' anchor. It is not a 4 because coverage stops at two verbs — scan/YAML lint rules, codemods, and multi-language rewriting capabilities go unmentioned.

3 / 5

Completeness

The 'what' is clear ("structural code search and rewrite via ast-grep") but there is no 'Use when...' clause or equivalent trigger guidance anywhere, which caps completeness at 3 per the rubric guideline. It cannot score 4 because the 'when' is entirely absent rather than merely vague.

3 / 5

Trigger Term Quality

Relevant keywords are present ("code search", "rewrite", "ast-grep", "AST") but natural phrases users actually say — "codemod", "refactor", "find and replace", "find every function that..." — are missing, matching the 'some relevant keywords but missing common variations or synonyms' anchor. Not a 2 because the terms present are on-target rather than generic filler.

3 / 5

Distinctiveness Conflict Risk

"AST-aware structural" plus the named binary carves a clear niche that plain grep/search skills do not occupy, fitting 'mostly distinct; minor overlap risk with closely related skills'. Not a 5 because "code search and rewrite" without an explicit when-clause could still pull queries aimed at ordinary text search or sed-style replacement.

4 / 5

Total

13

/

20

Passed

Validation

81%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 13 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

metadata_version

'metadata.version' is missing

Warning

metadata_field

'metadata' should map string keys to string values

Warning

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

13

/

16

Passed

Repository

NousResearch/hermes-agent

Path

optional-skills/software-development/ast-grep/SKILL.md

Reviewed

Table of Contents

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.