claude-all-hands 1.0.1 → 1.0.3

package/.claude/skills/skills-development/workflows/create-new-skill.md

@@ -0,0 +1,191 @@
+# Workflow: Create a New Skill
+
+<required_reading>
+**Read these reference files NOW:**
+1. references/recommended-structure.md
+2. references/skill-structure.md
+3. references/core-principles.md
+4. references/use-xml-tags.md
+</required_reading>
+
+<process>
+## Step 1: Adaptive Requirements Gathering
+
+**If user provided context** (e.g., "build a skill for X"):
+→ Analyze what's stated, what can be inferred, what's unclear
+→ Skip to asking about genuine gaps only
+
+**If user just invoked skill without context:**
+→ Ask what they want to build
+
+### Using AskUserQuestion
+
+Ask 2-4 domain-specific questions based on actual gaps. Each question should:
+- Have specific options with descriptions
+- Focus on scope, complexity, outputs, boundaries
+- NOT ask things obvious from context
+
+Example questions:
+- "What specific operations should this skill handle?" (with options based on domain)
+- "Should this also handle [related thing] or stay focused on [core thing]?"
+- "What should the user see when successful?"
+
+### Decision Gate
+
+After initial questions, ask:
+"Ready to proceed with building, or would you like me to ask more questions?"
+
+Options:
+1. **Proceed to building** - I have enough context
+2. **Ask more questions** - There are more details to clarify
+3. **Let me add details** - I want to provide additional context
+
+## Step 2: Research Trigger (If External API)
+
+**When external service detected**, ask using AskUserQuestion:
+"This involves [service name] API. Would you like me to research current endpoints and patterns before building?"
+
+Options:
+1. **Yes, research first** - Fetch current documentation for accurate implementation
+2. **No, proceed with general patterns** - Use common patterns without specific API research
+
+If research requested:
+- Use Context7 MCP to fetch current library documentation
+- Or use WebSearch for recent API documentation
+- Focus on 2024-2025 sources
+- Store findings for use in content generation
+
+## Step 3: Decide Structure
+
+**Simple skill (single workflow, <200 lines):**
+→ Single SKILL.md file with all content
+
+**Complex skill (multiple workflows OR domain knowledge):**
+→ Router pattern:
+```
+skill-name/
+├── SKILL.md (router + principles)
+├── workflows/ (procedures - FOLLOW)
+├── references/ (knowledge - READ)
+├── templates/ (output structures - COPY + FILL)
+└── scripts/ (reusable code - EXECUTE)
+```
+
+Factors favoring router pattern:
+- Multiple distinct user intents (create vs debug vs ship)
+- Shared domain knowledge across workflows
+- Essential principles that must not be skipped
+- Skill likely to grow over time
+
+**Consider templates/ when:**
+- Skill produces consistent output structures (plans, specs, reports)
+- Structure matters more than creative generation
+
+**Consider scripts/ when:**
+- Same code runs across invocations (deploy, setup, API calls)
+- Operations are error-prone when rewritten each time
+
+See references/recommended-structure.md for templates.
+
+## Step 4: Create Directory
+
+```bash
+mkdir -p ~/.claude/skills/{skill-name}
+# If complex:
+mkdir -p ~/.claude/skills/{skill-name}/workflows
+mkdir -p ~/.claude/skills/{skill-name}/references
+# If needed:
+mkdir -p ~/.claude/skills/{skill-name}/templates  # for output structures
+mkdir -p ~/.claude/skills/{skill-name}/scripts    # for reusable code
+```
+
+## Step 5: Write SKILL.md
+
+**Simple skill:** Write complete skill file with:
+- YAML frontmatter (name, description)
+- `<objective>`
+- `<quick_start>`
+- Content sections with pure XML
+- `<success_criteria>`
+
+**Complex skill:** Write router with:
+- YAML frontmatter
+- `<essential_principles>` (inline, unavoidable)
+- `<intake>` (question to ask user)
+- `<routing>` (maps answers to workflows)
+- `<reference_index>` and `<workflows_index>`
+
+## Step 6: Write Workflows (if complex)
+
+For each workflow:
+```xml
+<required_reading>
+Which references to load for this workflow
+</required_reading>
+
+<process>
+Step-by-step procedure
+</process>
+
+<success_criteria>
+How to know this workflow is done
+</success_criteria>
+```
+
+## Step 7: Write References (if needed)
+
+Domain knowledge that:
+- Multiple workflows might need
+- Doesn't change based on workflow
+- Contains patterns, examples, technical details
+
+## Step 8: Validate Structure
+
+Check:
+- [ ] YAML frontmatter valid
+- [ ] Name matches directory (lowercase-with-hyphens)
+- [ ] Description says what it does AND when to use it (third person)
+- [ ] No markdown headings (#) in body - use XML tags
+- [ ] Required tags present: objective, quick_start, success_criteria
+- [ ] All referenced files exist
+- [ ] SKILL.md under 500 lines
+- [ ] XML tags properly closed
+
+## Step 9: Create Slash Command
+
+```bash
+cat > ~/.claude/commands/{skill-name}.md << 'EOF'
+---
+description: {Brief description}
+argument-hint: [{argument hint}]
+allowed-tools: Skill({skill-name})
+---
+
+Invoke the {skill-name} skill for: $ARGUMENTS
+EOF
+```
+
+## Step 10: Test
+
+Invoke the skill and observe:
+- Does it ask the right intake question?
+- Does it load the right workflow?
+- Does the workflow load the right references?
+- Does output match expectations?
+
+Iterate based on real usage, not assumptions.
+</process>
+
+<success_criteria>
+Skill is complete when:
+- [ ] Requirements gathered with appropriate questions
+- [ ] API research done if external service involved
+- [ ] Directory structure correct
+- [ ] SKILL.md has valid frontmatter
+- [ ] Essential principles inline (if complex skill)
+- [ ] Intake question routes to correct workflow
+- [ ] All workflows have required_reading + process + success_criteria
+- [ ] References contain reusable domain knowledge
+- [ ] Slash command exists and works
+- [ ] Tested with real invocation
+</success_criteria>

package/.claude/skills/skills-development/workflows/get-guidance.md

@@ -0,0 +1,121 @@
+# Workflow: Get Guidance on Skill Design
+
+<required_reading>
+**Read these reference files NOW:**
+1. references/core-principles.md
+2. references/recommended-structure.md
+</required_reading>
+
+<process>
+## Step 1: Understand the Problem Space
+
+Ask the user:
+- What task or domain are you trying to support?
+- Is this something you do repeatedly?
+- What makes it complex enough to need a skill?
+
+## Step 2: Determine If a Skill Is Right
+
+**Create a skill when:**
+- Task is repeated across multiple sessions
+- Domain knowledge doesn't change frequently
+- Complex enough to benefit from structure
+- Would save significant time if automated
+
+**Don't create a skill when:**
+- One-off task (just do it directly)
+- Changes constantly (will be outdated quickly)
+- Too simple (overhead isn't worth it)
+- Better as a slash command (user-triggered, no context needed)
+
+Share this assessment with user.
+
+## Step 3: Map the Workflows
+
+Ask: "What are the different things someone might want to do with this skill?"
+
+Common patterns:
+- Create / Read / Update / Delete
+- Build / Debug / Ship
+- Setup / Use / Troubleshoot
+- Import / Process / Export
+
+Each distinct workflow = potential workflow file.
+
+## Step 4: Identify Domain Knowledge
+
+Ask: "What knowledge is needed regardless of which workflow?"
+
+This becomes references:
+- API patterns
+- Best practices
+- Common examples
+- Configuration details
+
+## Step 5: Draft the Structure
+
+Based on answers, recommend structure:
+
+**If 1 workflow, simple knowledge:**
+```
+skill-name/
+└── SKILL.md (everything in one file)
+```
+
+**If 2+ workflows, shared knowledge:**
+```
+skill-name/
+├── SKILL.md (router)
+├── workflows/
+│   ├── workflow-a.md
+│   └── workflow-b.md
+└── references/
+    └── shared-knowledge.md
+```
+
+## Step 6: Identify Essential Principles
+
+Ask: "What rules should ALWAYS apply, no matter which workflow?"
+
+These become `<essential_principles>` in SKILL.md.
+
+Examples:
+- "Always verify before reporting success"
+- "Never store credentials in code"
+- "Ask before making destructive changes"
+
+## Step 7: Present Recommendation
+
+Summarize:
+- Recommended structure (simple vs router pattern)
+- List of workflows
+- List of references
+- Essential principles
+
+Ask: "Does this structure make sense? Ready to build it?"
+
+If yes → offer to switch to "Create a new skill" workflow
+If no → clarify and iterate
+</process>
+
+<decision_framework>
+## Quick Decision Framework
+
+| Situation | Recommendation |
+|-----------|----------------|
+| Single task, repeat often | Simple skill |
+| Multiple related tasks | Router + workflows |
+| Complex domain, many patterns | Router + workflows + references |
+| User-triggered, fresh context | Slash command, not skill |
+| One-off task | No skill needed |
+</decision_framework>
+
+<success_criteria>
+Guidance is complete when:
+- [ ] User understands if they need a skill
+- [ ] Structure is recommended and explained
+- [ ] Workflows are identified
+- [ ] References are identified
+- [ ] Essential principles are identified
+- [ ] User is ready to build (or decided not to)
+</success_criteria>

package/.claude/skills/skills-development/workflows/upgrade-to-router.md

@@ -0,0 +1,161 @@
+# Workflow: Upgrade Skill to Router Pattern
+
+<required_reading>
+**Read these reference files NOW:**
+1. references/recommended-structure.md
+2. references/skill-structure.md
+</required_reading>
+
+<process>
+## Step 1: Select the Skill
+
+```bash
+ls ~/.claude/skills/
+```
+
+Present numbered list, ask: "Which skill should be upgraded to the router pattern?"
+
+## Step 2: Verify It Needs Upgrading
+
+Read the skill:
+```bash
+cat ~/.claude/skills/{skill-name}/SKILL.md
+ls ~/.claude/skills/{skill-name}/
+```
+
+**Already a router?** (has workflows/ and intake question)
+→ Tell user it's already using router pattern, offer to add workflows instead
+
+**Simple skill that should stay simple?** (under 200 lines, single workflow)
+→ Explain that router pattern may be overkill, ask if they want to proceed anyway
+
+**Good candidate for upgrade:**
+- Over 200 lines
+- Multiple distinct use cases
+- Essential principles that shouldn't be skipped
+- Growing complexity
+
+## Step 3: Identify Components
+
+Analyze the current skill and identify:
+
+1. **Essential principles** - Rules that apply to ALL use cases
+2. **Distinct workflows** - Different things a user might want to do
+3. **Reusable knowledge** - Patterns, examples, technical details
+
+Present findings:
+```
+## Analysis
+
+**Essential principles I found:**
+- [Principle 1]
+- [Principle 2]
+
+**Distinct workflows I identified:**
+- [Workflow A]: [description]
+- [Workflow B]: [description]
+
+**Knowledge that could be references:**
+- [Reference topic 1]
+- [Reference topic 2]
+```
+
+Ask: "Does this breakdown look right? Any adjustments?"
+
+## Step 4: Create Directory Structure
+
+```bash
+mkdir -p ~/.claude/skills/{skill-name}/workflows
+mkdir -p ~/.claude/skills/{skill-name}/references
+```
+
+## Step 5: Extract Workflows
+
+For each identified workflow:
+
+1. Create `workflows/{workflow-name}.md`
+2. Add required_reading section (references it needs)
+3. Add process section (steps from original skill)
+4. Add success_criteria section
+
+## Step 6: Extract References
+
+For each identified reference topic:
+
+1. Create `references/{reference-name}.md`
+2. Move relevant content from original skill
+3. Structure with semantic XML tags
+
+## Step 7: Rewrite SKILL.md as Router
+
+Replace SKILL.md with router structure:
+
+```markdown
+---
+name: {skill-name}
+description: {existing description}
+---
+
+<essential_principles>
+[Extracted principles - inline, cannot be skipped]
+</essential_principles>
+
+<intake>
+**Ask the user:**
+
+What would you like to do?
+1. [Workflow A option]
+2. [Workflow B option]
+...
+
+**Wait for response before proceeding.**
+</intake>
+
+<routing>
+| Response | Workflow |
+|----------|----------|
+| 1, "keywords" | `workflows/workflow-a.md` |
+| 2, "keywords" | `workflows/workflow-b.md` |
+</routing>
+
+<reference_index>
+[List all references by category]
+</reference_index>
+
+<workflows_index>
+| Workflow | Purpose |
+|----------|---------|
+| workflow-a.md | [What it does] |
+| workflow-b.md | [What it does] |
+</workflows_index>
+```
+
+## Step 8: Verify Nothing Was Lost
+
+Compare original skill content against new structure:
+- [ ] All principles preserved (now inline)
+- [ ] All procedures preserved (now in workflows)
+- [ ] All knowledge preserved (now in references)
+- [ ] No orphaned content
+
+## Step 9: Test
+
+Invoke the upgraded skill:
+- Does intake question appear?
+- Does each routing option work?
+- Do workflows load correct references?
+- Does behavior match original skill?
+
+Report any issues.
+</process>
+
+<success_criteria>
+Upgrade is complete when:
+- [ ] workflows/ directory created with workflow files
+- [ ] references/ directory created (if needed)
+- [ ] SKILL.md rewritten as router
+- [ ] Essential principles inline in SKILL.md
+- [ ] All original content preserved
+- [ ] Intake question routes correctly
+- [ ] Tested and working
+</success_criteria>

package/.claude/skills/skills-development/workflows/verify-skill.md

@@ -0,0 +1,204 @@
+# Workflow: Verify Skill Content Accuracy
+
+<required_reading>
+**Read these reference files NOW:**
+1. references/skill-structure.md
+</required_reading>
+
+<purpose>
+Audit checks structure. **Verify checks truth.**
+
+Skills contain claims about external things: APIs, CLI tools, frameworks, services. These change over time. This workflow checks if a skill's content is still accurate.
+</purpose>
+
+<process>
+## Step 1: Select the Skill
+
+```bash
+ls ~/.claude/skills/
+```
+
+Present numbered list, ask: "Which skill should I verify for accuracy?"
+
+## Step 2: Read and Categorize
+
+Read the entire skill (SKILL.md + workflows/ + references/):
+```bash
+cat ~/.claude/skills/{skill-name}/SKILL.md
+cat ~/.claude/skills/{skill-name}/workflows/*.md 2>/dev/null
+cat ~/.claude/skills/{skill-name}/references/*.md 2>/dev/null
+```
+
+Categorize by primary dependency type:
+
+| Type | Examples | Verification Method |
+|------|----------|---------------------|
+| **API/Service** | manage-stripe, manage-gohighlevel | Context7 + WebSearch |
+| **CLI Tools** | build-macos-apps (xcodebuild, swift) | Run commands |
+| **Framework** | build-iphone-apps (SwiftUI, UIKit) | Context7 for docs |
+| **Integration** | setup-stripe-payments | WebFetch + Context7 |
+| **Pure Process** | create-agent-skills | No external deps |
+
+Report: "This skill is primarily [type]-based. I'll verify using [method]."
+
+## Step 3: Extract Verifiable Claims
+
+Scan skill content and extract:
+
+**CLI Tools mentioned:**
+- Tool names (xcodebuild, swift, npm, etc.)
+- Specific flags/options documented
+- Expected output patterns
+
+**API Endpoints:**
+- Service names (Stripe, Meta, etc.)
+- Specific endpoints documented
+- Authentication methods
+- SDK versions
+
+**Framework Patterns:**
+- Framework names (SwiftUI, React, etc.)
+- Specific APIs/patterns documented
+- Version-specific features
+
+**File Paths/Structures:**
+- Expected project structures
+- Config file locations
+
+Present: "Found X verifiable claims to check."
+
+## Step 4: Verify by Type
+
+### For CLI Tools
+```bash
+# Check tool exists
+which {tool-name}
+
+# Check version
+{tool-name} --version
+
+# Verify documented flags work
+{tool-name} --help | grep "{documented-flag}"
+```
+
+### For API/Service Skills
+Use Context7 to fetch current documentation:
+```
+mcp__context7__resolve-library-id: {service-name}
+mcp__context7__get-library-docs: {library-id}, topic: {relevant-topic}
+```
+
+Compare skill's documented patterns against current docs:
+- Are endpoints still valid?
+- Has authentication changed?
+- Are there deprecated methods being used?
+
+### For Framework Skills
+Use Context7:
+```
+mcp__context7__resolve-library-id: {framework-name}
+mcp__context7__get-library-docs: {library-id}, topic: {specific-api}
+```
+
+Check:
+- Are documented APIs still current?
+- Have patterns changed?
+- Are there newer recommended approaches?
+
+### For Integration Skills
+WebSearch for recent changes:
+```
+"[service name] API changes 2025"
+"[service name] breaking changes"
+"[service name] deprecated endpoints"
+```
+
+Then Context7 for current SDK patterns.
+
+### For Services with Status Pages
+WebFetch official docs/changelog if available.
+
+## Step 5: Generate Freshness Report
+
+Present findings:
+
+```
+## Verification Report: {skill-name}
+
+### ✅ Verified Current
+- [Claim]: [Evidence it's still accurate]
+
+### ⚠️ May Be Outdated
+- [Claim]: [What changed / newer info found]
+  → Current: [what docs now say]
+
+### ❌ Broken / Invalid
+- [Claim]: [Why it's wrong]
+  → Fix: [What it should be]
+
+### ℹ️ Could Not Verify
+- [Claim]: [Why verification wasn't possible]
+
+---
+**Overall Status:** [Fresh / Needs Updates / Significantly Stale]
+**Last Verified:** [Today's date]
+```
+
+## Step 6: Offer Updates
+
+If issues found:
+
+"Found [N] items that need updating. Would you like me to:"
+
+1. **Update all** - Apply all corrections
+2. **Review each** - Show each change before applying
+3. **Just the report** - No changes
+
+If updating:
+- Make changes based on verified current information
+- Add verification date comment if appropriate
+- Report what was updated
+
+## Step 7: Suggest Verification Schedule
+
+Based on skill type, recommend:
+
+| Skill Type | Recommended Frequency |
+|------------|----------------------|
+| API/Service | Every 1-2 months |
+| Framework | Every 3-6 months |
+| CLI Tools | Every 6 months |
+| Pure Process | Annually |
+
+"This skill should be re-verified in approximately [timeframe]."
+</process>
+
+<verification_shortcuts>
+## Quick Verification Commands
+
+**Check if CLI tool exists and get version:**
+```bash
+which {tool} && {tool} --version
+```
+
+**Context7 pattern for any library:**
+```
+1. resolve-library-id: "{library-name}"
+2. get-library-docs: "{id}", topic: "{specific-feature}"
+```
+
+**WebSearch patterns:**
+- Breaking changes: "{service} breaking changes 2025"
+- Deprecations: "{service} deprecated API"
+- Current best practices: "{framework} best practices 2025"
+</verification_shortcuts>
+
+<success_criteria>
+Verification is complete when:
+- [ ] Skill categorized by dependency type
+- [ ] Verifiable claims extracted
+- [ ] Each claim checked with appropriate method
+- [ ] Freshness report generated
+- [ ] Updates applied (if requested)
+- [ ] User knows when to re-verify
+</success_criteria>