claude-all-hands 1.0.0 → 1.0.1

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

@@ -3,15 +3,33 @@ 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
+<objective>
+Guide creation of effective Claude Code skills with proper structure, progressive disclosure, and validation. Skills extend Claude's capabilities through specialized knowledge and workflows, packaged as discoverable capabilities invoked autonomously based on description triggers.
+</objective>
+
+<quick_start>
+1. Create `.claude/skills/skill-name/SKILL.md`
+2. Add frontmatter: `name` (lowercase-hyphenated) + `description` (trigger phrases)
+3. Write body in imperative form (~500-700 words)
+4. Add references/examples/scripts only if content exceeds body capacity
+</quick_start>
+
+<success_criteria>
+- SKILL.md exists with valid YAML frontmatter
+- `name`: lowercase-hyphenated, max 64 chars
+- `description`: max 1024 chars, includes trigger phrases
+- Body uses imperative form (not second person)
+- Body ~500-700 words (excess moved to references/)
+</success_criteria>
+
+<constraints>
+- Description MUST use "Use when..." format with specific triggers
+- Body MUST use imperative/infinitive form (not "you should")
+- Resources only created when necessary (most skills are SKILL.md only)
+- Max 1024 chars for description field
+</constraints>
+
+## Skill Anatomy
 
 ```
 skill-name/
@@ -24,9 +42,7 @@ skill-name/
     └── scripts/        - Utilities, executable
 ```
 
-### Progressive Disclosure
-
-Three-level loading for context efficiency:
+## Progressive Disclosure
 
 | Level | Contents | When Loaded | Size Target |
 |-------|----------|-------------|-------------|
@@ -34,65 +50,35 @@ Three-level loading for context efficiency:
 | 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
+<workflow name="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
-
+**Frontmatter**:
 ```yaml
 ---
 name: skill-name          # lowercase-hyphenated, max 64 chars
-description: [trigger description, max 1024 chars]
+description: Use when user asks to "create X", "configure Y". Provides [capability].
 ---
 ```
 
-**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
-
+**Body structure**:
 ```markdown
 # Skill Name
 
@@ -105,47 +91,25 @@ Essential patterns, commands, key concepts.
 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
+- [ ] `description` field: max 1024 chars, includes triggers
+- [ ] Body uses imperative form
+- [ ] Body ~500-700 words
 
 ### Step 6: Iterate
-
-After using the skill on real tasks:
-
-1. Notice struggles or inefficiencies
-2. Identify improvements to SKILL.md or resources
+1. Notice struggles or inefficiencies during use
+2. Identify improvements
 3. Implement changes
 4. Test again
 
-## Degrees of Freedom
+</workflow>
 
-Match constraint level to task criticality:
+## Degrees of Freedom
 
 | Level | When to Use | Example |
 |-------|-------------|---------|
@@ -153,10 +117,9 @@ Match constraint level to task criticality:
 | Medium (parameterized) | Preferred pattern exists | Script with configurable params |
 | Low (exact) | Fragile/critical ops | Exact shell commands |
 
-## Common Mistakes
+<examples>
 
 ### Weak Trigger Description
-
 **Bad**:
 ```yaml
 description: Provides guidance for working with hooks.
@@ -167,36 +130,20 @@ description: Provides guidance for working with hooks.
 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
+### Skill Structures
 
-### Minimal Skill
+**Minimal**:
 ```
 skill-name/
 └── SKILL.md
 ```
 
-### Standard Skill (Recommended)
+**Standard** (Recommended):
 ```
 skill-name/
 ├── SKILL.md
@@ -206,31 +153,16 @@ skill-name/
     └── working-example.sh
 ```
 
-### Complete Skill
-```
-skill-name/
-├── SKILL.md
-├── references/
-│   ├── patterns.md
-│   └── advanced.md
-├── examples/
-│   ├── example1.sh
-│   └── example2.json
-└── scripts/
-    └── validate.sh
-```
+</examples>
 
 ## 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
+- **`references/progressive-disclosure.md`** - Directory structure patterns
+- **`references/writing-style.md`** - Imperative form rules
 
 ### Examples
-
-- **`examples/complete-skill-examples.md`** - Annotated complete skills with commentary
+- **`examples/complete-skill-examples.md`** - Annotated complete skills
 
 ### Scripts
-
-- **`scripts/validate-skill.sh`** - Validate skill file structure and content
+- **`scripts/validate-skill.sh`** - Validate skill file structure

package/.claude/skills/specialist-builder/SKILL.md

@@ -3,13 +3,34 @@ name: specialist-builder
 description: Use when user asks to "create an agent", "add a subagent", or needs guidance on agent frontmatter, triggering examples, system prompts, tools, or colors.
 ---
 
-# Specialist Builder
-
-Build specialist agents tailored to repository domains.
-
-For initial research this is a great researouce of specialist plugins (which ship agents with their commands and skills) (see their agent.md files):
-**https://github.com/wshobson/agents/tree/main/plugins**
+<objective>
+Build specialist agents tailored to repository domains. Specialists are READ-ONLY subagents that return information to the main agent for implementation.
+</objective>
+
+<quick_start>
+1. Research domain via research-tools skill
+2. Extract repo patterns via repomix-extraction skill
+3. Confirm agent name with user
+4. Gather requirements (scope, pattern, skills, tools)
+5. Generate agent definition following frontmatter spec
+6. Auto-create companion maintenance skill
+</quick_start>
+
+<success_criteria>
+- Agent has valid YAML frontmatter (name, description, model, color)
+- Description includes trigger keywords and ONE `<example>` block with variant syntax
+- Agent scope is focused (narrow specialists over broad ones)
+- Companion maintenance skill created
+</success_criteria>
+
+<constraints>
+- Specialists are READ-ONLY - they return information, main agent implements
+- Description MUST include WHEN to trigger (main agent uses this for dispatch)
+- Use ONE condensed `<example>` block with variant syntax (`|`) for trigger phrases
+- Name format: lowercase, numbers, hyphens only, 3-50 chars, start/end alphanumeric
+</constraints>
 
+<workflow>
 ## When Triggered
 
 Main agent calls curator with this skill when:
@@ -22,9 +43,9 @@ Main agent calls curator with this skill when:
 ### Inference Logic
 
 When curator invocation already specifies details, skip those questions:
-- Specialist name specified → skip name confirmation
-- Source directories specified → skip directory question
-- Specific domain described → skip option proposal, go direct to requirements
+- Specialist name specified -> skip name confirmation
+- Source directories specified -> skip directory question
+- Specific domain described -> skip option proposal, go direct to requirements
 
 ### 1. Research Phase (required)
 
@@ -146,7 +167,29 @@ If custom skill selected in requirements:
 "This specialist needs a custom skill. Would you like to define it now?"
 - If yes: use skill-development skill to create it
 - If no: note as TODO in agent file
+</workflow>
+
+<validation>
+## Agent File Checklist
 
+- [ ] `name`: lowercase-hyphens, 3-50 chars, alphanumeric start/end
+- [ ] `description`: includes trigger keywords + ONE `<example>` block
+- [ ] `model`: set (recommend `inherit`)
+- [ ] `color`: set based on agent type
+- [ ] `allowed-tools`: follows least privilege principle
+- [ ] System prompt: includes behavioral boundaries, methodologies, output format
+
+## Reference Files
+
+| File | Content |
+|------|---------|
+| `references/triggering-examples.md` | Example block anatomy and patterns |
+| `references/system-prompt-patterns.md` | Four agent pattern templates |
+| `examples/complete-agent-examples.md` | Full working agent examples |
+| `scripts/validate-agent.sh` | Validate agent file structure and content |
+</validation>
+
+<examples>
 ## Agent File Structure
 
 ### Complete Format
@@ -162,7 +205,7 @@ description: |
   </example>
 model: inherit
 color: blue
-allowed-tools: Read, Glob, Grep
+tools: Read, Glob, Grep
 skills: repomix-extraction, skill-name
 ---
 
@@ -183,12 +226,6 @@ You are [agent role description]...
 
 ### name (required)
 
-Agent identifier used for namespacing and invocation.
-
-**Format:** lowercase, numbers, hyphens only
-**Length:** 3-50 characters
-**Pattern:** Must start and end with alphanumeric
-
 **Good examples:**
 - `code-reviewer`
 - `test-generator`
@@ -198,16 +235,9 @@ Agent identifier used for namespacing and invocation.
 - `helper` (too generic)
 - `-agent-` (starts/ends with hyphen)
 - `my_agent` (underscores not allowed)
-- `ag` (too short)
 
 ### description (required)
 
-Defines when Claude should trigger this agent. **Most critical field.**
-
-**Must include:**
-1. Concise description with trigger keywords and responsibility scope
-2. ONE `<example>` block with variant syntax for compression
-
 **Format (condensed pattern):**
 ```yaml
 description: |
@@ -218,8 +248,6 @@ description: |
   </example>
 ```
 
-**Variant syntax:** Use `|` to separate trigger phrase variants within a single example. This compresses multiple triggering scenarios into minimal context.
-
 **Example:**
 ```yaml
 description: |
@@ -230,28 +258,17 @@ description: |
   </example>
 ```
 
-**Do NOT include:**
-- Multiple `<example>` blocks (use variant syntax instead)
-- `<commentary>` blocks (description conveys reasoning)
-- Context or assistant response lines
-
-See `references/triggering-examples.md` for additional patterns.
-
 ### model (required)
 
-Which model the agent should use.
-
-**Options:**
-- `inherit` - Use same model as parent (recommended)
-- `sonnet` - Claude Sonnet (balanced)
-- `opus` - Claude Opus (most capable)
-- `haiku` - Claude Haiku (fast)
+| Option | Use |
+|--------|-----|
+| `inherit` | Same as parent (recommended) |
+| `sonnet` | Balanced |
+| `opus` | Most capable |
+| `haiku` | Fast |
 
 ### color (required)
 
-Visual identifier for agent in UI.
-
-**Guidelines:**
 | Color | Use For |
 |-------|---------|
 | blue/cyan | Analysis, review |
@@ -260,24 +277,17 @@ Visual identifier for agent in UI.
 | red | Critical, security |
 | magenta | Creative, generation |
 
-### allowed-tools (optional)
-
-Restrict agent to specific tools. **Principle of least privilege.**
+### tools (optional)
 
-**Common tool sets:**
-- Read-only analysis: `Read, Grep, Glob`
-- Code generation: `Read, Write, Grep`
-- Testing: `Read, Bash, Grep`
-- Full access: Omit field to inherit all
-
-### skills (optional)
-
-Skills to auto-load when agent starts. Comma-separated list.
+| Tool Set | Use Case |
+|----------|----------|
+| `Read, Grep, Glob` | Read-only analysis |
+| `Read, Write, Grep` | Code generation |
+| `Read, Bash, Grep` | Testing |
+| (omit) | Full access |
 
 ## System Prompt Patterns
 
-Four patterns for agent system prompts. See `references/system-prompt-patterns.md` for templates.
-
 | Pattern | Use When |
 |---------|----------|
 | Analysis | Reviewing, auditing, researching |
@@ -285,46 +295,6 @@ Four patterns for agent system prompts. See `references/system-prompt-patterns.m
 | Validation | Checking, verifying, linting |
 | Orchestration | Multi-step workflows |
 
-## AI-Assisted Agent Generation
-
-For complex agents, use this prompt template:
-
-```json
-{
-  "request": "[USER DESCRIPTION]",
-  "requirements": {
-    "core_intent": "Extract primary purpose",
-    "persona": "Define expert role for domain",
-    "system_prompt": {
-      "behavioral_boundaries": true,
-      "specific_methodologies": true,
-      "edge_case_handling": true,
-      "output_format": true
-    },
-    "identifier": "lowercase-hyphens, 3-50 chars",
-    "description": "trigger keywords + ONE condensed example block",
-    "example": "ONE <example> with variant syntax (trigger1 | trigger2 | trigger3)"
-  }
-}
-```
-
-## Key Principles
-
-- Specialists are READ-ONLY - they return information, main agent implements
-- Description must include WHEN to trigger (main agent uses this for dispatch)
-- Keep scope focused - better to have multiple narrow specialists than one broad one
-- Skills determine what knowledge/capabilities the specialist has access to
-- Use ONE condensed `<example>` block with variant syntax (`|`) for trigger phrases
-
-## Reference Files
-
-| File | Content |
-|------|---------|
-| `references/triggering-examples.md` | Example block anatomy and patterns |
-| `references/system-prompt-patterns.md` | Four agent pattern templates |
-| `examples/complete-agent-examples.md` | Full working agent examples |
-| `scripts/validate-agent.sh` | Validate agent file structure and content |
-
 ## Agent-Skill Workflow Pattern
 
 When an agent has workflow skills, the agent profile should:
@@ -338,11 +308,20 @@ Example in agent file:
 
 When main agent asks to [prompt pattern], use the [skill-name] skill.
 ```
+</examples>
 
-**Why this works:**
-- Agent's `skills:` frontmatter lists skills to auto-load into context
-- Main agent triggers agent based on description examples
-- Agent body references skill by name - skill content already available
-- No duplication: skill owns workflow logic, agent owns triggering conditions
+<anti_patterns>
+| Anti-Pattern | Problem | Correct Approach |
+|--------------|---------|------------------|
+| Multiple `<example>` blocks | Wastes context | Use variant syntax with `\|` separator |
+| Generic name like `helper` | Unclear purpose | Specific domain names like `code-reviewer` |
+| Broad scope | Jack of all trades | Multiple narrow specialists |
+| Duplicate workflow in agent | Redundancy | Keep workflow in skill, agent references it |
+| Missing trigger keywords | Agent not dispatched | Description MUST include when to trigger |
+| Write access for analysis agents | Violates read-only | Use `allowed-tools: Read, Grep, Glob` |
 
-This keeps agent files lean and workflow logic centralized in skills.
+## Research Resource
+
+For initial research this is a great resource of specialist plugins (which ship agents with their commands and skills):
+**https://github.com/wshobson/agents/tree/main/plugins**
+</anti_patterns>

package/.claude/skills/specialist-builder/examples/complete-agent-examples.md

@@ -15,7 +15,7 @@ description: |
   </example>
 model: inherit
 color: cyan
-allowed-tools: Read, Grep, Glob, Bash
+tools: Read, Grep, Glob, Bash
 ---
 
 You are a senior code reviewer ensuring high standards of code quality and security.
@@ -78,7 +78,7 @@ description: |
   </example>
 model: inherit
 color: green
-allowed-tools: Read, Write, Grep, Glob
+tools: Read, Write, Grep, Glob
 ---
 
 You are an expert test engineer specializing in creating comprehensive, maintainable test suites.
@@ -145,7 +145,7 @@ description: |
   </example>
 model: inherit
 color: red
-allowed-tools: Read, Grep, Glob
+tools: Read, Grep, Glob
 ---
 
 You are a security expert specializing in identifying vulnerabilities and ensuring secure coding practices.
@@ -199,7 +199,7 @@ You are a security expert specializing in identifying vulnerabilities and ensuri
 
 2. **System prompts follow the pattern structure**: Role definition, responsibilities, process steps, quality standards, output format, edge cases.
 
-3. **allowed-tools match responsibilities**: Read-only agents get read tools, generation agents get write tools.
+3. **tools match responsibilities**: Read-only agents get read tools, generation agents get write tools.
 
 4. **Colors signal purpose**: cyan=analysis, green=success/generation, red=security, magenta=creative/orchestration.