Claude Code: Agent Skills and skill-creator
Last updated: 2026-08-31
Agent Skills are Claude Code's "professional skill packs" — install a Skill, and Claude Code gains a complete professional workflow.
💡 Tip: Skills aren't simple prompt templates, but complete workflow definitions including steps, checklists, output formats, and verification logic. skill-creator lets you customize these skills.
📋 Prerequisites: Chapter 15 - Memory System
1. What You'll Learn
- Agent Skills concept and architecture
- Built-in and community Skills
- Skills usage examples
- Creating custom Skills with skill-creator
- Skills best practices
2. Agent Skills Concept
(1) What is a Skill
| Component | Description |
|---|---|
| Trigger conditions | What tasks activate this Skill |
| Work steps | Ordered execution steps |
| Checkpoints | Verification checklist after each step |
| Output format | Standard format for final output |
| Tool dependencies | Which tools are needed |
(2) Skill vs Plain Instruction
| Dimension | Plain Instruction | Skill |
|---|---|---|
| Structure | Free text | Structured workflow |
| Completeness | May miss steps | Checkpoints ensure completeness |
| Consistency | May vary each time | Same flow every time |
| Reusability | One-time | Cross-project reusable |
| Verification | No auto-verification | Built-in verification checks |
▶ Example 1: Skill vs Plain Instruction
TEXT
📖 Display only
# Plain instruction
> Review this file's code quality
[Free-form review, may miss aspects]
# Using Skill
> /skill code-review
[Follows code-review Skill's structured flow]
Step 1: Read file ✓
Step 2: Security check ✓ (SQL injection, XSS, sensitive data exposure)
Step 3: Performance check ✓ (N+1 queries, memory leaks)
Step 4: Style check ✓
Step 5: Generate report ✓
All checkpoints passed
3. Built-in and Community Skills
(1) Built-in Skills
| Skill | Function | Trigger |
|---|---|---|
| code-review | Code review | /skill code-review |
| bug-fix | Bug fix workflow | /skill bug-fix |
| refactor | Refactoring workflow | /skill refactor |
| test-gen | Test generation | /skill test-gen |
| api-design | API design | /skill api-design |
| security-audit | Security audit | /skill security-audit |
(2) Skill Management
BASH
# List available Skills
claude /skills
# Install community Skill
claude /skill install @community/pr-review
# View Skill details
claude /skill info code-review
4. Skills Usage Examples
▶ Example 2: bug-fix Skill Workflow
TEXT
📖 Display only
> /skill bug-fix "TypeError: Cannot read property 'id' of undefined at UserController.getProfile"
Claude Code [bug-fix Skill]:
Step 1: Locate Bug ✓
→ Found: getProfile() accesses req.user.id without null check
Step 2: Analyze Root Cause ✓
→ req.user is undefined when auth middleware fails silently
Step 3: Design Fix ✓
→ Add null check in getProfile()
→ Fix auth middleware to throw on failure
Step 4: Implement Fix ✓
→ Modifying UserController.ts and auth.ts
Step 5: Verify Fix ✓
→ Running tests: 5/5 passed ✓
Step 6: Prevent Recurrence ✓
→ Added edge case test for null user
Bug fixed ✓ | 2 files modified | 1 test added
5. Creating Custom Skills with skill-creator
(1) Skill Definition Structure
YAML
# .claude/skills/my-deployment.yaml
name: deployment
description: "Standardized deployment workflow"
trigger:
keywords: ["deploy", "deployment"]
steps:
- name: "Pre-check"
actions:
- "Confirm all tests pass"
- "Check no uncommitted changes"
checkpoints:
- "npm test exit code = 0"
- "git status clean"
- name: "Build"
actions:
- "Run build command"
checkpoints:
- "build/ directory exists"
- name: "Deploy"
actions:
- "Push code to remote"
- "Trigger CI/CD pipeline"
checkpoints:
- "git push successful"
- name: "Verify"
actions:
- "Wait for deployment"
- "Access health check endpoint"
checkpoints:
- "HTTP 200 from /health"
output:
format: "markdown"
▶ Example 3: Using skill-creator
TEXT
📖 Display only
> /skill-creator create a "database migration" Skill
Claude Code:
I'll help you create a DB migration Skill. A few questions:
1. Database tool? Prisma
2. Migration steps? Modify schema, generate migration, run, verify
3. Safety checks? Backup database, check reversibility
4. Output format? Markdown report
→ Creating .claude/skills/db-migration.yaml
→ Skill created ✓
Usage: /skill db-migration
6. Skills Best Practices
When to Create a Skill
| Scenario | Create Skill? | Reason |
|---|---|---|
| Repetitive workflows | ✅ Yes | Standardization beneficial |
| Critical processes | ✅ Yes | Checkpoints prevent omissions |
| Team collaboration | ✅ Yes | Unified work standards |
| One-time tasks | ❌ No | Plain instructions suffice |
| Simple queries | ❌ No | Over-engineering |
Design Principles
| Principle | Description |
|---|---|
| Minimal | No more than 6 steps |
| Verifiable | Each step has clear checkpoints |
| Reversible | Critical operations have rollback plans |
| Composable | Skills can be nested |
❓ FAQ
Q Difference between Skill and Plugin?
A Skills are workflow definitions (steps+checkpoints); plugins are feature extensions (tools+hooks). Skills use plugin-provided tools, but they're independent concepts.
Q Does Skill guarantee quality?
A Not 100%. Skills provide structured flows and checkpoints, but execution quality depends on model ability. Critical operations should have human review.
Q Can Skills be reused across projects?
A Yes. In
~/.claude/skills/ for global, .claude/skills/ for project-specific.Q Are skill-creator generated skills good?
A First version is usable but needs refinement. skill-creator generates the framework; you refine steps and checkpoints per your needs.
📖 Summary
- Skills are structured workflows: steps + checkpoints + output format
- Built-in Skills: code-review, bug-fix, security-audit, etc.
/skill <name>triggers Skill execution following the flow- skill-creator interactively creates custom Skills
- Repetitive workflows and critical processes benefit from Skills; one-time tasks don't need them
📝 Exercises
- Basic (⭐): Use built-in
code-reviewSkill to review a file, compare with plain instruction. - Intermediate (⭐⭐): Use skill-creator to create a custom Skill (e.g., deployment workflow), test execution.
- Advanced (⭐⭐⭐): Create 3 core Skills for a team covering dev→test→deploy with complete checkpoints.
