feat(skills): modernize capability-writing with Anthropic best practices

Updates capability-writing skill with progressive disclosure structure based on Anthropic's January 2025 documentation. Implements Haiku-first approach (12x cheaper, 2-5x faster than Sonnet). Key changes: - Add 5 core principles: conciseness, progressive disclosure, script bundling, degrees of freedom, and Haiku-first model selection - Restructure with best-practices.md, templates/, examples/, and reference/ - Create 4 templates: user-invocable skill, background skill, agent, helper script - Add 3 examples: simple workflow, progressive disclosure, with scripts - Add 3 reference docs: frontmatter fields, model selection, anti-patterns - Update create-capability to analyze complexity and recommend structures - Default all new skills/agents to Haiku unless justified Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-11 18:10:53 +01:00
parent 7406517cd9
commit f424a7f992
13 changed files with 2612 additions and 229 deletions
--- a/skills/capability-writing/examples/progressive-disclosure.md
+++ b/skills/capability-writing/examples/progressive-disclosure.md
@@ -0,0 +1,129 @@
+# Example: Progressive Disclosure Skill
+
+A skill that uses reference files to keep the main SKILL.md concise.
+
+## Structure
+
+```
+skills/database-query/
+├── SKILL.md (~200 lines)
+├── reference/
+│   ├── schemas.md (table schemas)
+│   ├── common-queries.md (frequently used queries)
+│   └── optimization-tips.md (performance guidance)
+└── examples/
+    ├── simple-select.md
+    └── complex-join.md
+```
+
+## When to Use
+
+- Skill content would be >500 lines
+- Multiple domains or topics
+- Reference documentation is large
+- Want to keep main workflow concise
+
+## Example: database-query (main SKILL.md)
+
+```markdown
+---
+name: database-query
+description: >
+  Help users query the PostgreSQL database with proper schemas and optimization.
+  Use when user needs to write SQL queries or mentions database/tables.
+user-invocable: false
+---
+
+# Database Query Helper
+
+Help write efficient, correct SQL queries for our PostgreSQL database.
+
+## Quick Start
+
+\`\`\`sql
+SELECT id, name, created_at
+FROM users
+WHERE status = 'active'
+LIMIT 10;
+\`\`\`
+
+## Table Schemas
+
+We have 3 main schemas:
+
+- **Users & Auth**: See [reference/schemas.md#users](reference/schemas.md#users)
+- **Products**: See [reference/schemas.md#products](reference/schemas.md#products)
+- **Orders**: See [reference/schemas.md#orders](reference/schemas.md#orders)
+
+## Common Queries
+
+For frequently requested queries, see [reference/common-queries.md](reference/common-queries.md):
+- User activity reports
+- Sales summaries
+- Inventory status
+
+## Writing Queries
+
+1. **Identify tables**: Which schemas does this query need?
+2. **Check schema**: Load relevant schema from reference
+3. **Write query**: Use proper column names and types
+4. **Optimize**: See [reference/optimization-tips.md](reference/optimization-tips.md)
+
+## Examples
+
+- **Simple select**: See [examples/simple-select.md](examples/simple-select.md)
+- **Complex join**: See [examples/complex-join.md](examples/complex-join.md)
+```
+
+## Example: reference/schemas.md
+
+```markdown
+# Database Schemas
+
+## Users
+
+| Column | Type | Description |
+|--------|------|-------------|
+| id | UUID | Primary key |
+| email | VARCHAR(255) | Unique email |
+| name | VARCHAR(100) | Display name |
+| status | ENUM('active','inactive','banned') | Account status |
+| created_at | TIMESTAMP | Account creation |
+| updated_at | TIMESTAMP | Last update |
+
+## Products
+
+| Column | Type | Description |
+|--------|------|-------------|
+| id | UUID | Primary key |
+| name | VARCHAR(200) | Product name |
+| price | DECIMAL(10,2) | Price in USD |
+| inventory | INTEGER | Stock count |
+| category_id | UUID | FK to categories |
+
+## Orders
+
+[...more tables...]
+```
+
+## Why This Works
+
+- **Main file stays concise** (~200 lines)
+- **Details load on-demand**: schemas.md loads when user asks about specific table
+- **Fast for common cases**: Simple queries don't need reference files
+- **Scalable**: Can add more schemas without bloating main file
+
+## Loading Pattern
+
+1. User: "Show me all active users"
+2. Claude reads SKILL.md (sees Users schema reference)
+3. Claude: "I'll load the users schema to get column names"
+4. Claude reads reference/schemas.md#users
+5. Claude writes correct query
+
+## What Makes It Haiku-Friendly
+
+- ✓ Main workflow is simple ("identify → check schema → write query")
+- ✓ Reference files provide facts, not reasoning
+- ✓ Clear pointers to where details are
+- ✓ Examples show patterns
--- a/skills/capability-writing/examples/simple-workflow.md
+++ b/skills/capability-writing/examples/simple-workflow.md
@@ -0,0 +1,71 @@
+# Example: Simple Workflow Skill
+
+A basic skill with just a SKILL.md file - no scripts or reference files needed.
+
+## Structure
+
+```
+skills/list-open-prs/
+└── SKILL.md
+```
+
+## When to Use
+
+- Skill is simple (<300 lines)
+- No error-prone bash operations
+- No need for reference documentation
+- Straightforward workflow
+
+## Example: list-open-prs
+
+```markdown
+---
+name: list-open-prs
+description: >
+  List all open pull requests for the current repository.
+  Use when user wants to see PRs or says /list-open-prs.
+model: haiku
+user-invocable: true
+---
+
+# List Open PRs
+
+@~/.claude/skills/gitea/SKILL.md
+
+Show all open pull requests in the current repository.
+
+## Process
+
+1. **Get repository info**
+   - `git remote get-url origin`
+   - Parse owner/repo from URL
+
+2. **Fetch open PRs**
+   - `tea pulls list --state open --output simple`
+
+3. **Format results** as table
+
+| PR # | Title | Author | Created |
+|------|-------|--------|---------|
+| ... | ... | ... | ... |
+
+## Guidelines
+
+- Show most recent PRs first
+- Include link to each PR
+- If no open PRs, say "No open pull requests"
+```
+
+## Why This Works
+
+- **Concise**: Entire skill fits in ~30 lines
+- **Simple commands**: Just git and tea CLI
+- **No error handling needed**: tea handles errors gracefully
+- **Structured output**: Table format is clear
+
+## What Makes It Haiku-Friendly
+
+- ✓ Simple sequential steps
+- ✓ Clear commands with no ambiguity
+- ✓ Structured output format
+- ✓ No complex decision-making
--- a/skills/capability-writing/examples/with-scripts.md
+++ b/skills/capability-writing/examples/with-scripts.md
@@ -0,0 +1,210 @@
+# Example: Skill with Bundled Scripts
+
+A skill that bundles helper scripts for error-prone operations.
+
+## Structure
+
+```
+skills/deploy-to-staging/
+├── SKILL.md
+├── reference/
+│   └── rollback-procedure.md
+└── scripts/
+    ├── validate-build.sh
+    ├── deploy.sh
+    └── health-check.sh
+```
+
+## When to Use
+
+- Operations have complex error handling
+- Need retry logic
+- Multiple validation steps
+- Fragile bash commands
+
+## Example: deploy-to-staging (main SKILL.md)
+
+```markdown
+---
+name: deploy-to-staging
+description: >
+  Deploy current branch to staging environment with validation and health checks.
+  Use when deploying to staging or when user says /deploy-to-staging.
+model: haiku
+user-invocable: true
+---
+
+# Deploy to Staging
+
+Deploy current branch to staging with automated validation and rollback capability.
+
+## Process
+
+1. **Validate build**
+   - `./scripts/validate-build.sh`
+   - Checks tests pass, linter clean, no uncommitted changes
+
+2. **Show deployment plan** for approval
+   - Branch name
+   - Latest commit
+   - Services that will be updated
+
+3. **If approved, deploy**
+   - `./scripts/deploy.sh staging $branch`
+   - Script handles Docker build, push, k8s apply
+
+4. **Health check**
+   - `./scripts/health-check.sh staging`
+   - Verifies all services are healthy
+
+5. **Report results**
+   - Deployment URL
+   - Status of each service
+   - Rollback command if needed
+
+## Rollback
+
+If deployment fails, see [reference/rollback-procedure.md](reference/rollback-procedure.md)
+```
+
+## Example: scripts/validate-build.sh
+
+```bash
+#!/bin/bash
+# validate-build.sh - Pre-deployment validation
+#
+# Checks:
+# - Tests pass
+# - Linter clean
+# - No uncommitted changes
+# - Docker builds successfully
+
+set -e
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+NC='\033[0m'
+
+error() {
+    echo -e "${RED}ERROR: $1${NC}" >&2
+    exit 1
+}
+
+success() {
+    echo -e "${GREEN}✓ $1${NC}"
+}
+
+# Check 1: No uncommitted changes
+if ! git diff-index --quiet HEAD --; then
+    error "Uncommitted changes detected. Commit or stash first."
+fi
+success "No uncommitted changes"
+
+# Check 2: Tests pass
+if ! npm test > /dev/null 2>&1; then
+    error "Tests failing. Fix tests before deploying."
+fi
+success "Tests pass"
+
+# Check 3: Linter clean
+if ! npm run lint > /dev/null 2>&1; then
+    error "Linter errors. Run 'npm run lint' to see details."
+fi
+success "Linter clean"
+
+# Check 4: Docker builds
+if ! docker build -t test-build . > /dev/null 2>&1; then
+    error "Docker build failed"
+fi
+success "Docker build successful"
+
+echo ""
+echo -e "${GREEN}✓ All validations passed${NC}"
+```
+
+## Example: scripts/deploy.sh
+
+```bash
+#!/bin/bash
+# deploy.sh - Deploy to environment
+#
+# Usage: deploy.sh <environment> <branch>
+# Example: deploy.sh staging feature-new-ui
+
+set -e
+
+ENVIRONMENT=$1
+BRANCH=$2
+
+if [ -z "$ENVIRONMENT" ] || [ -z "$BRANCH" ]; then
+    echo "Usage: $0 <environment> <branch>"
+    exit 1
+fi
+
+echo "Deploying $BRANCH to $ENVIRONMENT..."
+
+# Build Docker image
+docker build -t myapp:$BRANCH .
+
+# Tag for registry
+docker tag myapp:$BRANCH registry.example.com/myapp:$BRANCH
+
+# Push to registry with retry
+for i in {1..3}; do
+    if docker push registry.example.com/myapp:$BRANCH; then
+        break
+    fi
+    echo "Push failed, retrying ($i/3)..."
+    sleep 5
+done
+
+# Update Kubernetes deployment
+kubectl set image deployment/myapp \
+    myapp=registry.example.com/myapp:$BRANCH \
+    -n $ENVIRONMENT
+
+# Wait for rollout
+kubectl rollout status deployment/myapp -n $ENVIRONMENT --timeout=5m
+
+echo "Deployment complete!"
+echo "URL: https://$ENVIRONMENT.example.com"
+```
+
+## Why This Works
+
+**Script benefits:**
+- **Deterministic**: Same behavior every time
+- **Error handling**: Retries, clear messages
+- **Validation**: Pre-flight checks prevent bad deployments
+- **No token cost**: Scripts execute without loading code into context
+
+**Skill stays simple:**
+- Main SKILL.md is ~30 lines
+- Just calls scripts in order
+- No complex bash logic inline
+- Easy to test scripts independently
+
+## What Makes It Haiku-Friendly
+
+- ✓ Skill has simple instructions ("run script X, then Y")
+- ✓ Scripts handle all complexity
+- ✓ Clear success/failure from script exit codes
+- ✓ Validation prevents ambiguous states
+- ✓ Structured output from scripts is easy to parse
+
+## Testing Scripts
+
+Scripts can be tested independently:
+
+```bash
+# Test validation
+./scripts/validate-build.sh
+
+# Test deployment (dry-run)
+./scripts/deploy.sh staging test-branch --dry-run
+
+# Test health check
+./scripts/health-check.sh staging
+```
+
+This makes the skill more reliable than inline bash.