gsd-pi 2.29.0-dev.77f06e2 → 2.29.0-dev.f08b4fe

package/src/resources/skills/create-skill/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: create-skill
+description: Expert guidance for creating, writing, building, and refining GSD skills. Use when working with SKILL.md files, authoring new skills, improving existing skills, or understanding skill structure and best practices.
+---
+
+<essential_principles>
+## How Skills Work
+
+Skills are modular, filesystem-based capabilities that provide domain expertise on demand. This skill teaches how to create effective skills.
+
+### 1. Skills Are Prompts
+
+All prompting best practices apply. Be clear, be direct, use XML structure. Assume Claude is smart - only add context Claude doesn't have.
+
+### 2. SKILL.md Is Always Loaded
+
+When a skill is invoked, Claude reads SKILL.md. Use this guarantee:
+- Essential principles go in SKILL.md (can't be skipped)
+- Workflow-specific content goes in workflows/
+- Reusable knowledge goes in references/
+
+### 3. Router Pattern for Complex Skills
+
+```
+skill-name/
+├── SKILL.md              # Router + principles
+├── workflows/            # Step-by-step procedures (FOLLOW)
+├── references/           # Domain knowledge (READ)
+├── templates/            # Output structures (COPY + FILL)
+└── scripts/              # Reusable code (EXECUTE)
+```
+
+SKILL.md asks "what do you want to do?" → routes to workflow → workflow specifies which references to read.
+
+**When to use each folder:**
+- **workflows/** - Multi-step procedures Claude follows
+- **references/** - Domain knowledge Claude reads for context
+- **templates/** - Consistent output structures Claude copies and fills (plans, specs, configs)
+- **scripts/** - Executable code Claude runs as-is (deploy, setup, API calls)
+
+### 4. Pure XML Structure
+
+No markdown headings (#, ##, ###) in skill body. Use semantic XML tags:
+```xml
+<objective>...</objective>
+<process>...</process>
+<success_criteria>...</success_criteria>
+```
+
+Keep markdown formatting within content (bold, lists, code blocks).
+
+### 5. Progressive Disclosure
+
+SKILL.md under 500 lines. Split detailed content into reference files. Load only what's needed for the current workflow.
+</essential_principles>
+
+<routing>
+## Understanding User Intent
+
+Based on the user's message, route directly to the appropriate workflow:
+
+**Creating new skills:**
+- Domain expertise (exhaustive knowledge base) → **Use `create-domain-expertise` skill instead** (separate skill with batched subagent orchestration)
+- Task-execution skill (does specific things) → workflows/create-new-skill.md
+
+**Working with existing skills:**
+- Audit, review, check → workflows/audit-skill.md
+- Verify content is current → workflows/verify-skill.md
+- Add workflow → workflows/add-workflow.md
+- Add reference → workflows/add-reference.md
+- Add template → workflows/add-template.md
+- Add script → workflows/add-script.md
+- Upgrade to router pattern → workflows/upgrade-to-router.md
+
+**Need help deciding:**
+- General guidance → workflows/get-guidance.md
+
+**If user intent is unclear, ask minimal clarifying questions:**
+- "Create a MIDI skill" → "Task-execution skill (does MIDI tasks) or domain expertise (complete MIDI knowledge base)?"
+- "Work on my skill" → "Which skill? What do you want to do with it?"
+
+Then proceed directly to the workflow.
+</routing>
+
+<quick_reference>
+## Skill Structure Quick Reference
+
+**Skill directories:**
+- Global: `~/.gsd/agent/skills/{skill-name}/`
+- Project-local: `.pi/agent/skills/{skill-name}/`
+
+**Simple skill (single file):**
+```yaml
+---
+name: skill-name
+description: What it does and when to use it.
+---
+
+<objective>What this skill does</objective>
+<quick_start>Immediate actionable guidance</quick_start>
+<process>Step-by-step procedure</process>
+<success_criteria>How to know it worked</success_criteria>
+```
+
+**Complex skill (router pattern):**
+```
+SKILL.md:
+  <essential_principles> - Always applies
+  <intake> - Question to ask
+  <routing> - Maps answers to workflows
+
+workflows/:
+  <required_reading> - Which refs to load
+  <process> - Steps
+  <success_criteria> - Done when...
+
+references/:
+  Domain knowledge, patterns, examples
+
+templates/:
+  Output structures Claude copies and fills
+  (plans, specs, configs, documents)
+
+scripts/:
+  Executable code Claude runs as-is
+  (deploy, setup, API calls, data processing)
+```
+</quick_reference>
+
+<reference_index>
+## Domain Knowledge
+
+All in `references/`:
+
+**Structure:** recommended-structure.md, skill-structure.md
+**Principles:** core-principles.md, be-clear-and-direct.md, use-xml-tags.md
+**Patterns:** common-patterns.md, workflows-and-validation.md
+**Assets:** using-templates.md, using-scripts.md
+**Advanced:** executable-code.md, api-security.md, iteration-and-testing.md
+**GSD-specific:** gsd-skill-ecosystem.md
+</reference_index>
+
+<workflows_index>
+## Workflows
+
+All in `workflows/`:
+
+| Workflow | Purpose |
+|----------|---------|
+| create-new-skill.md | Build a task-execution skill from scratch |
+| audit-skill.md | Analyze skill against best practices |
+| verify-skill.md | Check if content is still accurate |
+| add-workflow.md | Add a workflow to existing skill |
+| add-reference.md | Add a reference to existing skill |
+| add-template.md | Add a template to existing skill |
+| add-script.md | Add a script to existing skill |
+| upgrade-to-router.md | Convert simple skill to router pattern |
+| get-guidance.md | Help decide what kind of skill to build |
+</workflows_index>
+
+<yaml_requirements>
+## YAML Frontmatter
+
+Required fields:
+```yaml
+---
+name: skill-name          # lowercase-with-hyphens, matches directory
+description: ...          # What it does AND when to use it (third person)
+---
+```
+
+Name conventions: `create-*`, `manage-*`, `setup-*`, `generate-*`, `build-*`
+</yaml_requirements>
+
+<success_criteria>
+A well-structured skill:
+- Has valid YAML frontmatter
+- Uses pure XML structure (no markdown headings in body)
+- Has essential principles inline in SKILL.md
+- Routes directly to appropriate workflows based on user intent
+- Keeps SKILL.md under 500 lines
+- Asks minimal clarifying questions only when truly needed
+- Has been tested with real usage
+</success_criteria>

package/src/resources/skills/create-skill/references/api-security.md

@@ -0,0 +1,226 @@
+<overview>
+When building skills that make API calls requiring credentials (API keys, tokens, secrets), follow this protocol to prevent credentials from appearing in chat.
+</overview>
+
+<the_problem>
+Raw curl commands with environment variables expose credentials:
+
+```bash
+# ❌ BAD - API key visible in chat
+curl -H "Authorization: Bearer $API_KEY" https://api.example.com/data
+```
+
+When Claude executes this, the full command with expanded `$API_KEY` appears in the conversation.
+</the_problem>
+
+<the_solution>
+Use `~/.claude/scripts/secure-api.sh` - a wrapper that loads credentials internally.
+
+<for_supported_services>
+```bash
+# ✅ GOOD - No credentials visible
+~/.claude/scripts/secure-api.sh <service> <operation> [args]
+
+# Examples:
+~/.claude/scripts/secure-api.sh facebook list-campaigns
+~/.claude/scripts/secure-api.sh ghl search-contact "email@example.com"
+```
+</for_supported_services>
+
+<adding_new_services>
+When building a new skill that requires API calls:
+
+1. **Add operations to the wrapper** (`~/.claude/scripts/secure-api.sh`):
+
+```bash
+case "$SERVICE" in
+    yourservice)
+        case "$OPERATION" in
+            list-items)
+                curl -s -G \
+                    -H "Authorization: Bearer $YOUR_API_KEY" \
+                    "https://api.yourservice.com/items"
+                ;;
+            get-item)
+                ITEM_ID=$1
+                curl -s -G \
+                    -H "Authorization: Bearer $YOUR_API_KEY" \
+                    "https://api.yourservice.com/items/$ITEM_ID"
+                ;;
+            *)
+                echo "Unknown operation: $OPERATION" >&2
+                exit 1
+                ;;
+        esac
+        ;;
+esac
+```
+
+2. **Add profile support to the wrapper** (if service needs multiple accounts):
+
+```bash
+# In secure-api.sh, add to profile remapping section:
+yourservice)
+    SERVICE_UPPER="YOURSERVICE"
+    YOURSERVICE_API_KEY=$(eval echo \$${SERVICE_UPPER}_${PROFILE_UPPER}_API_KEY)
+    YOURSERVICE_ACCOUNT_ID=$(eval echo \$${SERVICE_UPPER}_${PROFILE_UPPER}_ACCOUNT_ID)
+    ;;
+```
+
+3. **Add credential placeholders to `~/.claude/.env`** using profile naming:
+
+```bash
+# Check if entries already exist
+grep -q "YOURSERVICE_MAIN_API_KEY=" ~/.claude/.env 2>/dev/null || \
+  echo -e "\n# Your Service - Main profile\nYOURSERVICE_MAIN_API_KEY=\nYOURSERVICE_MAIN_ACCOUNT_ID=" >> ~/.claude/.env
+
+echo "Added credential placeholders to ~/.claude/.env - user needs to fill them in"
+```
+
+4. **Document profile workflow in your SKILL.md**:
+
+```markdown
+## Profile Selection Workflow
+
+**CRITICAL:** Always use profile selection to prevent using wrong account credentials.
+
+### When user requests YourService operation:
+
+1. **Check for saved profile:**
+   ```bash
+   ~/.claude/scripts/profile-state get yourservice
+   ```
+
+2. **If no profile saved, discover available profiles:**
+   ```bash
+   ~/.claude/scripts/list-profiles yourservice
+   ```
+
+3. **If only ONE profile:** Use it automatically and announce:
+   ```
+   "Using YourService profile 'main' to list items..."
+   ```
+
+4. **If MULTIPLE profiles:** Ask user which one:
+   ```
+   "Which YourService profile: main, clienta, or clientb?"
+   ```
+
+5. **Save user's selection:**
+   ```bash
+   ~/.claude/scripts/profile-state set yourservice <selected_profile>
+   ```
+
+6. **Always announce which profile before calling API:**
+   ```
+   "Using YourService profile 'main' to list items..."
+   ```
+
+7. **Make API call with profile:**
+   ```bash
+   ~/.claude/scripts/secure-api.sh yourservice:<profile> list-items
+   ```
+
+## Secure API Calls
+
+All API calls use profile syntax:
+
+```bash
+~/.claude/scripts/secure-api.sh yourservice:<profile> <operation> [args]
+
+# Examples:
+~/.claude/scripts/secure-api.sh yourservice:main list-items
+~/.claude/scripts/secure-api.sh yourservice:main get-item <ITEM_ID>
+```
+
+**Profile persists for session:** Once selected, use same profile for subsequent operations unless user explicitly changes it.
+```
+</adding_new_services>
+</the_solution>
+
+<pattern_guidelines>
+<simple_get_requests>
+```bash
+curl -s -G \
+    -H "Authorization: Bearer $API_KEY" \
+    "https://api.example.com/endpoint"
+```
+</simple_get_requests>
+
+<post_with_json_body>
+```bash
+ITEM_ID=$1
+curl -s -X POST \
+    -H "Authorization: Bearer $API_KEY" \
+    -H "Content-Type: application/json" \
+    -d @- \
+    "https://api.example.com/items/$ITEM_ID"
+```
+
+Usage:
+```bash
+echo '{"name":"value"}' | ~/.claude/scripts/secure-api.sh service create-item
+```
+</post_with_json_body>
+
+<post_with_form_data>
+```bash
+curl -s -X POST \
+    -F "field1=value1" \
+    -F "field2=value2" \
+    -F "access_token=$API_TOKEN" \
+    "https://api.example.com/endpoint"
+```
+</post_with_form_data>
+</pattern_guidelines>
+
+<credential_storage>
+**Location:** `~/.claude/.env` (global for all skills, accessible from any directory)
+
+**Format:**
+```bash
+# Service credentials
+SERVICE_API_KEY=your-key-here
+SERVICE_ACCOUNT_ID=account-id-here
+
+# Another service
+OTHER_API_TOKEN=token-here
+OTHER_BASE_URL=https://api.other.com
+```
+
+**Loading in script:**
+```bash
+set -a
+source ~/.claude/.env 2>/dev/null || { echo "Error: ~/.claude/.env not found" >&2; exit 1; }
+set +a
+```
+</credential_storage>
+
+<best_practices>
+1. **Never use raw curl with `$VARIABLE` in skill examples** - always use the wrapper
+2. **Add all operations to the wrapper** - don't make users figure out curl syntax
+3. **Auto-create credential placeholders** - add empty fields to `~/.claude/.env` immediately when creating the skill
+4. **Keep credentials in `~/.claude/.env`** - one central location, works everywhere
+5. **Document each operation** - show examples in SKILL.md
+6. **Handle errors gracefully** - check for missing env vars, show helpful error messages
+</best_practices>
+
+<testing>
+Test the wrapper without exposing credentials:
+
+```bash
+# This command appears in chat
+~/.claude/scripts/secure-api.sh facebook list-campaigns
+
+# But API keys never appear - they're loaded inside the script
+```
+
+Verify credentials are loaded:
+```bash
+# Check .env exists
+ls -la ~/.claude/.env
+
+# Check specific variables (without showing values)
+grep -q "YOUR_API_KEY=" ~/.claude/.env && echo "API key configured" || echo "API key missing"
+```
+</testing>