Skip to content

tobihagemann/turbo / claude/skills/write-skill

write-skill

Verified

Create or update a skill that extends Claude's capabilities. Use when the user asks to "create a skill", "make a new skill", "write a skill for...", or "update this skill".

FileKindSize
SKILL.mdskill md9.9 KB
references/composition.mdmarkdown4.6 KB
references/evaluation.mdmarkdown3.9 KB
references/harness.mdmarkdown2.9 KB
references/principles.mdmarkdown7.3 KB
references/scripts.mdmarkdown4.4 KB
references/skill-reviewer.mdmarkdown5.7 KB
references/structure.mdmarkdown9.4 KB
references/tools.mdmarkdown28.1 KB
references/workflows.mdmarkdown8.0 KB
references/writing.mdmarkdown8.1 KB

references/skill-reviewer.md

View on GitHub
# Skill Reviewer Guidelines

Review and improve skills for maximum effectiveness and reliability.

## Contents

- Review Process
  - 1. Locate and Read Skill
  - 2. Validate Structure
  - 3. Evaluate Description (Most Critical)
  - 4. Assess Content Quality
  - 5. Check Progressive Disclosure
  - 6. Review Supporting Files (if present)
  - 7. Identify Issues
- Quality Standards
- Output Format
  - Summary
  - Description Analysis
  - Content Quality
  - Progressive Disclosure
  - Issues by Severity
  - Positive Aspects
  - Overall Rating
  - Priority Recommendations

## Review Process

### 1. Locate and Read Skill

- Find SKILL.md file
- Read frontmatter and body content
- Check for supporting directories (references/, scripts/, assets/)

### 2. Validate Structure

- Frontmatter format (YAML between `---`)
- Required fields: `name`, `description`
- Body content exists and is substantial

### 3. Evaluate Description (Most Critical)

- **Trigger Phrases**: Does description include specific phrases users would say?
- **Third Person**: Avoids first/second person ("I can help you", "You can use this"). Imperative form ("Use when...") is fine.
- **Specificity**: Concrete scenarios, not vague
- **Length**: Flag a description under 50 characters or over 200 characters, counting the parsed value without its quotes and escape backslashes
- **Example Triggers**: Lists specific user queries that should trigger skill

### 4. Assess Content Quality

- **Word Count**: SKILL.md body should stay under about 3,000 words (lean, focused). Flag a body over it as minor when it holds content a typical run does not read
- **Project Conventions**: Check the skill against the skill conventions stated in the instruction files governing its location (each CLAUDE.md from the root of the project containing the skill down to the skill's directory, the files they import, and that project's `.claude/rules/`), and flag each deviation
- **Writing Style**: Imperative/infinitive form ("To do X, do Y" not "You should do X")
- **Instructions vs documentation**: Every paragraph should tell the agent what to do. Flag prose that only describes, frames, or contextualizes the skill for a human reader — it is drift, not instruction.
- **Lean baseline comparison**: Pick the simplest existing skills in the same collection (ones that open with a one-line purpose and jump straight into Task Tracking or Step 1) and compare the reviewed skill against that baseline. If the reviewed skill has multiple paragraphs of context before the first instruction while its neighbors do not, flag the excess as narrator prose.
- **Organization**: Clear sections, logical flow
- **Specificity**: Concrete guidance, not vague advice
- **Done-conditions**: A step whose end is not self-evident states a checkable condition for being finished. Flag a step that ends on a vague bound, or that names a deliverable without the set it must cover
- **No-op sentences**: Flag an instruction the agent would follow without being told, and recommend deleting the whole sentence. Leave a line the project's conventions mandate and a guardrail against the agent's own drift

### 5. Check Progressive Disclosure

- **Core SKILL.md**: Essential information only
- **references/**: Detailed docs moved out of core
- **scripts/**: Utility scripts if needed
- **assets/**: Output resources separate from documentation
- **Pointers**: SKILL.md references these resources clearly

### 6. Review Supporting Files (if present)

- **references/**: Check quality, relevance, organization
- **scripts/**: Check scripts are executable and documented
- **assets/**: Verify assets are used and referenced

### 7. Identify Issues

Categorize by severity (critical/major/minor).

Anti-patterns to watch for:
- Vague trigger descriptions
- Content a typical run does not read kept in SKILL.md (should be in references/)
- First/second person in description ("I can help you", "You can use this")
- Missing key triggers
- No references when they'd be valuable
- **Narrator prose**: meta-framing that explains the file to its own reader ("This SKILL.md is the router..."), cross-skill commentary ("This is the sibling of /other-skill"), marketing copy ("X is the structured alternative to Y"), architecture commentary that restates what the instructions already convey, historical rationale, and tautological boundary statements ("X is Y's job; this skill only does Z")
- **"Step 0" as mode detection**: a numbered step that only inspects caller input or picks a mode. Should be folded into the opening prose, not given a step heading

## Quality Standards

- Description must have strong, specific trigger phrases
- SKILL.md should be lean (under about 3,000 words, or over it only through content every typical run reads)
- Skill follows the skill conventions its project states
- Writing style must be imperative/infinitive form
- Progressive disclosure properly implemented
- All file references work correctly

## Output Format

When reviewing a skill, produce a report with:

### Summary
Overall assessment and word counts.

### Description Analysis
- Current description
- Issues found
- Recommended improvements (with suggested text)

### Content Quality
- Word count assessment
- Project conventions assessment
- Writing style assessment
- Organization assessment

### Progressive Disclosure
- Current structure (file counts, word counts)
- Assessment of whether disclosure is effective
- Recommendations for better organization

### Issues by Severity

#### Critical
Issues that prevent the skill from working correctly.

#### Major
Issues that significantly reduce skill effectiveness.

#### Minor
Polish and optimization suggestions.

### Positive Aspects
What the skill does well.

### Overall Rating
Pass / Needs Improvement / Needs Major Revision

### Priority Recommendations
Top 3 fixes ordered by impact.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall