@soleur/opencode 0.0.0-stage → 3.354.2

package/skills/skill-creator/workflows/create-new-skill.md

@@ -0,0 +1,207 @@
+# 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/authoring-levers.md
+</required_reading>
+
+<process>
+## Step 1: 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 2: 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-2026 sources
+- Store findings for use in content generation
+
+## Step 3: 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 4: Create Directory
+
+```bash
+mkdir -p ~/.claude/skills/{skill-name}
+# If complex:
+mkdir -p ~/.claude/skills/{skill-name}/workflows
+mkdir -p ~/.claude/skills/{skill-name}/references
+# If needed:
+mkdir -p ~/.claude/skills/{skill-name}/templates  # for output structures
+mkdir -p ~/.claude/skills/{skill-name}/scripts    # for reusable code
+```
+
+## Step 5: Write SKILL.md
+
+**Simple skill:** Write complete skill file with:
+
+- YAML frontmatter (name, description; add `disable-model-invocation: true` only if the invocation test in `references/authoring-levers.md` says human-only)
+- `# <Skill Name>` title with what the skill does
+- `## Quick start`
+- Content sections as markdown headings (XML tags only as optional wrappers inside a section)
+- `## Success criteria`
+
+**Complex skill:** Write router with:
+
+- YAML frontmatter
+- `## Essential principles` (inline, unavoidable)
+- `## Intake` (question to ask user)
+- `## Routing` (maps answers to workflows)
+- `## References` and `## Workflows` indexes
+
+## Step 6: Write Workflows (if complex)
+
+For each workflow:
+
+```markdown
+# Workflow: {Workflow Name}
+
+## Required reading
+Which references to load for this workflow
+
+## Process
+Step-by-step procedure
+
+## Success criteria
+How to know this workflow is done
+```
+
+## Step 7: Write References (if needed)
+
+Domain knowledge that:
+
+- Multiple workflows might need
+- Doesn't change based on workflow
+- Contains patterns, examples, technical details
+
+## Step 8: Validate Structure
+
+Check:
+
+- [ ] YAML frontmatter valid
+- [ ] Name matches directory (lowercase-with-hyphens)
+- [ ] Description says what it does AND when to use it (third person)
+- [ ] Body structured with markdown headings (XML tags only as optional wrappers inside a section)
+- [ ] Required sections present: title + purpose, quick start, success criteria
+- [ ] All referenced files exist
+- [ ] SKILL.md under 500 lines
+- [ ] Any XML wrappers closed
+
+## Step 9: Create Slash Command
+
+```bash
+cat > ~/.claude/commands/{skill-name}.md << 'EOF'
+---
+description: {Brief description}
+argument-hint: [{argument hint}]
+allowed-tools: Skill({skill-name})
+---
+
+Invoke the {skill-name} skill for: $ARGUMENTS
+EOF
+```
+
+## Step 10: 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:
+
+- [ ] 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
+- [ ] Slash command exists and works
+- [ ] Tested with real invocation
+</success_criteria>

package/skills/skill-creator/workflows/get-guidance.md

@@ -0,0 +1,134 @@
+# Workflow: Get Guidance on Skill Design
+
+<required_reading>
+**Read these reference files NOW:**
+
+1. references/core-principles.md
+2. references/recommended-structure.md
+</required_reading>
+
+<process>
+## Step 1: Understand the Problem Space
+
+Ask the user:
+
+- What task or domain are you trying to support?
+- Is this something you do repeatedly?
+- What makes it complex enough to need a skill?
+
+## Step 2: Determine If a Skill Is Right
+
+**Create a skill when:**
+
+- Task is repeated across multiple sessions
+- Domain knowledge doesn't change frequently
+- Complex enough to benefit from structure
+- Would save significant time if automated
+
+**Don't create a skill when:**
+
+- One-off task (just do it directly)
+- Changes constantly (will be outdated quickly)
+- Too simple (overhead isn't worth it)
+- Better as a slash command (user-triggered, no context needed)
+
+Share this assessment with user.
+
+## Step 3: Map the Workflows
+
+Ask: "What are the different things someone might want to do with this skill?"
+
+Common patterns:
+
+- Create / Read / Update / Delete
+- Build / Debug / Ship
+- Setup / Use / Troubleshoot
+- Import / Process / Export
+
+Each distinct workflow = potential workflow file.
+
+## Step 4: Identify Domain Knowledge
+
+Ask: "What knowledge is needed regardless of which workflow?"
+
+This becomes references:
+
+- API patterns
+- Best practices
+- Common examples
+- Configuration details
+
+## Step 5: Draft the Structure
+
+Based on answers, recommend structure:
+
+**If 1 workflow, simple knowledge:**
+
+```
+skill-name/
+└── SKILL.md (everything in one file)
+```
+
+**If 2+ workflows, shared knowledge:**
+
+```
+skill-name/
+├── SKILL.md (router)
+├── workflows/
+│   ├── workflow-a.md
+│   └── workflow-b.md
+└── references/
+    └── shared-knowledge.md
+```
+
+## Step 6: Identify Essential Principles
+
+Ask: "What rules should ALWAYS apply, no matter which workflow?"
+
+These become the essential-principles section (a `##` heading) in SKILL.md.
+
+Examples:
+
+- "Always verify before reporting success"
+- "Never store credentials in code"
+- "Ask before making destructive changes"
+
+## Step 7: Present Recommendation
+
+Summarize:
+
+- Recommended structure (simple vs router pattern)
+- List of workflows
+- List of references
+- Essential principles
+
+Ask: "Does this structure make sense? Ready to build it?"
+
+If yes → offer to switch to "Create a new skill" workflow
+If no → clarify and iterate
+</process>
+
+<decision_framework>
+
+## Quick Decision Framework
+
+| Situation | Recommendation |
+|-----------|----------------|
+| Single task, repeat often | Simple skill |
+| Multiple related tasks | Router + workflows |
+| Complex domain, many patterns | Router + workflows + references |
+| User-triggered, fresh context | Slash command, not skill |
+| One-off task | No skill needed |
+
+</decision_framework>
+
+<success_criteria>
+Guidance is complete when:
+
+- [ ] User understands if they need a skill
+- [ ] Structure is recommended and explained
+- [ ] Workflows are identified
+- [ ] References are identified
+- [ ] Essential principles are identified
+- [ ] User is ready to build (or decided not to)
+</success_criteria>

package/skills/skill-creator/workflows/upgrade-to-router.md

@@ -0,0 +1,170 @@
+# Workflow: Upgrade Skill to Router Pattern
+
+<required_reading>
+**Read these reference files NOW:**
+
+1. references/recommended-structure.md
+2. references/skill-structure.md
+</required_reading>
+
+<process>
+## Step 1: Select the Skill
+
+```bash
+ls ~/.claude/skills/
+```
+
+Present numbered list, ask: "Which skill should be upgraded to the router pattern?"
+
+## Step 2: Verify It Needs Upgrading
+
+Read the skill:
+
+```bash
+cat ~/.claude/skills/{skill-name}/SKILL.md
+ls ~/.claude/skills/{skill-name}/
+```
+
+**Already a router?** (has workflows/ and intake question)
+→ Tell user it's already using router pattern, offer to add workflows instead
+
+**Simple skill that should stay simple?** (under 200 lines, single workflow)
+→ Explain that router pattern may be overkill, ask if they want to proceed anyway
+
+**Good candidate for upgrade:**
+
+- Over 200 lines
+- Multiple distinct use cases
+- Essential principles that shouldn't be skipped
+- Growing complexity
+
+## Step 3: Identify Components
+
+Analyze the current skill and identify:
+
+1. **Essential principles** - Rules that apply to ALL use cases
+2. **Distinct workflows** - Different things a user might want to do
+3. **Reusable knowledge** - Patterns, examples, technical details
+
+Present findings:
+
+```
+## Analysis
+
+**Essential principles I found:**
+- [Principle 1]
+- [Principle 2]
+
+**Distinct workflows I identified:**
+- [Workflow A]: [description]
+- [Workflow B]: [description]
+
+**Knowledge that could be references:**
+- [Reference topic 1]
+- [Reference topic 2]
+```
+
+Ask: "Does this breakdown look right? Any adjustments?"
+
+## Step 4: Create Directory Structure
+
+```bash
+mkdir -p ~/.claude/skills/{skill-name}/workflows
+mkdir -p ~/.claude/skills/{skill-name}/references
+```
+
+## Step 5: Extract Workflows
+
+For each identified workflow:
+
+1. Create `workflows/{workflow-name}.md`
+2. Add required_reading section (references it needs)
+3. Add process section (steps from original skill)
+4. Add success_criteria section
+
+## Step 6: Extract References
+
+For each identified reference topic:
+
+1. Create `references/{reference-name}.md`
+2. Move relevant content from original skill
+3. Structure with markdown headings; XML wrappers optional, inside a section
+
+## Step 7: Rewrite SKILL.md as Router
+
+Replace SKILL.md with router structure:
+
+```markdown
+---
+name: {skill-name}
+description: {existing description}
+---
+
+# {Skill Name}
+
+## Essential principles
+
+[Extracted principles - inline, cannot be skipped]
+
+## Intake
+
+**Ask the user:**
+
+What would you like to do?
+1. [Workflow A option]
+2. [Workflow B option]
+...
+
+**Wait for response before proceeding.**
+
+## Routing
+
+| Response | Workflow |
+|----------|----------|
+| 1, "keywords" | `workflows/workflow-a.md` |
+| 2, "keywords" | `workflows/workflow-b.md` |
+
+## References
+
+[List all references by category]
+
+## Workflows
+
+| Workflow | Purpose |
+|----------|---------|
+| workflow-a.md | [What it does] |
+| workflow-b.md | [What it does] |
+```
+
+## Step 8: Verify Nothing Was Lost
+
+Compare original skill content against new structure:
+
+- [ ] All principles preserved (now inline)
+- [ ] All procedures preserved (now in workflows)
+- [ ] All knowledge preserved (now in references)
+- [ ] No orphaned content
+
+## Step 9: Test
+
+Invoke the upgraded skill:
+
+- Does intake question appear?
+- Does each routing option work?
+- Do workflows load correct references?
+- Does behavior match original skill?
+
+Report any issues.
+</process>
+
+<success_criteria>
+Upgrade is complete when:
+
+- [ ] workflows/ directory created with workflow files
+- [ ] references/ directory created (if needed)
+- [ ] SKILL.md rewritten as router
+- [ ] Essential principles inline in SKILL.md
+- [ ] All original content preserved
+- [ ] Intake question routes correctly
+- [ ] Tested and working
+</success_criteria>