claude-all-hands 1.0.0

package/.claude/skills/skill-development/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: skill-development
+description: Use when user asks to "create a skill", "build a new skill", "write skill instructions", "improve skill description", "organize skill content", or needs guidance on skill structure, progressive disclosure, or skill development best practices. (project)
+---
+
+# Skill Development
+
+Guide for creating effective Claude Code skills with proper structure, progressive disclosure, and validation.
+
+## Overview
+
+Skills extend Claude's capabilities through specialized knowledge and workflows. Each skill packages expertise into a discoverable capability that Claude invokes autonomously based on description triggers.
+
+### Skill Anatomy
+
+```
+skill-name/
+├── SKILL.md (required)
+│   ├── YAML frontmatter (name, description)
+│   └── Markdown body (~500-700 words target)
+└── Bundled Resources (only if needed)
+    ├── references/     - Detailed docs, loaded as needed
+    ├── examples/       - Working code, copyable
+    └── scripts/        - Utilities, executable
+```
+
+### Progressive Disclosure
+
+Three-level loading for context efficiency:
+
+| Level | Contents | When Loaded | Size Target |
+|-------|----------|-------------|-------------|
+| Metadata | name + description | Always | ~100 words |
+| Body | SKILL.md content | Skill triggers | ~500-700 words |
+| Resources | references/, examples/, scripts/ | As needed | Unlimited |
+
+For detailed patterns, see `references/progressive-disclosure.md`.
+
+## Creation Process
+
+### Step 1: Understand Use Cases
+
+Before writing, clarify concrete usage scenarios:
+
+- What specific phrases trigger this skill?
+- What tasks does it help accomplish?
+- What would a user say to invoke it?
+
+### Step 2: Plan Reusable Contents
+
+Analyze each use case to identify:
+
+1. **Scripts**: Code rewritten repeatedly or needing deterministic reliability
+2. **References**: Documentation Claude should consult while working
+3. **Assets**: Files used in output (templates, images)
+
+### Step 3: Create Structure
+
+```bash
+mkdir -p .claude/skills/skill-name
+touch .claude/skills/skill-name/SKILL.md
+```
+
+**Minimal by default**: Only create `references/`, `examples/`, or `scripts/` when content exceeds SKILL.md capacity or requires separate files. Most skills need only SKILL.md.
+
+### Step 4: Write SKILL.md
+
+#### Frontmatter Requirements
+
+```yaml
+---
+name: skill-name          # lowercase-hyphenated, max 64 chars
+description: [trigger description, max 1024 chars]
+---
+```
+
+**Description format** (direct with triggers):
+```yaml
+description: Use when user asks to "create X", "configure Y", "build Z", or needs guidance on [domain]. Provides [capability summary].
+```
+
+#### Body Writing Style
+
+Use **imperative/infinitive form** throughout:
+
+| Correct | Incorrect |
+|---------|-----------|
+| Create the configuration file | You should create the configuration file |
+| Validate input before processing | You need to validate input |
+| Parse frontmatter using sed | Claude should parse frontmatter |
+
+For complete style rules, see `references/writing-style.md`.
+
+#### Body Structure
+
+```markdown
+# Skill Name
+
+Overview (2-3 sentences).
+
+## Quick Reference
+Essential patterns, commands, key concepts.
+
+## Key Workflows
+Step-by-step procedures for main use cases.
+
+## Additional Resources
+
+### Reference Files
+- **`references/detailed-guide.md`** - Extended documentation
+
+### Examples
+- **`examples/working-example.sh`** - Annotated example
+```
+
+**Keep body lean**: Only move to references/ when content exceeds ~700 words or requires separate file format.
+
+### Step 5: Validate
+
+**Structure**:
+- [ ] SKILL.md exists with valid YAML frontmatter
+- [ ] `name` field: lowercase-hyphenated, max 64 chars
+- [ ] `description` field: max 1024 chars
+- [ ] Referenced files exist
+
+**Description Quality**:
+- [ ] Direct format ("Use when...")
+- [ ] Specific trigger phrases ("create X", "configure Y")
+- [ ] Not vague or generic
+
+**Content Quality**:
+- [ ] Body uses imperative/infinitive form (not second person)
+- [ ] Body is ~500-700 words (move excess to references/)
+- [ ] Resources only created when necessary
+- [ ] Resources clearly referenced in body if present
+
+### Step 6: Iterate
+
+After using the skill on real tasks:
+
+1. Notice struggles or inefficiencies
+2. Identify improvements to SKILL.md or resources
+3. Implement changes
+4. Test again
+
+## Degrees of Freedom
+
+Match constraint level to task criticality:
+
+| Level | When to Use | Example |
+|-------|-------------|---------|
+| High (text) | Multiple valid approaches | "Generate appropriate tests" |
+| Medium (parameterized) | Preferred pattern exists | Script with configurable params |
+| Low (exact) | Fragile/critical ops | Exact shell commands |
+
+## Common Mistakes
+
+### Weak Trigger Description
+
+**Bad**:
+```yaml
+description: Provides guidance for working with hooks.
+```
+
+**Good**:
+```yaml
+description: Use when user asks to "create a hook", "add a PreToolUse hook", "validate tool use". Provides hooks API guidance.
+```
+
+### Too Much in SKILL.md
+
+**Bad**: 1,000+ words in SKILL.md without references
+
+**Good**: ~500-700 words in SKILL.md, move excess to references/
+
+### Unnecessary Reference Files
+
+**Bad**: Creating references/ for simple skills that fit in ~500 words
+
+**Good**: Most skills are SKILL.md only. Create subdirs only when:
+- Content exceeds ~700 words
+- Need executable scripts or separate file formats
+- Multiple distinct reference documents required
+
+### Second Person Writing
+
+**Bad**: "You should start by reading the configuration."
+
+**Good**: "Start by reading the configuration."
+
+## Quick Reference Structures
+
+### Minimal Skill
+```
+skill-name/
+└── SKILL.md
+```
+
+### Standard Skill (Recommended)
+```
+skill-name/
+├── SKILL.md
+├── references/
+│   └── detailed-guide.md
+└── examples/
+    └── working-example.sh
+```
+
+### Complete Skill
+```
+skill-name/
+├── SKILL.md
+├── references/
+│   ├── patterns.md
+│   └── advanced.md
+├── examples/
+│   ├── example1.sh
+│   └── example2.json
+└── scripts/
+    └── validate.sh
+```
+
+## Additional Resources
+
+### Reference Files
+
+- **`references/progressive-disclosure.md`** - Directory structure patterns, when to use each level
+- **`references/writing-style.md`** - Imperative form rules, formatting best practices
+
+### Examples
+
+- **`examples/complete-skill-examples.md`** - Annotated complete skills with commentary
+
+### Scripts
+
+- **`scripts/validate-skill.sh`** - Validate skill file structure and content

package/.claude/skills/skill-development/examples/complete-skill-examples.md

@@ -0,0 +1,281 @@
+# Complete Skill Examples
+
+Annotated examples demonstrating skill structure best practices.
+
+---
+
+## Example 1: Code Review Skill (Minimal Structure)
+
+Simple skill with no supporting files.
+
+### File: `code-review/SKILL.md`
+
+```yaml
+---
+name: code-review
+description: Use when user asks to "review code", "check this PR", "analyze code quality", or needs feedback on code changes. Provides structured code review guidance.
+---
+
+# Code Review
+
+Structured approach to reviewing code for quality, security, and maintainability.
+
+## Quick Reference
+
+| Check | Focus Areas |
+|-------|-------------|
+| Logic | Edge cases, error handling, race conditions |
+| Security | Input validation, auth, data exposure |
+| Performance | N+1 queries, memory leaks, inefficient loops |
+| Style | Naming, formatting, documentation |
+| Tests | Coverage, edge cases, mocking |
+
+## Review Workflow
+
+### 1. Understand Context
+
+Before reviewing:
+- Read PR description and linked issues
+- Understand the feature/fix intent
+- Check affected components
+
+### 2. Structural Review
+
+Examine high-level design:
+- File organization appropriate?
+- Separation of concerns maintained?
+- Dependencies reasonable?
+
+### 3. Line-by-Line Review
+
+Check each change for:
+- Logic correctness
+- Edge case handling
+- Error handling
+- Security implications
+
+### 4. Test Review
+
+Verify test coverage:
+- Happy path covered
+- Edge cases tested
+- Error conditions handled
+
+## Output Format
+
+Structure review comments as:
+
+**[SEVERITY]** path/to/file.py:L42
+
+[Issue description]
+
+Suggestion:
+[Proposed fix or improvement]
+
+Severity levels:
+- **CRITICAL**: Must fix before merge
+- **IMPORTANT**: Should fix, may block
+- **SUGGESTION**: Nice to have
+- **QUESTION**: Clarification needed
+```
+
+### Commentary
+
+This minimal skill works because:
+- **Focused scope**: Just code review
+- **Clear triggers**: "review code", "check this PR"
+- **Actionable content**: Checklist and workflow immediately usable
+- **Output format**: Structured format ensures consistent reviews
+
+---
+
+## Example 2: API Integration Skill (Standard Structure)
+
+Skill with references for detailed documentation.
+
+### Directory Structure
+
+```
+api-integration/
+├── SKILL.md
+└── references/
+    ├── authentication.md
+    └── error-handling.md
+```
+
+### File: `api-integration/SKILL.md`
+
+```yaml
+---
+name: api-integration
+description: Use when user asks to "integrate with API", "make API calls", "handle API authentication", or needs guidance on REST API integration patterns.
+---
+
+# API Integration
+
+Patterns for integrating with REST APIs: authentication, requests, error handling.
+
+## Quick Reference
+
+| Task | Pattern |
+|------|---------|
+| Auth | Bearer token in Authorization header |
+| Requests | Use requests library with timeout |
+| Errors | Retry with exponential backoff |
+| Responses | Validate schema before processing |
+
+## Core Workflow
+
+### 1. Setup Authentication
+
+import requests
+
+def get_client(api_key: str) -> requests.Session:
+    session = requests.Session()
+    session.headers.update({
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json"
+    })
+    return session
+
+For advanced auth patterns, see `references/authentication.md`.
+
+### 2. Make Requests
+
+def api_request(session, method, url, **kwargs):
+    kwargs.setdefault("timeout", 30)
+    response = session.request(method, url, **kwargs)
+    response.raise_for_status()
+    return response.json()
+
+### 3. Handle Errors
+
+Implement retry with backoff for transient failures.
+
+For comprehensive error handling, see `references/error-handling.md`.
+
+## Additional Resources
+
+### Reference Files
+
+- **`references/authentication.md`** - OAuth flows, API key patterns, JWT handling
+- **`references/error-handling.md`** - Error categories, retry strategies
+```
+
+### Commentary
+
+This standard structure works because:
+- **Lean SKILL.md**: Core patterns inline, details in references
+- **Progressive disclosure**: Auth and error depth available but not always loaded
+- **Practical code**: Copy-paste ready examples
+
+---
+
+## Example 3: Database Migration Skill (Complete Structure)
+
+Full skill with references, examples, and scripts.
+
+### Directory Structure
+
+```
+db-migration/
+├── SKILL.md
+├── references/
+│   └── rollback-procedures.md
+├── examples/
+│   └── simple-migration.sql
+└── scripts/
+    └── validate-migration.sh
+```
+
+### File: `db-migration/SKILL.md`
+
+```yaml
+---
+name: db-migration
+description: Use when user asks to "create migration", "migrate database", "rollback migration", or needs guidance on safe database schema modifications.
+---
+
+# Database Migration
+
+Safe patterns for database schema modifications with rollback capabilities.
+
+## Quick Reference
+
+| Phase | Actions |
+|-------|---------|
+| Plan | Review changes, identify risks, plan rollback |
+| Prepare | Backup, test in staging, validate syntax |
+| Execute | Apply in maintenance window, monitor |
+| Verify | Check data integrity, test application |
+
+## Migration Workflow
+
+### 1. Plan Migration
+
+Before writing migration:
+- Document current schema state
+- Identify all affected tables
+- Plan rollback strategy
+
+### 2. Write Migration
+
+-- migrations/001_add_user_email.sql
+-- Rollback: ALTER TABLE users DROP COLUMN email;
+
+ALTER TABLE users ADD COLUMN email VARCHAR(255);
+CREATE INDEX idx_users_email ON users(email);
+
+For examples, see `examples/simple-migration.sql`.
+
+### 3. Validate Before Execution
+
+Run validation script:
+
+./scripts/validate-migration.sh migrations/001_add_user_email.sql
+
+### 4. Execute Migration
+
+# Backup first
+pg_dump dbname > backup_$(date +%Y%m%d).sql
+
+# Apply migration
+psql dbname < migrations/001_add_user_email.sql
+
+## Rollback Procedures
+
+If issues detected, rollback immediately. See `references/rollback-procedures.md`.
+
+## Additional Resources
+
+### Reference Files
+- **`references/rollback-procedures.md`** - Step-by-step rollback for different scenarios
+
+### Examples
+- **`examples/simple-migration.sql`** - Basic ALTER TABLE migration
+
+### Scripts
+- **`scripts/validate-migration.sh`** - Syntax and safety validation
+```
+
+### Commentary
+
+This complete structure works because:
+- **SKILL.md as orchestrator**: Points to all resources
+- **Scripts execute blindly**: validate-migration.sh runs without context consumption
+- **Examples are copyable**: SQL ready to adapt
+- **References for depth**: Rollback details available when needed
+
+---
+
+## Key Takeaways
+
+1. **Match structure to complexity**: Simple = minimal, complex = complete
+
+2. **SKILL.md is the index**: Always reference supporting files
+
+3. **Progressive disclosure works**: Start lean, expand to references as needed
+
+4. **Scripts save tokens**: Execute without loading into context
+
+5. **Examples should be complete**: Provide working, copy-paste ready code

package/.claude/skills/skill-development/references/progressive-disclosure.md

@@ -0,0 +1,141 @@
+# Progressive Disclosure in Skills
+
+Design principle for managing context efficiently through three-level loading.
+
+## Core Concept
+
+Progressive disclosure means information loads only when needed:
+
+1. **Metadata** - Always in context (description triggers skill)
+2. **Body** - Loads when skill triggers (core instructions)
+3. **Resources** - Loads as Claude needs them (detailed content)
+
+## Directory Structure Pattern
+
+```
+skill-name/
+├── SKILL.md              # Always loaded when skill triggers
+├── references/           # Loaded as Claude consults them
+│   ├── patterns.md
+│   ├── advanced.md
+│   └── api-reference.md
+├── examples/             # Loaded when Claude needs examples
+│   ├── basic-example.sh
+│   └── advanced-example.py
+└── scripts/              # Executed without loading into context
+    ├── validate.sh
+    └── helper.py
+```
+
+## When to Use Each Level
+
+### SKILL.md (Body)
+
+**Include**:
+- Core concepts and overview
+- Essential workflows and procedures
+- Quick reference tables
+- Pointers to references/examples/scripts
+- Most common use cases
+
+**Size target**: 1,500-2,000 words (max 3,000)
+
+**Rule**: If in doubt, move it to references/
+
+### references/
+
+**Move here**:
+- Detailed patterns and advanced techniques
+- Comprehensive API documentation
+- Migration guides and edge cases
+- Extensive troubleshooting
+
+**Size**: Each file can be 2,000-5,000+ words
+
+**Naming conventions**:
+- `patterns.md` - Common patterns
+- `advanced.md` - Advanced use cases
+- `api-reference.md` - API documentation
+- `troubleshooting.md` - Problems and solutions
+
+### examples/
+
+**Include**:
+- Complete, runnable code
+- Configuration files that work
+- Template files users can copy
+
+**Characteristics**:
+- Self-contained and functional
+- Well-commented
+- Cover different use cases (basic, intermediate, advanced)
+
+### scripts/
+
+**Include**:
+- Validation utilities
+- Testing helpers
+- Automation scripts
+
+**Key benefit**: Scripts execute without loading into context window.
+
+## Example Directory Layouts
+
+### API Integration Skill
+
+```
+api-integration/
+├── SKILL.md                    # Quick start, core endpoints
+├── references/
+│   ├── authentication.md       # Auth patterns, token handling
+│   └── rate-limiting.md        # Rate limit handling
+├── examples/
+│   ├── basic-request.py
+│   └── batch-operations.py
+└── scripts/
+    └── validate-credentials.sh
+```
+
+### Database Migration Skill
+
+```
+db-migration/
+├── SKILL.md                    # Migration workflow, safety checks
+├── references/
+│   ├── rollback-procedures.md
+│   └── schema-patterns.md
+├── examples/
+│   ├── simple-migration.sql
+│   └── data-migration.py
+└── scripts/
+    └── validate-migration.sh
+```
+
+## Anti-Patterns
+
+### Everything in SKILL.md
+
+**Problem**: 8,000 word SKILL.md file
+
+**Solution**: Extract detailed sections to references/, keep SKILL.md under 2,000 words
+
+### Unreferenced Resources
+
+**Problem**: Files in references/ but no mention in SKILL.md
+
+**Solution**: Always reference supporting files in SKILL.md body
+
+### Scripts That Need Reading
+
+**Problem**: Script requires Claude to read and understand before execution
+
+**Solution**: If Claude must read it, it's documentation (put in references/)
+
+## Context Budget Guidelines
+
+| Component | Target | Max |
+|-----------|--------|-----|
+| Description | ~100 chars | 1024 chars |
+| SKILL.md body | 1,500-2,000 words | 3,000 words |
+| Single reference file | 2,000-3,000 words | 5,000+ words |
+| Total references/ | N/A | No limit (loaded as needed) |