gsd-pi 2.28.0 → 2.29.0-dev.2ccf3fb

package/dist/resources/skills/create-skill/references/use-xml-tags.md

@@ -0,0 +1,466 @@
+<overview>
+Skills use pure XML structure for consistent parsing, efficient token usage, and improved Claude performance. This reference defines the required and conditional XML tags for skill authoring, along with intelligence rules for tag selection.
+</overview>
+
+<critical_rule>
+**Remove ALL markdown headings (#, ##, ###) from skill body content.** Replace with semantic XML tags. Keep markdown formatting WITHIN content (bold, italic, lists, code blocks, links).
+</critical_rule>
+
+<required_tags>
+Every skill MUST have these three tags:
+
+<tag name="objective">
+**Purpose**: What the skill does and why it matters. Sets context and scope.
+
+**Content**: 1-3 paragraphs explaining the skill's purpose, domain, and value proposition.
+
+**Example**:
+```xml
+<objective>
+Extract text and tables from PDF files, fill forms, and merge documents using Python libraries. This skill provides patterns for common PDF operations without requiring external services or APIs.
+</objective>
+```
+</tag>
+
+<tag name="quick_start">
+**Purpose**: Immediate, actionable guidance. Gets Claude started quickly without reading advanced sections.
+
+**Content**: Minimal working example, essential commands, or basic usage pattern.
+
+**Example**:
+```xml
+<quick_start>
+Extract text with pdfplumber:
+
+```python
+import pdfplumber
+with pdfplumber.open("file.pdf") as pdf:
+    text = pdf.pages[0].extract_text()
+```
+</quick_start>
+```
+</tag>
+
+<tag name="success_criteria">
+**Purpose**: How to know the task worked. Defines completion criteria.
+
+**Alternative name**: `<when_successful>` (use whichever fits better)
+
+**Content**: Clear criteria for successful execution, validation steps, or expected outputs.
+
+**Example**:
+```xml
+<success_criteria>
+A well-structured skill has:
+
+- Valid YAML frontmatter with descriptive name and description
+- Pure XML structure with no markdown headings in body
+- Required tags: objective, quick_start, success_criteria
+- Progressive disclosure (SKILL.md < 500 lines, details in reference files)
+- Real-world testing and iteration based on observed behavior
+</success_criteria>
+```
+</tag>
+</required_tags>
+
+<conditional_tags>
+Add these tags based on skill complexity and domain requirements:
+
+<tag name="context">
+**When to use**: Background or situational information that Claude needs before starting.
+
+**Example**:
+```xml
+<context>
+The Facebook Marketing API uses a hierarchy: Account → Campaign → Ad Set → Ad. Each level has different configuration options and requires specific permissions. Always verify API access before making changes.
+</context>
+```
+</tag>
+
+<tag name="workflow">
+**When to use**: Step-by-step procedures, sequential operations, multi-step processes.
+
+**Alternative name**: `<process>`
+
+**Example**:
+```xml
+<workflow>
+1. **Analyze the form**: Run analyze_form.py to extract field definitions
+2. **Create field mapping**: Edit fields.json with values
+3. **Validate mapping**: Run validate_fields.py
+4. **Fill the form**: Run fill_form.py
+5. **Verify output**: Check generated PDF
+</workflow>
+```
+</tag>
+
+<tag name="advanced_features">
+**When to use**: Deep-dive topics that most users won't need (progressive disclosure).
+
+**Example**:
+```xml
+<advanced_features>
+**Custom styling**: See [styling.md](styling.md)
+**Template inheritance**: See [templates.md](templates.md)
+**API reference**: See [reference.md](reference.md)
+</advanced_features>
+```
+</tag>
+
+<tag name="validation">
+**When to use**: Skills with verification steps, quality checks, or validation scripts.
+
+**Example**:
+```xml
+<validation>
+After making changes, validate immediately:
+
+```bash
+python scripts/validate.py output_dir/
+```
+
+Only proceed when validation passes. If errors occur, review and fix before continuing.
+</validation>
+```
+</tag>
+
+<tag name="examples">
+**When to use**: Multi-shot learning, input/output pairs, demonstrating patterns.
+
+**Example**:
+```xml
+<examples>
+<example number="1">
+<input>User clicked signup button</input>
+<output>track('signup_initiated', { source: 'homepage' })</output>
+</example>
+
+<example number="2">
+<input>Purchase completed</input>
+<output>track('purchase', { value: 49.99, currency: 'USD' })</output>
+</example>
+</examples>
+```
+</tag>
+
+<tag name="anti_patterns">
+**When to use**: Common mistakes that Claude should avoid.
+
+**Example**:
+```xml
+<anti_patterns>
+<pitfall name="vague_descriptions">
+- ❌ "Helps with documents"
+- ✅ "Extract text and tables from PDF files"
+</pitfall>
+
+<pitfall name="too_many_options">
+- ❌ "You can use pypdf, or pdfplumber, or PyMuPDF..."
+- ✅ "Use pdfplumber for text extraction. For OCR, use pytesseract instead."
+</pitfall>
+</anti_patterns>
+```
+</tag>
+
+<tag name="security_checklist">
+**When to use**: Skills with security implications (API keys, payments, authentication).
+
+**Example**:
+```xml
+<security_checklist>
+- Never log API keys or tokens
+- Always use environment variables for credentials
+- Validate all user input before API calls
+- Use HTTPS for all external requests
+- Check API response status before proceeding
+</security_checklist>
+```
+</tag>
+
+<tag name="testing">
+**When to use**: Testing workflows, test patterns, or validation steps.
+
+**Example**:
+```xml
+<testing>
+Test with all target models (Haiku, Sonnet, Opus):
+
+1. Run skill on representative tasks
+2. Observe where Claude struggles or succeeds
+3. Iterate based on actual behavior
+4. Validate XML structure after changes
+</testing>
+```
+</tag>
+
+<tag name="common_patterns">
+**When to use**: Code examples, recipes, or reusable patterns.
+
+**Example**:
+```xml
+<common_patterns>
+<pattern name="error_handling">
+```python
+try:
+    result = process_file(path)
+except FileNotFoundError:
+    print(f"File not found: {path}")
+except Exception as e:
+    print(f"Error: {e}")
+```
+</pattern>
+</common_patterns>
+```
+</tag>
+
+<tag name="reference_guides">
+**When to use**: Links to detailed reference files (progressive disclosure).
+
+**Alternative name**: `<detailed_references>`
+
+**Example**:
+```xml
+<reference_guides>
+For deeper topics, see reference files:
+
+**API operations**: [references/api-operations.md](references/api-operations.md)
+**Security patterns**: [references/security.md](references/security.md)
+**Troubleshooting**: [references/troubleshooting.md](references/troubleshooting.md)
+</reference_guides>
+```
+</tag>
+</conditional_tags>
+
+<intelligence_rules>
+<decision_tree>
+**Simple skills** (single domain, straightforward):
+- Required tags only: objective, quick_start, success_criteria
+- Example: Text extraction, file format conversion, simple calculations
+
+**Medium skills** (multiple patterns, some complexity):
+- Required tags + workflow/examples as needed
+- Example: Document processing with steps, API integration with configuration
+
+**Complex skills** (multiple domains, security, APIs):
+- Required tags + conditional tags as appropriate
+- Example: Payment processing, authentication systems, multi-step workflows with validation
+</decision_tree>
+
+<principle>
+Don't over-engineer simple skills. Don't under-specify complex skills. Match tag selection to actual complexity and user needs.
+</principle>
+
+<when_to_add_conditional>
+Ask these questions:
+
+- **Context needed?** → Add `<context>`
+- **Multi-step process?** → Add `<workflow>` or `<process>`
+- **Advanced topics to hide?** → Add `<advanced_features>` + reference files
+- **Validation required?** → Add `<validation>`
+- **Pattern demonstration?** → Add `<examples>`
+- **Common mistakes?** → Add `<anti_patterns>`
+- **Security concerns?** → Add `<security_checklist>`
+- **Testing guidance?** → Add `<testing>`
+- **Code recipes?** → Add `<common_patterns>`
+- **Deep references?** → Add `<reference_guides>`
+</when_to_add_conditional>
+</intelligence_rules>
+
+<xml_vs_markdown_headings>
+<token_efficiency>
+XML tags are more efficient than markdown headings:
+
+**Markdown headings**:
+```markdown
+## Quick start
+## Workflow
+## Advanced features
+## Success criteria
+```
+Total: ~20 tokens, no semantic meaning to Claude
+
+**XML tags**:
+```xml
+<quick_start>
+<workflow>
+<advanced_features>
+<success_criteria>
+```
+Total: ~15 tokens, semantic meaning built-in
+</token_efficiency>
+
+<parsing_accuracy>
+XML provides unambiguous boundaries and semantic meaning. Claude can reliably:
+- Identify section boundaries
+- Understand content purpose
+- Skip irrelevant sections
+- Parse programmatically
+
+Markdown headings are just visual formatting. Claude must infer meaning from heading text.
+</parsing_accuracy>
+
+<consistency>
+XML enforces consistent structure across all skills. All skills use the same tag names for the same purposes. Makes it easier to:
+- Validate skill structure programmatically
+- Learn patterns across skills
+- Maintain consistent quality
+</consistency>
+</xml_vs_markdown_headings>
+
+<nesting_guidelines>
+<proper_nesting>
+XML tags can nest for hierarchical content:
+
+```xml
+<examples>
+<example number="1">
+<input>User input here</input>
+<output>Expected output here</output>
+</example>
+
+<example number="2">
+<input>Another input</input>
+<output>Another output</output>
+</example>
+</examples>
+```
+</proper_nesting>
+
+<closing_tags>
+Always close tags properly:
+
+✅ Good:
+```xml
+<objective>
+Content here
+</objective>
+```
+
+❌ Bad:
+```xml
+<objective>
+Content here
+```
+</closing_tags>
+
+<tag_naming>
+Use descriptive, semantic names:
+- `<workflow>` not `<steps>`
+- `<success_criteria>` not `<done>`
+- `<anti_patterns>` not `<dont_do>`
+
+Be consistent within your skill. If you use `<workflow>`, don't also use `<process>` for the same purpose.
+</tag_naming>
+</nesting_guidelines>
+
+<anti_pattern>
+**DO NOT use markdown headings in skill body content.**
+
+❌ Bad (hybrid approach):
+```markdown
+# PDF Processing
+
+## Quick start
+
+Extract text with pdfplumber...
+
+## Advanced features
+
+Form filling...
+```
+
+✅ Good (pure XML):
+```markdown
+<objective>
+PDF processing with text extraction, form filling, and merging.
+</objective>
+
+<quick_start>
+Extract text with pdfplumber...
+</quick_start>
+
+<advanced_features>
+Form filling...
+</advanced_features>
+```
+</anti_pattern>
+
+<benefits>
+<benefit type="clarity">
+Clearly separate different sections with unambiguous boundaries
+</benefit>
+
+<benefit type="accuracy">
+Reduce parsing errors. Claude knows exactly where sections begin and end.
+</benefit>
+
+<benefit type="flexibility">
+Easily find, add, remove, or modify sections without rewriting
+</benefit>
+
+<benefit type="parseability">
+Programmatically extract specific sections for validation or analysis
+</benefit>
+
+<benefit type="efficiency">
+Lower token usage compared to markdown headings
+</benefit>
+
+<benefit type="consistency">
+Standardized structure across all skills in the ecosystem
+</benefit>
+</benefits>
+
+<combining_with_other_techniques>
+XML tags work well with other prompting techniques:
+
+**Multi-shot learning**:
+```xml
+<examples>
+<example number="1">...</example>
+<example number="2">...</example>
+</examples>
+```
+
+**Chain of thought**:
+```xml
+<thinking>
+Analyze the problem...
+</thinking>
+
+<answer>
+Based on the analysis...
+</answer>
+```
+
+**Template provision**:
+```xml
+<template>
+```markdown
+# Report Title
+
+## Summary
+...
+```
+</template>
+```
+
+**Reference material**:
+```xml
+<schema>
+{
+  "field": "type"
+}
+</schema>
+```
+</combining_with_other_techniques>
+
+<tag_reference_pattern>
+When referencing content in tags, use the tag name:
+
+"Using the schema in `<schema>` tags..."
+"Follow the workflow in `<workflow>`..."
+"See examples in `<examples>`..."
+
+This makes the structure self-documenting.
+</tag_reference_pattern>

package/dist/resources/skills/create-skill/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/dist/resources/skills/create-skill/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>