Writing Skills

Writing Skills

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)

Overview

This skill covers Claude Code platform specifics. For skill design methodology (CSO, TDD, testing), also invoke superpowers:writing-skills.

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."

File Structure

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

Tools for Skills

Frontmatter Options

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

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?