@soleur/opencode 0.0.0-stage → 3.354.2

package/skills/skill-creator/workflows/add-script.md

@@ -0,0 +1,104 @@
+# 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:
+
+```markdown
+## Process
+
+...
+N. Run `scripts/{script-name}.sh [arguments]`
+N+1. Verify operation succeeded
+...
+
+```
+
+## 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/skills/skill-creator/workflows/add-template.md

@@ -0,0 +1,83 @@
+# 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:
+
+```markdown
+## Process
+
+...
+N. Read `templates/{template-name}.md`
+N+1. Copy template structure
+N+2. Fill each placeholder based on gathered context
+...
+
+```
+
+## 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/skills/skill-creator/workflows/add-workflow.md

@@ -0,0 +1,128 @@
+# 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/skills/skill-creator/workflows/audit-skill.md

@@ -0,0 +1,159 @@
+# Workflow: Audit a Skill
+
+<required_reading>
+**Read these reference files NOW:**
+
+1. references/recommended-structure.md
+2. references/skill-structure.md
+3. references/authoring-levers.md
+</required_reading>
+
+<process>
+## Step 1: List Available Skills
+
+**DO NOT use AskUserQuestion** - there may be many skills.
+
+Enumerate skills in chat as numbered list:
+
+```bash
+ls ~/.claude/skills/
+```
+
+Present as:
+
+```
+Available skills:
+1. create-agent-skills
+2. build-macos-apps
+3. manage-stripe
+...
+```
+
+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 ~/.claude/skills/{skill-name}/SKILL.md
+
+# Check for workflows and references
+ls ~/.claude/skills/{skill-name}/
+ls ~/.claude/skills/{skill-name}/workflows/ 2>/dev/null
+ls ~/.claude/skills/{skill-name}/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
+- [ ] Body structured with markdown headings: markdown headings structure a skill body; XML tags are optional semantic wrappers inside a section and never replace headings
+- [ ] Any XML wrappers are closed and sit inside a section
+- [ ] Has a `#` title with purpose (or an essential-principles section for a router)
+- [ ] Has a completion criterion (`## Success criteria` or per-phase exit conditions)
+
+### Invocation
+
+Apply the decision test in `references/authoring-levers.md` (could the model usefully reach for this on its own, or must another skill reach it?). Either of these is a finding:
+
+- [ ] A human-only skill (fails the test, and meets ADR-236's K1-K3) lacks `disable-model-invocation: true` in its frontmatter
+- [ ] A skill that sets `disable-model-invocation: true` is named by another file as something the model should invoke. `plugins/soleur/test/invocation-axis.test.ts` enforces this; run it.
+
+### 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"
+**Tag-only body**: Top-level XML tags standing in for sections, with no markdown headings
+**Invocation mismatch**: Human-only skill left model-invocable, or a user-invoked skill that another file tells the model to invoke
+**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>