gsd-pi 2.28.0 → 2.29.0-dev.2ccf3fb

package/dist/resources/skills/create-skill/workflows/add-script.md

@@ -0,0 +1,93 @@
+# Workflow: Add a Script to a Skill
+
+<required_reading>
+**Read these reference files NOW:**
+1. references/using-scripts.md
+</required_reading>
+
+<process>
+## Step 1: Identify the Skill
+
+Ask (if not already provided):
+- Which skill needs a script?
+- What operation should the script perform?
+
+## Step 2: Analyze Script Need
+
+Confirm this is a good script candidate:
+- [ ] Same code runs across multiple invocations
+- [ ] Operation is error-prone when rewritten
+- [ ] Consistency matters more than flexibility
+
+If not a good fit, suggest alternatives (inline code in workflow, reference examples).
+
+## Step 3: Create Scripts Directory
+
+```bash
+mkdir -p ~/.claude/skills/{skill-name}/scripts
+```
+
+## Step 4: Design Script
+
+Gather requirements:
+- What inputs does the script need?
+- What should it output or accomplish?
+- What errors might occur?
+- Should it be idempotent?
+
+Choose language:
+- **bash** - Shell operations, file manipulation, CLI tools
+- **python** - Data processing, API calls, complex logic
+- **node/ts** - JavaScript ecosystem, async operations
+
+## Step 5: Write Script File
+
+Create `scripts/{script-name}.{ext}` with:
+- Purpose comment at top
+- Usage instructions
+- Input validation
+- Error handling
+- Clear output/feedback
+
+For bash scripts:
+```bash
+#!/bin/bash
+set -euo pipefail
+```
+
+## Step 6: Make Executable (if bash)
+
+```bash
+chmod +x ~/.claude/skills/{skill-name}/scripts/{script-name}.sh
+```
+
+## Step 7: Update Workflow to Use Script
+
+Find the workflow that needs this operation. Add:
+```xml
+<process>
+...
+N. Run `scripts/{script-name}.sh [arguments]`
+N+1. Verify operation succeeded
+...
+</process>
+```
+
+## Step 8: Test
+
+Invoke the skill workflow and verify:
+- Script runs at the right step
+- Inputs are passed correctly
+- Errors are handled gracefully
+- Output matches expectations
+</process>
+
+<success_criteria>
+Script is complete when:
+- [ ] scripts/ directory exists
+- [ ] Script file has proper structure (comments, validation, error handling)
+- [ ] Script is executable (if bash)
+- [ ] At least one workflow references the script
+- [ ] No hardcoded secrets or credentials
+- [ ] Tested with real invocation
+</success_criteria>

package/dist/resources/skills/create-skill/workflows/add-template.md

@@ -0,0 +1,74 @@
+# Workflow: Add a Template to a Skill
+
+<required_reading>
+**Read these reference files NOW:**
+1. references/using-templates.md
+</required_reading>
+
+<process>
+## Step 1: Identify the Skill
+
+Ask (if not already provided):
+- Which skill needs a template?
+- What output does this template structure?
+
+## Step 2: Analyze Template Need
+
+Confirm this is a good template candidate:
+- [ ] Output has consistent structure across uses
+- [ ] Structure matters more than creative generation
+- [ ] Filling placeholders is more reliable than blank-page generation
+
+If not a good fit, suggest alternatives (workflow guidance, reference examples).
+
+## Step 3: Create Templates Directory
+
+```bash
+mkdir -p ~/.claude/skills/{skill-name}/templates
+```
+
+## Step 4: Design Template Structure
+
+Gather requirements:
+- What sections does the output need?
+- What information varies between uses? (→ placeholders)
+- What stays constant? (→ static structure)
+
+## Step 5: Write Template File
+
+Create `templates/{template-name}.md` with:
+- Clear section markers
+- `{{PLACEHOLDER}}` syntax for variable content
+- Brief inline guidance where helpful
+- Minimal example content
+
+## Step 6: Update Workflow to Use Template
+
+Find the workflow that produces this output. Add:
+```xml
+<process>
+...
+N. Read `templates/{template-name}.md`
+N+1. Copy template structure
+N+2. Fill each placeholder based on gathered context
+...
+</process>
+```
+
+## Step 7: Test
+
+Invoke the skill workflow and verify:
+- Template is read at the right step
+- All placeholders get filled appropriately
+- Output structure matches template
+- No placeholders left unfilled
+</process>
+
+<success_criteria>
+Template is complete when:
+- [ ] templates/ directory exists
+- [ ] Template file has clear structure with placeholders
+- [ ] At least one workflow references the template
+- [ ] Workflow instructions explain when/how to use template
+- [ ] Tested with real invocation
+</success_criteria>

package/dist/resources/skills/create-skill/workflows/add-workflow.md

@@ -0,0 +1,120 @@
+# Workflow: Add a Workflow to Existing Skill
+
+<required_reading>
+**Read these reference files NOW:**
+1. references/recommended-structure.md
+2. references/workflows-and-validation.md
+</required_reading>
+
+<process>
+## Step 1: Select the Skill
+
+**DO NOT use AskUserQuestion** - there may be many skills.
+
+```bash
+ls ~/.claude/skills/
+```
+
+Present numbered list, ask: "Which skill needs a new workflow?"
+
+## Step 2: Analyze Current Structure
+
+Read the skill:
+```bash
+cat ~/.claude/skills/{skill-name}/SKILL.md
+ls ~/.claude/skills/{skill-name}/workflows/ 2>/dev/null
+```
+
+Determine:
+- **Simple skill?** → May need to upgrade to router pattern first
+- **Already has workflows/?** → Good, can add directly
+- **What workflows exist?** → Avoid duplication
+
+Report current structure to user.
+
+## Step 3: Gather Workflow Requirements
+
+Ask using AskUserQuestion or direct question:
+- What should this workflow do?
+- When would someone use it vs existing workflows?
+- What references would it need?
+
+## Step 4: Upgrade to Router Pattern (if needed)
+
+**If skill is currently simple (no workflows/):**
+
+Ask: "This skill needs to be upgraded to the router pattern first. Should I restructure it?"
+
+If yes:
+1. Create workflows/ directory
+2. Move existing process content to workflows/main.md
+3. Rewrite SKILL.md as router with intake + routing
+4. Verify structure works before proceeding
+
+## Step 5: Create the Workflow File
+
+Create `workflows/{workflow-name}.md`:
+
+```markdown
+# Workflow: {Workflow Name}
+
+<required_reading>
+**Read these reference files NOW:**
+1. references/{relevant-file}.md
+</required_reading>
+
+<process>
+## Step 1: {First Step}
+[What to do]
+
+## Step 2: {Second Step}
+[What to do]
+
+## Step 3: {Third Step}
+[What to do]
+</process>
+
+<success_criteria>
+This workflow is complete when:
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+</success_criteria>
+```
+
+## Step 6: Update SKILL.md
+
+Add the new workflow to:
+
+1. **Intake question** - Add new option
+2. **Routing table** - Map option to workflow file
+3. **Workflows index** - Add to the list
+
+## Step 7: Create References (if needed)
+
+If the workflow needs domain knowledge that doesn't exist:
+1. Create `references/{reference-name}.md`
+2. Add to reference_index in SKILL.md
+3. Reference it in the workflow's required_reading
+
+## Step 8: Test
+
+Invoke the skill:
+- Does the new option appear in intake?
+- Does selecting it route to the correct workflow?
+- Does the workflow load the right references?
+- Does the workflow execute correctly?
+
+Report results to user.
+</process>
+
+<success_criteria>
+Workflow addition is complete when:
+- [ ] Skill upgraded to router pattern (if needed)
+- [ ] Workflow file created with required_reading, process, success_criteria
+- [ ] SKILL.md intake updated with new option
+- [ ] SKILL.md routing updated
+- [ ] SKILL.md workflows_index updated
+- [ ] Any needed references created
+- [ ] Tested and working
+</success_criteria>

package/dist/resources/skills/create-skill/workflows/audit-skill.md

@@ -0,0 +1,148 @@
+# Workflow: Audit a Skill
+
+<required_reading>
+**Read these reference files NOW:**
+1. references/recommended-structure.md
+2. references/skill-structure.md
+3. references/use-xml-tags.md
+4. references/gsd-skill-ecosystem.md
+</required_reading>
+
+<process>
+## Step 1: List Available Skills
+
+**DO NOT use AskUserQuestion** - there may be many skills.
+
+Enumerate skills from both directories:
+```bash
+echo "=== Global skills ==="
+ls ~/.gsd/agent/skills/ 2>/dev/null || echo "(none)"
+
+echo "=== Project-local skills ==="
+ls .pi/agent/skills/ 2>/dev/null || echo "(none)"
+```
+
+Present as:
+```
+Available skills:
+
+Global (~/.gsd/agent/skills/):
+1. create-skill
+2. manage-stripe
+...
+
+Project-local (.pi/agent/skills/):
+3. project-deploy
+...
+```
+
+Ask: "Which skill would you like to audit? (enter number or name)"
+
+## Step 2: Read the Skill
+
+After user selects, read the full skill structure:
+```bash
+# Read main file
+cat {skill-path}/SKILL.md
+
+# Check for workflows and references
+ls {skill-path}/
+ls {skill-path}/workflows/ 2>/dev/null
+ls {skill-path}/references/ 2>/dev/null
+```
+
+## Step 3: Run Audit Checklist
+
+Evaluate against each criterion:
+
+### YAML Frontmatter
+- [ ] Has `name:` field (lowercase-with-hyphens)
+- [ ] Name matches directory name
+- [ ] Has `description:` field
+- [ ] Description says what it does AND when to use it
+- [ ] Description is third person ("Use when...")
+
+### Structure
+- [ ] SKILL.md under 500 lines
+- [ ] Pure XML structure (no markdown headings # in body)
+- [ ] All XML tags properly closed
+- [ ] Has required tags: objective OR essential_principles
+- [ ] Has success_criteria
+
+### Router Pattern (if complex skill)
+- [ ] Essential principles inline in SKILL.md (not in separate file)
+- [ ] Has intake question
+- [ ] Has routing table
+- [ ] All referenced workflow files exist
+- [ ] All referenced reference files exist
+
+### Workflows (if present)
+- [ ] Each has required_reading section
+- [ ] Each has process section
+- [ ] Each has success_criteria section
+- [ ] Required reading references exist
+
+### Content Quality
+- [ ] Principles are actionable (not vague platitudes)
+- [ ] Steps are specific (not "do the thing")
+- [ ] Success criteria are verifiable
+- [ ] No redundant content across files
+
+## Step 4: Generate Report
+
+Present findings as:
+
+```
+## Audit Report: {skill-name}
+
+### Passing
+- [list passing items]
+
+### Issues Found
+1. **[Issue name]**: [Description]
+   → Fix: [Specific action]
+
+2. **[Issue name]**: [Description]
+   → Fix: [Specific action]
+
+### Score: X/Y criteria passing
+```
+
+## Step 5: Offer Fixes
+
+If issues found, ask:
+"Would you like me to fix these issues?"
+
+Options:
+1. **Fix all** - Apply all recommended fixes
+2. **Fix one by one** - Review each fix before applying
+3. **Just the report** - No changes needed
+
+If fixing:
+- Make each change
+- Verify file validity after each change
+- Report what was fixed
+</process>
+
+<audit_anti_patterns>
+## Common Anti-Patterns to Flag
+
+**Skippable principles**: Essential principles in separate file instead of inline
+**Monolithic skill**: Single file over 500 lines
+**Mixed concerns**: Procedures and knowledge in same file
+**Vague steps**: "Handle the error appropriately"
+**Untestable criteria**: "User is satisfied"
+**Markdown headings in body**: Using # instead of XML tags
+**Missing routing**: Complex skill without intake/routing
+**Broken references**: Files mentioned but don't exist
+**Redundant content**: Same information in multiple places
+</audit_anti_patterns>
+
+<success_criteria>
+Audit is complete when:
+- [ ] Skill fully read and analyzed
+- [ ] All checklist items evaluated
+- [ ] Report presented to user
+- [ ] Fixes applied (if requested)
+- [ ] User has clear picture of skill health
+</success_criteria>

package/dist/resources/skills/create-skill/workflows/create-new-skill.md

@@ -0,0 +1,196 @@
+# 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
+5. references/gsd-skill-ecosystem.md
+</required_reading>
+
+<process>
+## Step 1: Determine Scope
+
+**Ask the user:**
+"Should this skill be global or project-local?"
+
+1. **Global** (`~/.gsd/agent/skills/`) — Available in all GSD sessions
+2. **Project-local** (`.pi/agent/skills/`) — Available only in this project
+
+## Step 2: 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 3: 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 4: 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 5: Create Directory
+
+Use the scope selected in Step 1 to determine the base path:
+- **Global:** `~/.gsd/agent/skills/{skill-name}`
+- **Project-local:** `.pi/agent/skills/{skill-name}`
+
+```bash
+BASE_PATH="{selected-base}/agent/skills/{skill-name}"
+mkdir -p $BASE_PATH
+# If complex:
+mkdir -p $BASE_PATH/workflows
+mkdir -p $BASE_PATH/references
+# If needed:
+mkdir -p $BASE_PATH/templates  # for output structures
+mkdir -p $BASE_PATH/scripts    # for reusable code
+```
+
+## Step 6: 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 7: 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 8: Write References (if needed)
+
+Domain knowledge that:
+- Multiple workflows might need
+- Doesn't change based on workflow
+- Contains patterns, examples, technical details
+
+## Step 9: 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 10: Activate
+
+Run `/reload` to make the skill available in the current session. Skills are auto-discovered on next session start.
+
+## Step 11: 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:
+- [ ] Scope selected (global or project-local)
+- [ ] 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
+- [ ] /reload run to activate
+- [ ] Tested with real invocation
+</success_criteria>