Welcome to Unit 3 of Skills — Extending Claude's Capabilities! You have made excellent progress; we have explored the Skills system fundamentals, understood when to create Skills versus using CLAUDE.md, and built two practical Skills from scratch. Now we are ready to tackle more sophisticated challenges.

In this lesson, we will explore advanced skill patterns and best practices. We will examine how advanced Skills coordinate multiple tools, learn to debug Skill selection, and discover when not to create a Skill. We will also establish design principles for maintainable, effective Skills.

By the end of this lesson, you will understand Skill architecture, common pitfalls to avoid, and the patterns that separate good Skills from great ones. Let's elevate our Skills to the next level!

What makes Skills advanced?

Advanced Skills differ from basic ones through sophisticated coordination. While basic Skills might read a file and write output, advanced Skills orchestrate multiple operations that build on each other: analyzing existing code, generating new files based on findings, and verifying results through execution.

The Multi-Tool Coordination Pattern:

Most advanced Skills follow a three-phase workflow:

1. Analysis Phase — Use Read to understand context (existing code, project standards, requirements)
2. Generation Phase — Use Write or Edit to create new content based on analysis
3. Verification Phase — Use Bash to test that generated content works correctly

Each phase depends on the previous one. The analysis informs what to generate, and verification confirms the generation succeeded. Let's see this pattern in action by building a real advanced Skill.

Let's build an api-tester skill that demonstrates these advanced patterns. We will walk through creating it, testing it, and observing how it coordinates multiple tools automatically.

Step 1: Ask Claude to create it

We start with a specific request that describes what we want:

> Create a skill that generates comprehensive API tests with edge cases and error handling

Claude responds by creating the Skill:

● Write(.claude/skills/api-tester/SKILL.md)
  ⎿ Wrote 55 lines to .claude/skills/api-tester/SKILL.md
    ---
    name: api-tester
    description: Generate comprehensive API tests including edge cases, error handling, and authentication tests
    allowed-tools: Read, Write, Edit, Bash
    ---
    
    # API Testing Skill
    
    ## When to Use
    - User asks to test API endpoints
    - User mentions "coverage" or "edge cases"
    - User wants to add tests to API routes
    
    ## Process
    1. Analyze endpoint (Read route handler)
    2. Check project standards (Read CLAUDE.md)
    3. Generate tests (Write test file)
    4. Verify tests pass (Bash run tests)

Notice the frontmatter specifies four tools (Read, Write, Edit, Bash) and the description includes keywords like "comprehensive," "edge cases," and "error handling." The process section outlines the three-phase workflow we discussed.

Step 2: Test the skill

After restarting Claude Code to load the new Skill, we make a request:

> Generate tests for the /users POST endpoint

Watch what happens:

● [Skill selected: api-tester]

● Read(routes/users.py)
  ⎿ Read 40 lines from routes/users.py
    // Analysis phase: Understanding the endpoint

● Read(CLAUDE.md)
  ⎿ Read 25 lines from CLAUDE.md
    // Analysis phase: Learning project standards

● Write(tests/test_users.py)
  ⎿ Wrote 85 lines to tests/test_users.py
    // Generation phase: Creating comprehensive tests

● Bash(pytest tests/test_users.py -v)
  ⎿ PASSED tests/test_users.py::test_creates_user
    PASSED tests/test_users.py::test_rejects_invalid_email
    PASSED tests/test_users.py::test_rejects_missing_name
    7 passed in 0.85s
    // Verification phase: Confirming tests work

What makes this advanced:

The Skill coordinated three tools automatically! It read two files to understand context, wrote a test file based on that analysis, and ran the tests to verify everything works. Each phase built on the previous one:

• Without the analysis (reading route and standards), it could not generate appropriate tests
• Without the generation (writing tests), there would be nothing to verify
• Without the verification (running tests), we would not know if the tests actually work

This is the multi-tool coordination pattern that defines advanced Skills. The Skill orchestrated a complete workflow that would normally require multiple manual steps.

How to See Which Skill Was Selected:

Claude explicitly indicates when it selects a Skill:

> Generate tests for the /users POST endpoint

● [Skill selected: api-tester]

The bracket notation [Skill selected: skill-name] appears whenever a Skill activates. You may also see Skill(skill-name) notation. No indicator means Claude used general knowledge without any Skill. This helps verify your Skill descriptions are working correctly.

Common Selection Problems and Fixes:

When Claude selects the wrong Skill or fails to select the right one, several issues might be at play:

Problem: Descriptions too similar

❌ description: Process documents
❌ description: Handle files

✅ description: Extract tables from PDF invoices
✅ description: Generate markdown docs from code

Fix: Use specific keywords unique to each Skill's domain.

Problem: Vague requests

❌ "Help with this file"
✅ "Extract tables from this PDF invoice"

Fix: Make requests specific to match Skill descriptions and "When to Use" triggers.

Problem: Name conflicts Similar names like api-helper and api-tester cause confusion. Fix: Use distinctive names that clearly indicate purpose.

Problem: Mismatched triggers Your "When to Use" section says "test endpoints" but you phrase requests as "check the API." Fix: Add trigger phrases that match how you actually talk: "User asks to check API functionality."

Testing Skills in Isolation:

If selection seems unreliable, temporarily move other Skills out of .claude/skills/ to isolate the issue. This helps identify which Skills conflict. Test various phrasings to ensure automatic selection works: "test this endpoint," "generate API tests," "add test coverage" should all trigger the same Skill.

When NOT to Create Skills:

Skills add maintenance overhead and selection complexity. Avoid creating them for:

One-off tasks

❌ "Rename this variable"

Single operations with no pattern don't need Skills.

Simple operations

❌ "Read this file"

Claude already handles basic file operations.

General knowledge

❌ "Explain REST APIs"

Explanations don't require specialized workflows.

Project-wide rules

❌ Skill: async-enforcer (always use async/await)
✅ CLAUDE.md: "Always use async/await"

Use CLAUDE.md for rules that apply everywhere, not Skills for enforcement.

When TO Create Skills:

Create Skills when they solve genuine, recurring problems:

Regular tasks

✓ "Generate API tests" (weekly for new endpoints)

Repeated workflows benefit from automation.

Domain expertise

✓ "Extract invoice data" (specific formats)

Specialized knowledge about structures justifies a Skill.

Multi-step procedures

✓ "Set up React component" (multiple files, patterns)

Complex workflows benefit from guidance.

Specialized formatting

✓ "Scientific visualizations" (publication standards)

Domain-specific conventions warrant a Skill.

The key question: Will this task happen multiple times with consistent patterns? If yes, consider a Skill. If no, just ask Claude directly.

Write Specific, Keyword-Rich Descriptions:

✅ "Extract tables from PDF invoices and reports"
❌ "PDF helper"

Include concrete actions and domain terms users naturally mention. Keywords like "extract," "tables," "PDF," and "invoices" help Claude match requests.

Include a "When to Use" Section:

## When to Use
- User asks to test API endpoints
- User mentions "coverage" or "edge cases"
- User wants to add tests to routes

List specific scenarios and phrases to improve selection accuracy.

Apply Least Privilege with Tools:

---
allowed-tools: Read, Write, Bash
---

Only grant tools the Skill actually needs. This makes capabilities clear and prevents unintended actions.

Keep Skills Concise: Aim for 200-500 lines total. Longer Skills become hard to maintain and understand. If your Skill grows beyond this, consider splitting it into multiple focused Skills.

Test Multiple Phrasings: Try different ways developers might request the task:

• "Generate tests for this API"
• "Add test coverage to the endpoint"
• "Test the /users route"

All should trigger the same Skill reliably. If they don't, add those phrases to "When to Use."

We have explored advanced skill patterns and best practices. Advanced Skills coordinate multiple tools through structured workflows: analysis, generation, and verification. They solve recurring problems with consistent patterns and require careful design through specific descriptions, focused purposes, and thorough testing.

Equally important is knowing when not to create a Skill. Simple operations, one-off tasks, and general knowledge don't warrant the overhead. Use CLAUDE.md for project-wide rules and reserve Skills for specialized, repeating workflows.

You now have the toolkit for creating powerful Skills that extend Claude's capabilities meaningfully. Looking ahead: The api-tester skill you built demonstrates multi-tool coordination, and in Unit 4 you will discover how Claude orchestrates multi-skill workflows using these same principles of clear descriptions and focused purposes. In the upcoming practice exercises, you will apply these principles to build advanced Skills, debug selection issues, and make thoughtful decisions about when Skills add value. Let's put these techniques into action!