Writing Skills

Scope

This skill covers Claude Code platform gotchas and limitations. For different purposes, use:

• Comprehensive tutorials: plugin-dev:skill-development
• TDD methodology: superpowers:writing-skills
• This skill: Bug workarounds, version-specific behavior, issue tracking

Facts

• The frontmatter name is what appears in autocomplete list when typing / in session. So name: foo would allow user to submit /foo to trigger that skill.
• The skill directory name appears printed in session when skill is activated by the agent. E.g. dir /foobar would yield e.g.

  ⏺ Skill(foobar)
  ⎿  Initializing…
  

• Skill(foobar) is also the syntax for granting permission to the skill in config
• Development Related
  • Skills created or modified in ~/.claude/skills or .claude/skills are immediately available without restarting the session (added in v2.1.0)

Key Rules (from Anthropic guide)

Frontmatter:

• name: Max 64 chars, lowercase letters/numbers/hyphens only, no reserved words ("anthropic", "claude")
• description: Max 1024 chars, non-empty, third person, critical for discovery
  • Good: "Processes Excel files and generates reports"
  • Avoid: "I can help you process Excel files"
• Use gerund form (verb + -ing) for names: processing-pdfs, analyzing-spreadsheets

Body:

• Keep SKILL.md under 500 lines
• "Claude is already very smart. Only add context Claude doesn't already have."
• Paths are relative to skill directory — use scripts/foo not .claude/skills/my-skill/scripts/foo

File Structure

my-skill/
├── SKILL.md          # Main (<500 lines)
├── reference/        # Detailed docs (loaded on demand)
├── scripts/          # Executable (zero-token)
└── assets/           # Static files (banners, templates)

Naming: Directory name = skill name (kebab-case). Opening # Title = titleized skill name.

Skill Body Headings

| Heading | Purpose | |---------|---------| | ## CRITICAL | Safety rules at top | | ## Use Cases | Refine when skill applies | | ## Requirements | Deps, env vars, how to handle absence | | ## Steps | Sequential workflow | | ## Operations | Menu of actions | | ## Examples | User prompt → Claude action | | ## Reference | Internal docs | | ## Notes | Gotchas, tips | | ## Appendix | Implementation details |

Tools for Skills

| Tool | Purpose | Reference | | --------------- | ------------------------------------ | -------------------------------------------------------------------------------- | | AskUserQuestion | Interactive prompts (max 4 options) | tool-ask-user-question.md | | TodoWrite | Task checkboxes | tool-todo-write.md | | Bash | Execute bundled scripts (zero-token) | pattern-script-bundling.md | | Read | Load reference files on demand | pattern-progressive-disclosure.md |

Frontmatter Options

| Field | Purpose | Reference | | -------------------------- | --------------------------- | ------------------------------------------------------------ | | name, description | Identity and discovery | config-frontmatter.md | | allowed-tools | Skip permission prompts | config-allowed-tools.md | | context: fork | Run in isolated subagent | config-context-fork.md | | hooks | PreToolUse/PostToolUse/Stop | config-hooks.md | | user-invocable | Show in slash menu | config-frontmatter.md | | disable-model-invocation | User-triggered only | config-frontmatter.md |

Platform Limitations

Cannot control:

• Collapsed/expanded state of tool output - see limitation-output-collapse.md
• Terminal theme/colors
• Streaming behavior
• Custom UI widgets
• Status line refresh from skills - see feature-status-line.md

Patterns

| Pattern | Reference | | ---------------------- | -------------------------------------------------------------------------------- | | Code examples | pattern-code-examples.md | | Progressive disclosure | pattern-progressive-disclosure.md | | Script bundling | pattern-script-bundling.md |

When Reviewing Skills

Apply criteria from both this skill (CC platform) and superpowers:writing-skills (methodology).

Platform checklist:

• [ ] Frontmatter valid? (name format, description length, third person)
• [ ] SKILL.md under 500 lines?
• [ ] Reference files used for detailed content?
• [ ] Code examples have language tags?
• [ ] Known limitations acknowledged? (output collapse, status line)
• [ ] Hooks correctly structured if used?
• [ ] allowed-tools syntax correct if used?

Methodology checklist (from superpowers:writing-skills):

• [ ] CSO applied? (Claude-Specific Optimization)
• [ ] Token-efficient structure?
• [ ] Clear trigger conditions in description?