Advanced Skill Design Patterns

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.