Skill Metadata

What It Does

Claude Code Skill 생성 및 최적화를 위한 전체 가이드를 제공합니다. Progressive disclosure 패턴, freedom level framework, YAML metadata 작성, 예제 구성 방법을 다룹니다.

When to Use

• 새로운 Skill을 생성할 때
• 기존 Skill을 최적화하거나 리팩토링할 때
• Freedom level (high/medium/low) 균형을 조정할 때
• Skill metadata나 구조를 검증할 때

Creating and Optimizing Claude Code Skills

Skills are modular, reusable knowledge capsules that load via Progressive Disclosure. They combine templates, patterns, and best practices without blocking user workflow.

Skill File Structure

Location: .claude/skills/skill-name/

skill-name/
├── SKILL.md              # Main instructions (~400 lines)
├── reference.md          # Detailed reference (optional)
├── examples.md           # Real-world examples (optional)
├── CHECKLIST.md          # Validation guide (optional)
├── scripts/              # Utility scripts
│   ├── validator.sh
│   └── formatter.py
└── templates/            # Reusable templates
    ├── config.json
    └── main.md

YAML Frontmatter

---
name: "Skill Name (Gerund + Domain)"
description: "Creating and Optimizing Claude Code Skills. [Capability]. Use when [trigger 1], [trigger 2], [trigger 3]."
allowed-tools: "Read, Write, Bash(python:*)"
---

Field Rules

Freedom Level Framework

High-Freedom: Architecture Design

## Architecture Trade-offs

| Pattern | Pros | Cons | When |
|---------|------|------|------|
| Monolith | Simple, unified | Scales poorly | MVP, <10 people |
| Microservices | Scalable, independent | Complex, distributed tracing | 10+ teams |
| Serverless | Zero ops, elastic | Cold starts, vendor lock-in | Event-driven |

Choose based on:
1. **Team size**: Monolith if <5 devs
2. **Scale**: Microservices if >10M requests/month
3. **Budget**: Serverless if unpredictable workload

Medium-Freedom: Data Validation Pattern

## Validation Workflow

1. Load data source (CSV, JSON, API)
2. For each record:
   a. Check required fields exist
   b. Validate data types
   c. Verify constraints (range, format)
   d. Check references (foreign keys)
3. Collect errors with row numbers
4. Report summary + fix suggestions
5. Proceed only if all errors fixed

## Example: CSV Validation
   - Input: data.csv
   - Schema: validators/schema.json
   - Output: validation_report.json

Low-Freedom: Security Validator Script

#!/usr/bin/env python3
"""Validate code for OWASP Top 10 risks"""
import re
import sys

PATTERNS = [
    (r"eval\(", "OWASP-A1: Code injection risk"),
    (r"SELECT.*\$", "OWASP-A3: SQL injection risk"),
    (r"os\.system\(", "OWASP-A6: Command injection risk"),
]

def validate_file(filepath):
    with open(filepath) as f:
        content = f.read()

    issues = []
    for pattern, risk in PATTERNS:
        if re.search(pattern, content):
            issues.append(risk)

    return issues

if __name__ == "__main__":
    for filepath in sys.argv[1:]:
        issues = validate_file(filepath)
        if issues:
            print(f"⚠️  {filepath}:")
            for issue in issues:
                print(f"  • {issue}")

Progressive Disclosure Pattern

Level 1: Metadata (always loaded)

name: "Database Query Optimization"
description: "Creating and Optimizing Claude Code Skills. Profile slow queries, analyze execution plans, suggest indexes..."
allowed-tools: "Read, Bash(sqlite3:*)"

Level 2: Main content (on demand)

• Overview + quick start
• 3-4 core patterns
• Decision tree

Level 3: Resources (when referenced)

• reference.md — Detailed specs
• examples.md — Real-world scenarios
• scripts/ — Utility tools

Skill Discovery Keywords

Embed in description for auto-activation:

✅ DO include:

• Problem domain: "CSV", "SQL", "React", "API"
• Operation: "parsing", "validation", "optimization", "debugging"
• Tech stack: "Python", "TypeScript", "Go"

Example description:

"Parse CSV files, validate data schemas, clean datasets.
Use when processing CSV, Excel, JSON data or when user mentions
data cleaning, validation, or transformation."

Medium-Freedom: Example Skill Template

---
name: "Testing React Components with Vitest"
description: "Creating and Optimizing Claude Code Skills. Write unit tests for React components, mock hooks, test async behavior. Use when testing React components, setting up Vitest, or debugging test failures."
allowed-tools: "Read, Write, Bash(npm:*), Bash(npm run:*)"
---

# Testing React Components with Vitest

## Quick Start

1. Install: `npm install -D vitest @testing-library/react`
2. Create test: `src/Component.test.tsx`
3. Run: `npm run test`

## Core Patterns

### Pattern 1: Basic Component Test
```typescript
import { render, screen } from '@testing-library/react'
import { Button } from './Button'

it('renders button with text', () => {
  render(<Button>Click me</Button>)
  expect(screen.getByText('Click me')).toBeInTheDocument()
})

Pattern 2: Mock Hooks

import { useUserStore } from './store'

vi.mock('./store', () => ({
  useUserStore: vi.fn(() => ({ user: null }))
}))

Examples

See examples.md for integration with Redux, React Query, form testing.

## Skill Validation Checklist

- [ ] `name` is specific (not "React Helper")
- [ ] `description` includes 3+ discovery keywords
- [ ] Main content ≤ 500 lines
- [ ] At least 2 concrete examples
- [ ] Progressive Disclosure applied (metadata → content → resources)
- [ ] Freedom levels mixed appropriately
- [ ] No hardcoded paths or time-sensitive data
- [ ] YAML frontmatter is valid
- [ ] Paths use forward slashes (`/` not `\`)

## Skill Optimization Patterns

### Anti-pattern 1: Too Generic
```yaml
❌ name: "Python Helper"
✅ name: "Testing Python Code with pytest"

Anti-pattern 2: No Examples

❌ Only principles, no code samples
✅ Each concept has working example

Anti-pattern 3: Nested Files

❌ docs/api/v2/reference/security.md
✅ reference.md (one level)

Anti-pattern 4: Absolute Paths

❌ /Users/name/project/config.json
✅ ./config.json or ${PROJECT_DIR}/config.json

Best Practices

✅ DO:

• Keep < 500 lines per SKILL.md
• Use relative paths with forward slashes
• Provide working code examples
• Design for reusability across projects
• Include both success and error paths

❌ DON'T:

• Mix too many domains (split into separate Skills)
• Explain fundamentals (trust Claude already knows)
• Create nested directory structures
• Include time-sensitive info (dates, versions)
• Use Windows-style paths

Skill Lifecycle

1. Create: Design persona, scope, freedom levels
2. Implement: Write SKILL.md + examples
3. Test: Verify with Haiku, Sonnet, Opus
4. Deploy: Add to .claude/skills/
5. Iterate: Get feedback, update as needed

Reference: Claude Code Skills official documentation Version: 1.0.0