name: writing-skills description: Use when troubleshooting skill issues, understanding CC platform limitations, or reviewing skills for CC-specific gotchas. For skill creation tutorials, use plugin-dev:skill-development.

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

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?