compound-engineering-pi 0.2.3

package/skills/create-agent-skills/references/recommended-structure.md

@@ -0,0 +1,168 @@
+# Recommended Skill Structure
+
+The optimal structure for complex skills separates routing, workflows, and knowledge.
+
+<structure>
+```
+skill-name/
+├── SKILL.md              # Router + essential principles (unavoidable)
+├── workflows/            # Step-by-step procedures (how)
+│   ├── workflow-a.md
+│   ├── workflow-b.md
+│   └── ...
+└── references/           # Domain knowledge (what)
+    ├── reference-a.md
+    ├── reference-b.md
+    └── ...
+```
+</structure>
+
+<why_this_works>
+## Problems This Solves
+
+**Problem 1: Context gets skipped**
+When important principles are in a separate file, Claude may not read them.
+**Solution:** Put essential principles directly in SKILL.md. They load automatically.
+
+**Problem 2: Wrong context loaded**
+A "build" task loads debugging references. A "debug" task loads build references.
+**Solution:** Intake question determines intent → routes to specific workflow → workflow specifies which references to read.
+
+**Problem 3: Monolithic skills are overwhelming**
+500+ lines of mixed content makes it hard to find relevant parts.
+**Solution:** Small router (SKILL.md) + focused workflows + reference library.
+
+**Problem 4: Procedures mixed with knowledge**
+"How to do X" mixed with "What X means" creates confusion.
+**Solution:** Workflows are procedures (steps). References are knowledge (patterns, examples).
+</why_this_works>
+
+<skill_md_template>
+## SKILL.md Template
+
+```markdown
+---
+name: skill-name
+description: What it does and when to use it.
+---
+
+<essential_principles>
+## How This Skill Works
+
+[Inline principles that apply to ALL workflows. Cannot be skipped.]
+
+### Principle 1: [Name]
+[Brief explanation]
+
+### Principle 2: [Name]
+[Brief explanation]
+</essential_principles>
+
+<intake>
+**Ask the user:**
+
+What would you like to do?
+1. [Option A]
+2. [Option B]
+3. [Option C]
+4. Something else
+
+**Wait for response before proceeding.**
+</intake>
+
+<routing>
+| Response | Workflow |
+|----------|----------|
+| 1, "keyword", "keyword" | `workflows/option-a.md` |
+| 2, "keyword", "keyword" | `workflows/option-b.md` |
+| 3, "keyword", "keyword" | `workflows/option-c.md` |
+| 4, other | Clarify, then select |
+
+**After reading the workflow, follow it exactly.**
+</routing>
+
+<reference_index>
+All domain knowledge in `references/`:
+
+**Category A:** file-a.md, file-b.md
+**Category B:** file-c.md, file-d.md
+</reference_index>
+
+<workflows_index>
+| Workflow | Purpose |
+|----------|---------|
+| option-a.md | [What it does] |
+| option-b.md | [What it does] |
+| option-c.md | [What it does] |
+</workflows_index>
+```
+</skill_md_template>
+
+<workflow_template>
+## Workflow Template
+
+```markdown
+# Workflow: [Name]
+
+<required_reading>
+**Read these reference files NOW:**
+1. references/relevant-file.md
+2. references/another-file.md
+</required_reading>
+
+<process>
+## Step 1: [Name]
+[What to do]
+
+## Step 2: [Name]
+[What to do]
+
+## Step 3: [Name]
+[What to do]
+</process>
+
+<success_criteria>
+This workflow is complete when:
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+</success_criteria>
+```
+</workflow_template>
+
+<when_to_use_this_pattern>
+## When to Use This Pattern
+
+**Use router + workflows + references when:**
+- Multiple distinct workflows (build vs debug vs ship)
+- Different workflows need different references
+- Essential principles must not be skipped
+- Skill has grown beyond 200 lines
+
+**Use simple single-file skill when:**
+- One workflow
+- Small reference set
+- Under 200 lines total
+- No essential principles to enforce
+</when_to_use_this_pattern>
+
+<key_insight>
+## The Key Insight
+
+**SKILL.md is always loaded. Use this guarantee.**
+
+Put unavoidable content in SKILL.md:
+- Essential principles
+- Intake question
+- Routing logic
+
+Put workflow-specific content in workflows/:
+- Step-by-step procedures
+- Required references for that workflow
+- Success criteria for that workflow
+
+Put reusable knowledge in references/:
+- Patterns and examples
+- Technical details
+- Domain expertise
+</key_insight>

package/skills/create-agent-skills/references/skill-structure.md

@@ -0,0 +1,152 @@
+# Skill Structure Reference
+
+Skills have three structural components: YAML frontmatter (metadata), standard markdown body (content), and progressive disclosure (file organization).
+
+## Body Format
+
+Use **standard markdown headings** for structure. Keep markdown formatting within content (bold, italic, lists, code blocks, links).
+
+```markdown
+---
+name: my-skill
+description: What it does and when to use it
+---
+
+# Skill Name
+
+## Quick Start
+Immediate actionable guidance...
+
+## Instructions
+Step-by-step procedures...
+
+## Examples
+Concrete usage examples...
+
+## Guidelines
+Rules and constraints...
+```
+
+## Recommended Sections
+
+Every skill should have:
+
+- **Quick Start** - Immediate, actionable guidance (minimal working example)
+- **Instructions** - Core step-by-step guidance
+- **Success Criteria** - How to know it worked
+
+Add based on complexity:
+
+- **Context** - Background/situational information
+- **Workflow** - Multi-step procedures
+- **Examples** - Concrete input/output pairs
+- **Advanced Features** - Deep-dive topics (link to reference files)
+- **Anti-Patterns** - Common mistakes to avoid
+- **Guidelines** - Rules and constraints
+
+## YAML Frontmatter
+
+### Required/Recommended Fields
+
+```yaml
+---
+name: skill-name-here
+description: What it does and when to use it (specific triggers included)
+---
+```
+
+### Name Field
+
+**Validation rules:**
+- Maximum 64 characters
+- Lowercase letters, numbers, hyphens only
+- Must match directory name
+- No reserved words: "anthropic", "claude"
+
+**Examples:**
+- `triage-prs`
+- `deploy-production`
+- `review-code`
+- `setup-stripe-payments`
+
+**Avoid:** `helper`, `utils`, `tools`, generic names
+
+### Description Field
+
+**Validation rules:**
+- Maximum 1024 characters
+- Include what it does AND when to use it
+- Third person voice
+
+**Good:**
+```yaml
+description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
+```
+
+**Bad:**
+```yaml
+description: Helps with documents
+```
+
+### Optional Fields
+
+| Field | Description |
+|-------|-------------|
+| `argument-hint` | Usage hints. Example: `[issue-number]` |
+| `disable-model-invocation` | `true` to prevent auto-loading. Use for side-effect workflows. |
+| `user-invocable` | `false` to hide from `/` menu. Use for background knowledge. |
+| `allowed-tools` | Tools without permission prompts. Example: `Read, Bash(git *)` |
+| `model` | `haiku`, `sonnet`, or `opus` |
+| `context` | `fork` for isolated subagent execution |
+| `agent` | Subagent type: `Explore`, `Plan`, `general-purpose`, or custom |
+
+## Naming Conventions
+
+Use descriptive names that indicate purpose:
+
+| Pattern | Examples |
+|---------|----------|
+| Action-oriented | `triage-prs`, `deploy-production`, `review-code` |
+| Domain-specific | `setup-stripe-payments`, `manage-facebook-ads` |
+| Descriptive | `git-worktree`, `frontend-design`, `dhh-rails-style` |
+
+## Progressive Disclosure
+
+Keep SKILL.md under 500 lines. Split into reference files:
+
+```
+my-skill/
+├── SKILL.md           # Entry point (required, overview + navigation)
+├── reference.md       # Detailed docs (loaded when needed)
+├── examples.md        # Usage examples (loaded when needed)
+└── scripts/
+    └── helper.py      # Utility script (executed, not loaded)
+```
+
+**Rules:**
+- Keep references one level deep from SKILL.md
+- Add table of contents to reference files over 100 lines
+- Use forward slashes in paths: `scripts/helper.py`
+- Name files descriptively: `form_validation_rules.md` not `doc2.md`
+
+## Validation Checklist
+
+Before finalizing:
+
+- [ ] YAML frontmatter valid (name matches directory, description specific)
+- [ ] Uses standard markdown headings (not XML tags)
+- [ ] Has Quick Start, Instructions, and Success Criteria sections
+- [ ] `disable-model-invocation: true` if skill has side effects
+- [ ] SKILL.md under 500 lines
+- [ ] Reference files linked properly from SKILL.md
+- [ ] File paths use forward slashes
+- [ ] Tested with real usage
+
+## Anti-Patterns
+
+- **XML tags in body** - Use standard markdown headings
+- **Vague descriptions** - Be specific with trigger keywords
+- **Deep nesting** - Keep references one level from SKILL.md
+- **Missing invocation control** - Side-effect workflows need `disable-model-invocation: true`
+- **Inconsistent naming** - Directory name must match `name` field
+- **Windows paths** - Always use forward slashes

package/skills/create-agent-skills/references/using-scripts.md

@@ -0,0 +1,113 @@
+# Using Scripts in Skills
+
+<purpose>
+Scripts are executable code that Claude runs as-is rather than regenerating each time. They ensure reliable, error-free execution of repeated operations.
+</purpose>
+
+<when_to_use>
+Use scripts when:
+- The same code runs across multiple skill invocations
+- Operations are error-prone when rewritten from scratch
+- Complex shell commands or API interactions are involved
+- Consistency matters more than flexibility
+
+Common script types:
+- **Deployment** - Deploy to Vercel, publish packages, push releases
+- **Setup** - Initialize projects, install dependencies, configure environments
+- **API calls** - Authenticated requests, webhook handlers, data fetches
+- **Data processing** - Transform files, batch operations, migrations
+- **Build processes** - Compile, bundle, test runners
+</when_to_use>
+
+<script_structure>
+Scripts live in `scripts/` within the skill directory:
+
+```
+skill-name/
+├── SKILL.md
+├── workflows/
+├── references/
+├── templates/
+└── scripts/
+    ├── deploy.sh
+    ├── setup.py
+    └── fetch-data.ts
+```
+
+A well-structured script includes:
+1. Clear purpose comment at top
+2. Input validation
+3. Error handling
+4. Idempotent operations where possible
+5. Clear output/feedback
+</script_structure>
+
+<script_example>
+```bash
+#!/bin/bash
+# deploy.sh - Deploy project to Vercel
+# Usage: ./deploy.sh [environment]
+# Environments: preview (default), production
+
+set -euo pipefail
+
+ENVIRONMENT="${1:-preview}"
+
+# Validate environment
+if [[ "$ENVIRONMENT" != "preview" && "$ENVIRONMENT" != "production" ]]; then
+    echo "Error: Environment must be 'preview' or 'production'"
+    exit 1
+fi
+
+echo "Deploying to $ENVIRONMENT..."
+
+if [[ "$ENVIRONMENT" == "production" ]]; then
+    vercel --prod
+else
+    vercel
+fi
+
+echo "Deployment complete."
+```
+</script_example>
+
+<workflow_integration>
+Workflows reference scripts like this:
+
+```xml
+<process>
+## Step 5: Deploy
+
+1. Ensure all tests pass
+2. Run `scripts/deploy.sh production`
+3. Verify deployment succeeded
+4. Update user with deployment URL
+</process>
+```
+
+The workflow tells Claude WHEN to run the script. The script handles HOW the operation executes.
+</workflow_integration>
+
+<best_practices>
+**Do:**
+- Make scripts idempotent (safe to run multiple times)
+- Include clear usage comments
+- Validate inputs before executing
+- Provide meaningful error messages
+- Use `set -euo pipefail` in bash scripts
+
+**Don't:**
+- Hardcode secrets or credentials (use environment variables)
+- Create scripts for one-off operations
+- Skip error handling
+- Make scripts do too many unrelated things
+- Forget to make scripts executable (`chmod +x`)
+</best_practices>
+
+<security_considerations>
+- Never embed API keys, tokens, or secrets in scripts
+- Use environment variables for sensitive configuration
+- Validate and sanitize any user-provided inputs
+- Be cautious with scripts that delete or modify data
+- Consider adding `--dry-run` options for destructive operations
+</security_considerations>

package/skills/create-agent-skills/references/using-templates.md

@@ -0,0 +1,112 @@
+# Using Templates in Skills
+
+<purpose>
+Templates are reusable output structures that Claude copies and fills in. They ensure consistent, high-quality outputs without regenerating structure each time.
+</purpose>
+
+<when_to_use>
+Use templates when:
+- Output should have consistent structure across invocations
+- The structure matters more than creative generation
+- Filling placeholders is more reliable than blank-page generation
+- Users expect predictable, professional-looking outputs
+
+Common template types:
+- **Plans** - Project plans, implementation plans, migration plans
+- **Specifications** - Technical specs, feature specs, API specs
+- **Documents** - Reports, proposals, summaries
+- **Configurations** - Config files, settings, environment setups
+- **Scaffolds** - File structures, boilerplate code
+</when_to_use>
+
+<template_structure>
+Templates live in `templates/` within the skill directory:
+
+```
+skill-name/
+├── SKILL.md
+├── workflows/
+├── references/
+└── templates/
+    ├── plan-template.md
+    ├── spec-template.md
+    └── report-template.md
+```
+
+A template file contains:
+1. Clear section markers
+2. Placeholder indicators (use `{{placeholder}}` or `[PLACEHOLDER]`)
+3. Inline guidance for what goes where
+4. Example content where helpful
+</template_structure>
+
+<template_example>
+```markdown
+# {{PROJECT_NAME}} Implementation Plan
+
+## Overview
+{{1-2 sentence summary of what this plan covers}}
+
+## Goals
+- {{Primary goal}}
+- {{Secondary goals...}}
+
+## Scope
+**In scope:**
+- {{What's included}}
+
+**Out of scope:**
+- {{What's explicitly excluded}}
+
+## Phases
+
+### Phase 1: {{Phase name}}
+**Duration:** {{Estimated duration}}
+**Deliverables:**
+- {{Deliverable 1}}
+- {{Deliverable 2}}
+
+### Phase 2: {{Phase name}}
+...
+
+## Success Criteria
+- [ ] {{Measurable criterion 1}}
+- [ ] {{Measurable criterion 2}}
+
+## Risks
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| {{Risk}} | {{H/M/L}} | {{H/M/L}} | {{Strategy}} |
+```
+</template_example>
+
+<workflow_integration>
+Workflows reference templates like this:
+
+```xml
+<process>
+## Step 3: Generate Plan
+
+1. Read `templates/plan-template.md`
+2. Copy the template structure
+3. Fill each placeholder based on gathered requirements
+4. Review for completeness
+</process>
+```
+
+The workflow tells Claude WHEN to use the template. The template provides WHAT structure to produce.
+</workflow_integration>
+
+<best_practices>
+**Do:**
+- Keep templates focused on structure, not content
+- Use clear placeholder syntax consistently
+- Include brief inline guidance where sections might be ambiguous
+- Make templates complete but minimal
+
+**Don't:**
+- Put excessive example content that might be copied verbatim
+- Create templates for outputs that genuinely need creative generation
+- Over-constrain with too many required sections
+- Forget to update templates when requirements change
+</best_practices>