Skill Writing Tips

A Skill is not a "prompt template" — it's a workflow instruction that drives an AI Agent to complete real tasks. The AI reads your SKILL.md, then uses tools (read/write files, run scripts, control a browser…) to get things done. The key to writing a great Skill is translating your expert judgment into steps the AI can execute.

1. description Is the Most Important Field

description determines when the AI invokes your Skill. Write it poorly, and the Skill will never be triggered — no matter how good the body is.

Principles:
- Start with what the Skill does
- List trigger keywords and scenarios — the more specific, the better
- Over-trigger is fine; missing triggers is not

# ❌ Too vague
description: 'Helps with code review'

# ✅ Specific, accurate triggers
description: 'Reviews code for bugs, style issues, and performance problems.
  Use whenever the user pastes code and asks for feedback, says "review this",
  "check my code", "what's wrong here", or wants a PR review — even if they
  just say "look at this function".'

Wrap description in single quotes to avoid YAML parse errors from colons and other special characters.

2. The Body Describes a Workflow, Not a Persona

The Skill body is not a system prompt. Don't write "You are an expert with 10 years of experience in…" role descriptions.

The body should describe: what to do, in what order, with what tools, and what to output.

# Code Reviewer

## Steps

1. Read the code or file path provided by the user
2. Check each of the following:
   - Obvious bugs or missing edge cases
   - Clear naming and readable logic
   - Performance risks (N+1 queries, unnecessary loops, etc.)
3. Output findings by severity: 🔴 Must Fix / 🟡 Suggested / 🟢 Optional
4. Include a fix suggestion and example code for each issue

Use imperative sentences ("Read", "Check", "Output") — the AI executes them more reliably.

3. Make the Skill Actually Do Things, Not Just Answer

A great Skill drives the AI to use tools and complete tasks — not just generate a text response.

  • Read/write files: analyze codebases, generate reports, update configs
  • Run scripts: process data, call APIs, batch operations
  • Control the browser: scrape pages, fill forms, take screenshots
## Steps

1. Use the glob tool to find all `*.rb` files in the project
2. Use file_reader to read each file and check for `TODO` comments
3. Summarize the results and write them to `todo_report.md`
4. Tell the user the report is ready at `./todo_report.md`

If your Skill only "generates text", its value is limited. Make it complete the whole task.

4. Encode Your Expertise — Don't Let the AI Guess

The biggest value of a Skill is encoding your domain knowledge and standards. Don't let the AI improvise — tell it exactly what your criteria are.

# ❌ Vague — AI will use generic standards
Check code quality

# ✅ Explicit — AI follows your team's rules
Check the following (per our team conventions):
- All public methods must have comments
- Never use `rescue Exception` — only `rescue StandardError`
- All database queries must include a `limit` to prevent full table scans
- Variable names must be at least 3 characters (except loop vars i/j/k)

5. Put Large Content in references/, Keep the Body Lean

Keep your SKILL.md body under 500 lines. Move large reference content (style guides, data dictionaries, template libraries) into a references/ directory, and specify in the body when to read them:

## Review Standards

See `references/code-style-guide.md` for detailed rules — read this file before starting the review.

Put reusable scripts in scripts/ (Ruby recommended) instead of inline shell commands in the body:

## Data Processing

Run `ruby SKILL_DIR/scripts/parse_report.rb <input_file>` to process the input data.

6. Start with One Real Scenario, Then Generalize

Don't try to write a "universal" Skill from day one. Nail one specific scenario first, then expand:

  1. Pick the most familiar typical scenario and do it well
  2. Test with /skill-creator: run 3–5 real inputs and check if the output matches your expectations
  3. Fix gaps in SKILL.md: add clarifications when the AI deviates, rather than relying on users to figure it out
  4. Expand once satisfied: add edge case handling and support more scenarios

7. Iterate with /skill-creator, Not Gut Feeling

/skill-creator has a built-in eval workflow: write test cases → run comparisons (with Skill vs. without) → review results → revise → repeat.

This is the most reliable way to improve a Skill — far more efficient than tweaking prompts by intuition.

Skill Basics
Brand Customization