Lesson 21: Skills: Reusable Workflows

Day 21 of 50 · ~7 min read · Phase 3: Customization

The Opening Question

You've created custom slash commands for your project. You've written rules documenting your conventions. You've accumulated memory about what works and what doesn't.

Now imagine this: a colleague is working on a similar project. They're about to make all the same mistakes you've already solved. They're about to write the same commands you've already written.

Here's the question: What if your best prompts and workflows could be packaged and shared?

Discovery

Let's explore how skills work and why they matter.

Question 1: What exactly is a skill?

A skill is a reusable bundle of instructions that Claude can load on demand.

But let's be more concrete. What's actually in a skill?

Pause and think: If you were packaging "how to add error handling to an API" into something shareable, what would you include?

A skill is just a markdown file (with some structure) that contains:

1. Instructions — Step-by-step guidance for completing a task
2. Context — What Claude needs to know to do the task well
3. Constraints — Rules about how to approach it
4. Examples — Sample outputs or patterns to follow

For example, here's a simple skill for "add logging to a function":

# Add Logging to a Function

## What this does
Adds structured logging to a function, following the project's logging conventions.

## Prerequisites
- The project uses Winston for logging
- Logging calls should include: timestamp, level, function name, operation, result

## Steps
1. Import the logger: `import logger from './logger'`
2. At the function start, log: `logger.info('FunctionName starting', { args })`
3. At success, log: `logger.info('FunctionName completed', { result })`
4. In catches, log: `logger.error('FunctionName failed', { error })`

## Example
Before:
```javascript
function processUser(id) {
  return db.users.find(id);
}

After:

function processUser(id) {
  logger.info('processUser starting', { id });
  const result = db.users.find(id);
  logger.info('processUser completed', { result });
  return result;
}

This is a skill. When you ask Claude to add logging, it can load and follow this skill.

### Question 2: How are skills different from rules and CLAUDE.md?

Good question. They're related but serve different purposes.

**CLAUDE.md** documents what your project is (tech stack, patterns, philosophy). It's passive — it's just information.

**Rules** document how to work in specific directories. Also passive — they're guidelines.

**Skills** are active instructions for specific tasks. They say: "When someone asks to do X, here's exactly how to do it."

Think of it this way:

- CLAUDE.md: "We use TypeScript and async/await"
- Rules: "In the `/api` directory, all endpoints validate input with Zod"
- Skill: "To add a new endpoint: create a file, export a handler, add it to the router, write tests"

Skills are task-oriented. They assume you *know* the conventions (because you read CLAUDE.md and the rules) and now you want to *do* a specific task.

### Question 3: Where do skills live, and how does Claude find them?

Skills live in `.claude/skills/` in your project.

Each skill is a markdown file with a specific structure. The filename becomes the skill name. For example:

.claude/skills/ ├── add-error-handling.md ├── create-database-migration.md ├── set-up-ci-cd.md └── optimize-query.md

When you ask Claude to do something related to one of these, Claude can load the relevant skill.

But here's the clever part: **Claude doesn't load the full text of every skill from the start.** That would blow up the context window.

Instead:
1. Claude sees a *summary* of available skills (name and one-line description)
2. When you ask for something that matches a skill, Claude loads the full skill file
3. Claude uses that detailed instruction to complete the task

This way, skills are modular. You can have dozens of them without slowing Claude down.

### Question 4: How do you create and refine skills?

Skills are markdown files, so you can write them by hand. But there's a workflow to making them good:

**First iteration:** You write a simple skill documenting how to do a task.

```markdown
# Add Error Handling

To add error handling:
1. Wrap code in try/catch
2. Log errors
3. Return error response

Testing: You use the skill a few times. Claude follows the instructions. Sometimes Claude gets stuck or confused.

Refinement: Based on what went wrong, you improve the skill.

# Add Error Handling

## When to use this
When a function might throw an error and needs to handle it gracefully.

## Prerequisites
- All async functions wrapped in try/catch
- Use the centralized error handler (see error-handling.md)
- Log with context about what failed

## Steps
1. Wrap the operation in try/catch:
   ```javascript
   try {
     // operation
   } catch (error) {
     // handle
   }

2. Check if error is expected (validation) or unexpected (bug)
3. Log appropriately
4. Return or throw

**Sharing:** Once a skill is solid, you can share it. Copy the skill file to a colleague's project. Or publish it somewhere your team can discover it.

The best skills are ones you've tested and refined in real work, not ones you write in theory.

> Pause and think: What tasks do you find yourself repeating? Those are candidates for skills.

---

## The Insight

Here's what's really happening with skills:

> Skills are the bridge between Claude Code's general intelligence and your specific workflows. They let you encode your hard-won knowledge about "how we do things" into reusable instructions that Claude can apply consistently. Over time, a good collection of skills becomes institutional knowledge that your whole team can use and improve on.

**The mental model:** Skills are like **playbooks or runbooks in a large organization**. A runbook for "respond to a database outage" documents the steps: check logs, alert the team, roll back, etc. A skill for "add logging to a function" does the same thing for code. They're living documents that get better as you use them and learn from mistakes.

---

## Try It

Let's create your first skill.

1. **Create the skills directory:**
   ```bash
   mkdir -p .claude/skills

2. Pick a task you do repeatedly. Examples:

   • Creating a new React component with tests
   • Adding a new database migration
   • Creating an environment configuration file
   • Optimizing a slow query
   • Adding validation to an API endpoint

3. Write a skill for it. Create a file:

   cat > .claude/skills/create-component.md << 'EOF'
   # Create a React Component
   
   ## What this does
   Creates a new React component with the project's standard structure and tests.
   
   ## Prerequisites
   - Component goes in `/src/components/[ComponentName]/`
   - Every component needs a test file
   - Use TypeScript
   - Follow ESLint rules
   
   ## Steps
   1. Create directory: `/src/components/ComponentName/`
   2. Create `index.tsx` with component export
   3. Create `ComponentName.test.tsx` with at least one test
   4. Add the component to `/src/components/index.ts` exports
   
   ## Template
   index.tsx:
   ```typescript
   export const ComponentName = () => {
     return <div>...</div>;
   };
   

   ComponentName.test.tsx:

   import { render, screen } from '@testing-library/react';
   import { ComponentName } from './index';
   
   describe('ComponentName', () => {
     test('renders', () => {
       render(<ComponentName />);
       expect(screen.getByText(/component/i)).toBeInTheDocument();
     });
   });
   

   EOF

4. Test the skill. Ask Claude to create a component:

   claude
   

   Then: "Create a new component called Button using the create-component skill"

5. Refine it. If Claude got something wrong, update the skill file and try again.

Key Concepts Introduced

Bridge to Lesson 22

You've now learned how to customize Claude Code within your project — through CLAUDE.md, permissions, commands, rules, memory, and skills. These are individual pieces.

Next lesson is a lab: This is where you put it all together.

The mission: Take a real codebase and set it up for optimal Claude Code collaboration. Create CLAUDE.md, configure permissions, and build a custom skill from scratch.

You'll integrate everything you've learned in Phase 3 into one working system.

← Back to Curriculum · Lesson 22 →