CC-101 · Module 3

Skill Engineering

5 min read

Skills are Claude Code's most underutilized superpower. Anthropic published a 33-page guide on skill design — the depth tells you how important they consider this feature. A skill is more than a saved prompt. It's a three-layer progressive disclosure system that Claude loads just-in-time, keeping your context window clean while giving Claude deep domain expertise exactly when it needs it.

  1. Level 1: YAML Front Matter Always loaded in the system prompt. Contains only the skill name, description, and trigger words. Must be under 1,000 characters. This is the 'business card' that tells Claude whether to investigate further. If this is vague, Claude will never invoke your skill.
  2. Level 2: Core Instructions Loaded when Claude has confidence the skill matches the current task. Contains the procedural steps, checklists, and decision logic. This is where your SOP lives — the actual workflow broken into numbered steps with explicit criteria.
  3. Level 3: Linked Files Loaded only when Claude needs to execute. Python scripts, reference data, templates, and assets. These are the 'hands' that do the actual work. Kept separate so they don't bloat context until they're needed.

The YAML front matter is the make-or-break section. It must answer two questions perfectly: what does this skill do, and when should it be invoked. Bad descriptions kill skills before they're ever used. 'Helps with projects' is useless — every skill helps with projects. 'Cleans, validates, and transforms CSV files for analysis — use when user says clean the CSV, fix my data, or prepare the spreadsheet' gives Claude clear trigger words and a specific scope.

Do This

  • Write descriptions like 'Analyzes Figma design files and generates developer handoff documents. Use when user uploads .fig files or asks for design-to-code handoffs.'
  • Include 3-5 trigger words or phrases that should invoke the skill
  • Add event triggers — 'also invoke when user uploads a CSV file'
  • Test in a fresh terminal session to verify triggering works

Avoid This

  • Write 'helps with projects' or 'processes documents and analyzes data'
  • Use buzzwords like 'implements sophisticated multi-paradigm transformation pipeline'
  • Skip trigger words — Claude needs hints, not telepathy
  • Test in an existing session where context might accidentally trigger the skill

If something is done more than twice, it deserves to be a skill. The workflow: do the task manually once with Claude, observe what worked, then tell Claude to crystallize that process by doing a reverse meta-prompt — 'Go through the process we just completed. Crystallize exactly how you went from A to B. Ignore all the noise. Fix that in a skill.' This captures not just the steps but the specific decisions and error-handling that emerged organically.