Building Skills

What Is a Skill?

A skill is a markdown file that encodes a complete workflow. You write it once, and Claude Code executes it whenever the right keywords appear in your prompt.

Think of skills as recipes. Instead of telling Claude Code "pull my calendar, check Jira for open tickets, scan Slack for recent threads, then compile a briefing" every time you have a meeting, you write a meeting-prep skill once. Next time you say "prep for my 1:1 with Sarah," Claude Code finds the skill, follows the steps, and delivers a structured briefing.

Skills are the building blocks of a Claude Code operating system. They turn scattered knowledge into repeatable, composable workflows.

Anatomy of a Skill

Every skill is a markdown file with a clear structure: a description at the top, trigger keywords, and step-by-step instructions.

# Meeting Prep

Pre-meeting context gathering across all connected systems.
Pulls recent interactions, open items, and talking points
for any person or topic.

Triggers: "meeting prep", "prep for my meeting",
"meeting with X", "prep for 1:1", "before my meeting"

## Steps

1. Identify the person or topic from the user's prompt
2. Search Slack for recent threads involving them
3. Check Jira/Linear for shared open tickets
4. Pull any relevant notes from the knowledge base
5. Compile a structured briefing:
   - Recent interactions (last 7 days)
   - Open items and blockers
   - Suggested talking points
   - Decisions that need alignment

## Output Format

Deliver as a markdown document with clear sections.
Lead with the most actionable items. Skip anything
older than 2 weeks unless it's unresolved.

The trigger keywords are how Claude Code knows when to activate this skill. When your prompt contains "meeting prep" or "prep for 1:1," the skill loads automatically and Claude Code follows the instructions.

How to Create Your First Skill

Step 1: Identify a task you repeat. Look for anything you explain to Claude Code more than twice. Formatting a PR description. Running a specific test suite. Generating a weekly status report. If you keep saying "remember, do it like last time," that's a skill waiting to be written.

Step 2: Write the steps as markdown. Be specific. Include the output format you want, the sources to check, the order of operations. Write it as if you're training a sharp junior developer who has never seen your workflow.

Step 3: Save it as a markdown file. Drop it in the right directory (see below) and add trigger keywords that match how you naturally ask for the task.

Step 4: Test and iterate. Run the skill a few times. When Claude Code misses a step or gets the format wrong, update the skill file. Skills improve through use.

Where Skills Live

Skills can live at two levels:

Project-level skills are specific to a codebase. User-level skills follow you everywhere.

Built-in vs Custom Skills

Claude Code ships with some built-in capabilities, but the real power comes from custom skills tailored to your workflow. Built-in skills handle generic tasks like code review or test generation. Custom skills encode your team's specific processes, your company's PR format, your preferred debugging sequence.

Tips for Writing Good Skills

Start simple. Your first skill should be 10-15 lines. Don't try to encode a 30-step workflow on day one.

One skill per workflow. A "deploy" skill and a "rollback" skill are better than a "deploy-and-maybe-rollback" skill. Keep them focused and composable.

Iterate based on corrections. When you correct Claude Code mid-skill, update the skill file immediately. The skill should absorb every lesson.

Be explicit about output format. "Generate a report" is vague. "Generate a markdown table with columns: ticket, status, owner, next action" gets you consistent results every time.

Use trigger keywords that match natural language. You want the skill to activate when you ask for it casually, not when you remember the exact command name.