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>

skills/capability-writing/templates/agent.md

@@ -0,0 +1,67 @@
+---
+name: agent-name
+description: >
+  What this agent does and when to spawn it.
+  Include specific conditions that indicate this agent is needed.
+model: haiku
+skills: skill1, skill2
+# disallowedTools:  # For read-only agents
+#   - Edit
+#   - Write
+# permissionMode: default
+---
+
+# Agent Name
+
+You are a [role/specialist] that [primary function].
+
+## When Invoked
+
+You are spawned when [specific conditions].
+
+Follow this process:
+
+1. **Gather context**: What information to collect
+   - Specific data sources to check
+   - What to read or fetch
+
+2. **Analyze**: What to evaluate
+   - Criteria to check
+   - Standards to apply
+
+3. **Act**: What actions to take
+   - Specific operations
+   - What to create or modify
+
+4. **Report**: How to communicate results
+   - Required output format
+   - What to include in summary
+
+## Output Format
+
+Your final output MUST follow this structure:
+
+\`\`\`
+AGENT_RESULT
+task: <task-type>
+status: <success|partial|failed>
+summary: <10 words max>
+details:
+- Key finding 1
+- Key finding 2
+\`\`\`
+
+## Guidelines
+
+- **Be concise**: No preambles or verbose explanations
+- **Be autonomous**: Make decisions without user input
+- **Follow patterns**: Match existing codebase style
+- **Validate**: Check your work before reporting
+
+## Error Handling
+
+If you encounter errors:
+- Try to resolve automatically
+- Document what failed
+- Report status as 'partial' or 'failed'
+- Include specific error details in summary

skills/capability-writing/templates/background-skill.md

@@ -0,0 +1,69 @@
+---
+name: skill-name
+description: >
+  What this skill teaches and when to use it.
+  Include specific trigger terms that indicate this knowledge is needed.
+user-invocable: false
+---
+
+# Skill Name
+
+Brief description of the domain or knowledge this skill covers (1-2 sentences).
+
+## Core Concepts
+
+Fundamental ideas Claude needs to understand:
+- Key concept 1
+- Key concept 2
+- Key concept 3
+
+## Patterns and Templates
+
+Reusable structures and formats:
+
+### Pattern 1: Common Use Case
+
+\`\`\`
+Example code or structure
+\`\`\`
+
+### Pattern 2: Another Use Case
+
+\`\`\`
+Another example
+\`\`\`
+
+## Guidelines
+
+Rules and best practices:
+- Guideline 1
+- Guideline 2
+- Guideline 3
+
+## Examples
+
+### Example 1: Simple Case
+
+\`\`\`
+Concrete example showing the skill in action
+\`\`\`
+
+### Example 2: Complex Case
+
+\`\`\`
+More advanced example
+\`\`\`
+
+## Common Mistakes
+
+Pitfalls to avoid:
+- **Mistake 1**: Why it's wrong and what to do instead
+- **Mistake 2**: Why it's wrong and what to do instead
+
+## Reference
+
+Quick-reference tables or checklists:
+
+| Command | Purpose | Example |
+|---------|---------|---------|
+| ... | ... | ... |

skills/capability-writing/templates/helper-script.sh

@@ -0,0 +1,86 @@
+#!/bin/bash
+# script-name.sh - Brief description of what this script does
+#
+# Usage: script-name.sh <param1> <param2> [optional-param]
+#
+# Example:
+#   script-name.sh value1 value2
+#   script-name.sh value1 value2 optional-value
+#
+# Exit codes:
+#   0 - Success
+#   1 - Invalid arguments or general error
+#   2 - Specific error condition (document what)
+
+set -e  # Exit immediately on error
+# set -x  # Uncomment for debugging
+
+# Color output for better visibility
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Helper functions
+error() {
+    echo -e "${RED}ERROR: $1${NC}" >&2
+    exit 1
+}
+
+success() {
+    echo -e "${GREEN}SUCCESS: $1${NC}"
+}
+
+warn() {
+    echo -e "${YELLOW}WARNING: $1${NC}"
+}
+
+# Input validation
+if [ $# -lt 2 ]; then
+    echo "Usage: $0 <param1> <param2> [optional-param]"
+    echo ""
+    echo "Description: Brief description of what this does"
+    echo ""
+    echo "Arguments:"
+    echo "  param1        Description of param1"
+    echo "  param2        Description of param2"
+    echo "  optional-param  Description of optional param (default: value)"
+    exit 1
+fi
+
+# Parse arguments
+PARAM1=$1
+PARAM2=$2
+OPTIONAL_PARAM=${3:-"default-value"}
+
+# Validate inputs
+if [ -z "$PARAM1" ]; then
+    error "param1 cannot be empty"
+fi
+
+# Main logic
+main() {
+    echo "Processing with param1=$PARAM1, param2=$PARAM2..."
+
+    # Step 1: Describe what this step does
+    if ! some_command "$PARAM1"; then
+        error "Failed to process param1"
+    fi
+
+    # Step 2: Another operation with error handling
+    result=$(another_command "$PARAM2" 2>&1)
+    if [ $? -ne 0 ]; then
+        error "Failed to process param2: $result"
+    fi
+
+    # Step 3: Validation
+    if [ ! -f "$result" ]; then
+        error "Expected file not found: $result"
+    fi
+
+    success "Operation completed successfully"
+    echo "$result"  # Output for caller to parse
+}
+
+# Execute main function
+main

skills/capability-writing/templates/user-invocable-skill.md

@@ -0,0 +1,65 @@
+---
+name: skill-name
+description: >
+  Clear description of what this skill does and when to use it.
+  Use when [specific trigger conditions] or when user says /skill-name.
+model: haiku
+argument-hint: <required-param> [optional-param]
+user-invocable: true
+# context: fork  # Use for skills needing isolated context
+# allowed-tools:  # Restrict tools if needed
+#   - Read
+#   - Bash
+---
+
+# Skill Title
+
+@~/.claude/skills/relevant-background-skill/SKILL.md
+
+Brief intro explaining the skill's purpose (1-2 sentences max).
+
+## Process
+
+1. **First step**: Clear action with specific command or instruction
+   - `command or tool to use`
+   - What to look for or validate
+
+2. **Second step**: Next action
+   - Specific details
+   - Expected output
+
+3. **Ask for approval** before significant actions
+   - Show what will be created/modified
+   - Wait for user confirmation
+
+4. **Execute** the approved actions
+   - Run commands/create files
+   - Handle errors gracefully
+
+5. **Present results** with links and summary
+   - Structured output (table or list)
+   - Links to created resources
+
+## Guidelines
+
+- Keep responses concise
+- Use structured output (tables, lists)
+- No preambles or sign-offs
+- Validate inputs before acting
+
+## Output Format
+
+Use this structure for responses:
+
+\`\`\`
+## Summary
+[1-2 sentences]
+
+## Results
+| Item | Status | Link |
+|------|--------|------|
+| ... | ... | ... |
+
+## Next Steps
+- ...
+\`\`\`