claude-plugins
← Back to the collection

Your job will be to review the skill at $ARGUMENTS for improvement opportunities.

Look for the skill at the provided path, or in .claude/skills/$ARGUMENTS/ or .claude/skills/monorepo-$ARGUMENTS/.

Current Skills Documentation

Codex: this path resolves under Claude Code; substitute the directory containing this SKILL.md.

Skills docs cached at: !SKILL_DIR="${CLAUDE_SKILL_DIR}"; bash "$SKILL_DIR/scripts/fetch-docs.sh"

Read the docs from that path. If the path doesn’t exist or the file is empty, tell the user the docs URL is unreachable and stop.

Step 1: Read the Skill

Read SKILL.md and all bundled files/scripts/etc at the skill path.

Key areas to emphasize:

  1. Frontmatter validity: Validate the SKILL.md YAML frontmatter before reviewing anything else. Use the same parser family as Claude/Codex loaders when possible, for example: 
    ruby --disable-gems -ryaml -e 'text = File.read(ARGV.fetch(0)); abort "missing frontmatter" unless text.start_with?("---\n"); fm = text.split("---\n", 3)[1]; YAML.safe_load(fm, permitted_classes: [], permitted_symbols: [], aliases: false); puts "frontmatter ok"' /path/to/SKILL.md

    Flag missing frontmatter, invalid YAML, and loader-sensitive plain scalars in description, when_to_use, argument-hint, or allowed-tools that contain YAML-sensitive characters such as brackets, braces, commas, backticks, colons, shell globs, ${...}, or command patterns. Recommend quoting these values without changing their text or the skill behavior.

  2. Inject dynamic context: Does this skill hardcode context that could be dynamic? Check for opportunities to use !commandsyntax (single-line) or `! fenced blocks (multi-line) to inject runtime context — current date, git branch, environment info, project metadata, etc. These run at skill load time and inline the output before Claude sees the prompt. Flag any static values that would be more accurate or useful if computed on the fly. This is a great way to reduce the size of the skill and make it more maintainable.
  3. Script opportunities: Bash/sh scripts that could improve reliability and save on tokens.
  4. when_to_use frontmatter: Is the description doing double duty as both a summary and a list of trigger phrases? If so, the trigger phrases should move to when_to_use to keep the description focused. Both fields are concatenated for matching (capped at 1,536 chars combined). (This is not relevant for disable-model-invocation: true skills)
  5. Skill size & compaction: Is SKILL.md over 500 lines? Could reference material move to supporting files? If the skill is large and expected to stay active, are critical instructions front-loaded (only first 5,000 tokens survive compaction)?
  6. Invocation control: Does disable-model-invocation / user-invocable match the skill’s purpose? Side-effect workflows should be user-only. Background knowledge should be model-only.
    • paths: gotcha: The docs describe paths: as limiting auto-activation, but it also gates /slash-command registry lookup. If the skill has disable-model-invocation: true (user-invocable only) and the user’s cwd doesn’t match the glob, the slash command silently disappears from the registry — it can’t be invoked at all. Never recommend paths: for disable-model-invocation: true skills. Only suggest it for purely model-invocable skills where narrowing auto-trigger to specific file contexts is the goal.
  7. Tool permissions: Are allowed-tools entries scoped with patterns (e.g., Bash(git *)) or overly broad (bare Bash)?
  8. String substitutions: Is the skill using ARGUMENTS, CLAUDE_SKILL_DIR, CLAUDE_PLUGIN_ROOT, CLAUDE_CODE_SESSION_ID variables where they’d add value? (CLAUDE_CODE_SESSION_ID is exported into every Bash subprocess by Claude Code >= 2.1.132 and equals the resumable session/transcript ID; it is Claude-only — Codex sets CODEX_THREAD_ID instead.)
  9. Subagent execution: Does the skill use context: fork when it shouldn’t (needs conversation context or interactive follow-up), or skip it when it should (self-contained task that doesn’t need history)? context: fork always forks — it’s a directive, not a hint. The skill content becomes the subagent’s prompt with no conversation history.

Step 2: Understand Intent, Then Evaluate

ultrathink

Before evaluating anything, determine what this skill is meant to do and how it’s meant to be used. Read the frontmatter, the description, the instructions, and think about:

If the skill’s intent isn’t clear from reading it, ask the user before proceeding.

Now evaluate — compare against fetched documentation. Focus solely on actionable improvements — no praise or congratulations. Let your understanding of the skill’s intent guide which recommendations are appropriate.

Extract key recommendations for: progressive disclosure, utility scripts, validation loops, metadata, frontmatter validation, content organization, inline script execution, and new patterns.

  1. Summary: Quick assessment (1-2 sentences)
  2. Issues: Problems with specific line references
  3. Recommendations: Prioritized improvements with code/text examples

Output the review as a markdown file at /tmp/skill-review-{skill-name}.md.

Step 3: Challenge Your Review

ultrathink

Re-read your review against the docs and the skill. For each recommendation, ask:

Update the review file — remove recommendations that don’t hold up, add any you missed.

Now present the findings to the user and open the review file in their editor.

Step 4: Apply the Recommendations

Ask the user if they would like to apply the recommendations. Keep in mind, when they say yes, they may have modified the review file, so you should re-read the skill and review the file again.