@soleur/opencode 0.0.0-stage → 3.354.2

package/skills/skill-creator/references/recommended-structure.md

@@ -0,0 +1,180 @@
+# Recommended Skill Structure
+
+The optimal structure for complex skills separates routing, workflows, and knowledge.
+
+<structure>
+```
+skill-name/
+├── SKILL.md              # Router + essential principles (unavoidable)
+├── workflows/            # Step-by-step procedures (how)
+│   ├── workflow-a.md
+│   ├── workflow-b.md
+│   └── ...
+└── references/           # Domain knowledge (what)
+    ├── reference-a.md
+    ├── reference-b.md
+    └── ...
+```
+</structure>
+
+<why_this_works>
+
+## Problems This Solves
+
+**Problem 1: Context gets skipped**
+When important principles are in a separate file, Claude may not read them.
+**Solution:** Put essential principles directly in SKILL.md. They load automatically.
+
+**Problem 2: Wrong context loaded**
+A "build" task loads debugging references. A "debug" task loads build references.
+**Solution:** Intake question determines intent → routes to specific workflow → workflow specifies which references to read.
+
+**Problem 3: Monolithic skills are overwhelming**
+500+ lines of mixed content makes it hard to find relevant parts.
+**Solution:** Small router (SKILL.md) + focused workflows + reference library.
+
+**Problem 4: Procedures mixed with knowledge**
+"How to do X" mixed with "What X means" creates confusion.
+**Solution:** Workflows are procedures (steps). References are knowledge (patterns, examples).
+</why_this_works>
+
+<skill_md_template>
+
+## SKILL.md Template
+
+```markdown
+---
+name: skill-name
+description: What it does and when to use it.
+---
+
+# [Skill Name]
+
+## How This Skill Works
+
+[Inline principles that apply to ALL workflows. Cannot be skipped.]
+
+### Principle 1: [Name]
+[Brief explanation]
+
+### Principle 2: [Name]
+[Brief explanation]
+
+## Intake
+
+**Ask the user:**
+
+What would you like to do?
+1. [Option A]
+2. [Option B]
+3. [Option C]
+4. Something else
+
+**Wait for response before proceeding.**
+
+## Routing
+
+| Response | Workflow |
+|----------|----------|
+| 1, "keyword", "keyword" | `workflows/option-a.md` |
+| 2, "keyword", "keyword" | `workflows/option-b.md` |
+| 3, "keyword", "keyword" | `workflows/option-c.md` |
+| 4, other | Clarify, then select |
+
+**After reading the workflow, follow it exactly.**
+
+## References
+
+All domain knowledge in `references/`:
+
+**Category A:** file-a.md, file-b.md
+**Category B:** file-c.md, file-d.md
+
+## Workflows
+
+| Workflow | Purpose |
+|----------|---------|
+| option-a.md | [What it does] |
+| option-b.md | [What it does] |
+| option-c.md | [What it does] |
+```
+
+</skill_md_template>
+
+<workflow_template>
+
+## Workflow Template
+
+```markdown
+# Workflow: [Name]
+
+<required_reading>
+**Read these reference files NOW:**
+1. references/relevant-file.md
+2. references/another-file.md
+</required_reading>
+
+<process>
+## Step 1: [Name]
+[What to do]
+
+## Step 2: [Name]
+[What to do]
+
+## Step 3: [Name]
+[What to do]
+</process>
+
+<success_criteria>
+This workflow is complete when:
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+</success_criteria>
+```
+
+</workflow_template>
+
+<when_to_use_this_pattern>
+
+## When to Use This Pattern
+
+**Use router + workflows + references when:**
+
+- Multiple distinct workflows (build vs debug vs ship)
+- Different workflows need different references
+- Essential principles must not be skipped
+- Skill has grown beyond 200 lines
+
+**Use simple single-file skill when:**
+
+- One workflow
+- Small reference set
+- Under 200 lines total
+- No essential principles to enforce
+</when_to_use_this_pattern>
+
+<key_insight>
+
+## The Key Insight
+
+**SKILL.md is always loaded. Use this guarantee.**
+
+Put unavoidable content in SKILL.md:
+
+- Essential principles
+- Intake question
+- Routing logic
+
+Put workflow-specific content in workflows/:
+
+- Step-by-step procedures
+- Required references for that workflow
+- Success criteria for that workflow
+
+Put reusable knowledge in references/:
+
+- Patterns and examples
+- Technical details
+- Domain expertise
+</key_insight>

package/skills/skill-creator/references/skill-structure.md

@@ -0,0 +1,396 @@
+<overview>
+Skills have three structural components: YAML frontmatter (metadata), a markdown-heading body (content organization), and progressive disclosure (file organization). This reference defines requirements and best practices for each component.
+</overview>
+
+<body_structure_requirements>
+<critical_rule>
+**Markdown headings structure a skill body; XML tags are optional semantic wrappers inside a section and never replace headings.** Use `#` for the skill title, `##` for each major section, and `###` below that. Keep markdown formatting within content (bold, italic, lists, code blocks, links).
+
+Measured basis (2026-09-21, fences excluded): 101 of 102 shipped Soleur `SKILL.md` bodies use markdown headings (96 carry a `#` title), and 23 also carry XML tag lines at column 0. A body built only from top-level tags, with no headings, is the anti-pattern.
+</critical_rule>
+
+<required_sections>
+Every skill body carries these, as headings:
+
+- **`# <Skill Name>`** followed by what the skill does and why it matters (1-3 paragraphs)
+- **`## Quick start`** (or the first numbered phase) - immediate, actionable guidance
+- **A completion criterion** - a `## Success criteria` section, or an explicit exit condition closing each phase
+</required_sections>
+
+<conditional_sections>
+Add based on skill complexity and domain requirements:
+
+- **`## Context`** - Background/situational information
+- **`## Workflow`** or **`## Phase N: ...`** - Step-by-step procedures
+- **`## Advanced features`** - Deep-dive topics (progressive disclosure)
+- **`## Validation`** - How to verify outputs
+- **`## Examples`** - Multi-shot learning
+- **`## Anti-patterns`** or **`## Sharp Edges`** - Common mistakes to avoid
+- **`## Security checklist`** - Non-negotiable security patterns
+- **`## Testing`** - Testing workflows
+- **`## References`** - Links to reference files
+
+See [authoring-levers.md](authoring-levers.md) for co-location: everything about one concept (what it is, how it applies, where it breaks) lives in one section.
+</conditional_sections>
+
+<section_selection>
+**Simple skills** (single domain, straightforward):
+
+- Required sections only
+- Example: Text extraction, file format conversion
+
+**Medium skills** (multiple patterns, some complexity):
+
+- Required sections + workflow/examples as needed
+- Example: Document processing with steps, API integration
+
+**Complex skills** (multiple domains, security, APIs):
+
+- Required sections + conditional sections as appropriate
+- Example: Payment processing, authentication systems, multi-step workflows
+</section_selection>
+
+<optional_xml_wrappers>
+Inside a section, an XML tag can mark a discrete block the model must treat as one unit: an input/output example pair, a template to copy verbatim, a checklist. The heading still names the section; the tag only bounds the block:
+
+```markdown
+## Examples
+
+<example number="1">
+<input>User input</input>
+<output>Expected output</output>
+</example>
+```
+
+When you use a wrapper, close it, and nest it inside a heading rather than in place of one.
+</optional_xml_wrappers>
+
+<section_naming_conventions>
+Use descriptive heading names:
+
+- `## Workflow` not `## Steps stuff`
+- `## Success criteria` not `## Done`
+- `## Anti-patterns` not `## Don't do`
+
+Be consistent within your skill. If you use `## Workflow`, don't also use `## Process` for the same purpose (unless they serve different roles).
+</section_naming_conventions>
+</body_structure_requirements>
+
+<yaml_requirements>
+<required_fields>
+
+```yaml
+---
+name: skill-name-here
+description: What it does and when to use it (third person, specific triggers)
+---
+```
+
+</required_fields>
+
+<name_field>
+**Validation rules**:
+
+- Maximum 64 characters
+- Lowercase letters, numbers, hyphens only
+- No XML tags
+- No reserved words: "anthropic", "claude"
+- Must match directory name exactly
+
+**Examples**:
+
+- ✅ `process-pdfs`
+- ✅ `manage-facebook-ads`
+- ✅ `setup-stripe-payments`
+- ❌ `PDF_Processor` (uppercase)
+- ❌ `helper` (vague)
+- ❌ `claude-helper` (reserved word)
+</name_field>
+
+<description_field>
+**Validation rules**:
+
+- Non-empty, maximum 1024 characters
+- No XML tags
+- Third person (never first or second person)
+- Include what it does AND when to use it
+
+**Critical rule**: Always write in third person.
+
+- ✅ "Processes Excel files and generates reports"
+- ❌ "I can help you process Excel files"
+- ❌ "You can use this to process Excel files"
+
+**Structure**: Include both capabilities and triggers.
+
+**Effective examples**:
+
+```yaml
+description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
+```
+
+```yaml
+description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.
+```
+
+```yaml
+description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.
+```
+
+**Avoid**:
+
+```yaml
+description: Helps with documents
+```
+
+```yaml
+description: Processes data
+```
+
+</description_field>
+</yaml_requirements>
+
+<naming_conventions>
+Use **`<noun|domain>-<verb>` prefix-grouping** for skill names: the shared grouping token comes
+first, the action second. Shipped evidence -- `flag-create`, `flag-delete`, `flag-list`,
+`flag-set-role`; `cron-list`, `cron-delete`; `legal-audit`, `legal-generate`; `operator-digest`,
+`operator-rephrase`; `release-announce`, `release-docs`. **No shipped Soleur skill uses the
+verb-first `create-*` / `setup-*` / `manage-*` / `generate-*` form.** Why the prefix leads: a sorted
+skill list then reads as families rather than as a flat wall, so every `flag-*` skill is found in
+one place -- which is how `plugins/soleur/commands/help.md` renders the listing.
+
+The patterns below are retained as upstream illustrations of the **pattern** shape (one pattern per
+capability class), not as Soleur name templates. Read them for the grouping idea, not for the word
+order.
+
+<pattern name="create">
+Building/authoring tools
+
+Examples: `create-agent-skills`, `create-hooks`, `create-landing-pages`
+</pattern>
+
+<pattern name="manage">
+Managing external services or resources
+
+Examples: `manage-facebook-ads`, `manage-zoom`, `manage-stripe`, `manage-supabase`
+</pattern>
+
+<pattern name="setup">
+Configuration/integration tasks
+
+Examples: `setup-stripe-payments`, `setup-meta-tracking`
+</pattern>
+
+<pattern name="generate">
+Generation tasks
+
+Examples: `generate-ai-images`
+</pattern>
+
+<avoid_patterns>
+
+- Vague: `helper`, `utils`, `tools`
+- Generic: `documents`, `data`, `files`
+- Reserved words: `anthropic-helper`, `claude-tools`
+- Inconsistent: Directory `facebook-ads` but name `facebook-ads-manager`
+</avoid_patterns>
+</naming_conventions>
+
+<progressive_disclosure>
+<principle>
+SKILL.md serves as an overview that points to detailed materials as needed. This keeps context window usage efficient.
+</principle>
+
+<practical_guidance>
+
+- Keep SKILL.md body under 500 lines
+- Split content into separate files when approaching this limit
+- Keep references one level deep from SKILL.md
+- Add table of contents to reference files over 100 lines
+</practical_guidance>
+
+<pattern name="high_level_guide">
+Quick start in SKILL.md, details in reference files:
+
+````markdown
+---
+name: pdf-processing
+description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
+---
+
+# PDF Processing
+
+Extract text and tables from PDF files, fill forms, and merge documents using Python libraries.
+
+## Quick start
+
+Extract text with pdfplumber:
+
+```python
+import pdfplumber
+with pdfplumber.open("file.pdf") as pdf:
+    text = pdf.pages[0].extract_text()
+```
+
+## Advanced features
+
+**Form filling**: See [forms.md](forms.md)
+**API reference**: See [reference.md](reference.md)
+````
+
+Claude loads forms.md or reference.md only when needed.
+</pattern>
+
+<pattern name="domain_organization">
+For skills with multiple domains, organize by domain to avoid loading irrelevant context:
+
+```
+
+bigquery-skill/
+├── SKILL.md (overview and navigation)
+└── reference/
+    ├── finance.md (revenue, billing metrics)
+    ├── sales.md (opportunities, pipeline)
+    ├── product.md (API usage, features)
+    └── marketing.md (campaigns, attribution)
+
+```
+
+When user asks about revenue, Claude reads only finance.md. Other files stay on filesystem consuming zero tokens.
+</pattern>
+
+<pattern name="conditional_details">
+Show basic content in SKILL.md, link to advanced in reference files:
+
+```markdown
+# DOCX Processing
+
+Process DOCX files with creation and editing capabilities.
+
+## Quick start
+
+### Creating documents
+
+Use docx-js for new documents. See [docx-js.md](docx-js.md).
+
+### Editing documents
+
+For simple edits, modify the document XML directly.
+
+**For tracked changes**: See [redlining.md](redlining.md)
+**For OOXML details**: See [ooxml.md](ooxml.md)
+```
+
+Claude reads redlining.md or ooxml.md only when the user needs those features.
+</pattern>
+
+<critical_rules>
+**Keep references one level deep**: All reference files should link directly from SKILL.md. Avoid nested references (SKILL.md → advanced.md → details.md) as Claude may only partially read deeply nested files.
+
+**Add table of contents to long files**: For reference files over 100 lines, include a table of contents at the top.
+
+**Structure reference files with headings too**: Reference files follow the same rule as `SKILL.md`: markdown headings for structure, XML wrappers optional inside a section. (Some older skill-creator references, this one included, still carry top-level tags as content labels; do not copy that shape into new files.)
+</critical_rules>
+</progressive_disclosure>
+
+<file_organization>
+<filesystem_navigation>
+Claude navigates your skill directory using bash commands:
+
+- Use forward slashes: `reference/guide.md` (not `reference\guide.md`)
+- Name files descriptively: `form_validation_rules.md` (not `doc2.md`)
+- Organize by domain: `reference/finance.md`, `reference/sales.md`
+</filesystem_navigation>
+
+<directory_structure>
+Typical skill structure:
+
+```
+skill-name/
+├── SKILL.md (main entry point, markdown headings)
+├── references/ (optional, for progressive disclosure)
+│   ├── guide-1.md (markdown headings)
+│   ├── guide-2.md (markdown headings)
+│   └── examples.md (markdown headings)
+└── scripts/ (optional, for utility scripts)
+    ├── validate.py
+    └── process.py
+```
+
+</directory_structure>
+</file_organization>
+
+<anti_patterns>
+<pitfall name="tag_only_body">
+✅ Structure the body with markdown headings; wrap a discrete block in a tag only inside a section:
+
+```markdown
+# PDF Processing
+
+PDF processing with text extraction, form filling, and merging.
+
+## Quick start
+Extract text...
+
+## Advanced features
+Form filling...
+```
+
+❌ Anti-pattern: a tag-only body with no headings, where top-level tags stand in for sections:
+
+```markdown
+## Objective
+
+PDF processing with text extraction, form filling, and merging.
+
+## Quick Start
+
+Extract text...
+
+```
+
+</pitfall>
+
+<pitfall name="vague_descriptions">
+- ❌ "Helps with documents"
+- ✅ "Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction."
+</pitfall>
+
+<pitfall name="inconsistent_pov">
+- ❌ "I can help you process Excel files"
+- ✅ "Processes Excel files and generates reports"
+</pitfall>
+
+<pitfall name="wrong_naming_convention">
+- ❌ Directory: `facebook-ads`, Name: `facebook-ads-manager`
+- ✅ Directory: `manage-facebook-ads`, Name: `manage-facebook-ads`
+- ❌ Directory: `stripe-integration`, Name: `stripe`
+- ✅ Directory: `setup-stripe-payments`, Name: `setup-stripe-payments`
+</pitfall>
+
+<pitfall name="deeply_nested_references">
+Keep references one level deep from SKILL.md. Claude may only partially read nested files (SKILL.md → advanced.md → details.md).
+</pitfall>
+
+<pitfall name="windows_paths">
+Always use forward slashes: `scripts/helper.py` (not `scripts\helper.py`)
+</pitfall>
+
+<pitfall name="missing_required_sections">
+Every skill needs a `#` title with its purpose, a `## Quick start` (or first phase), and a completion criterion (`## Success criteria` or a per-phase exit condition).
+</pitfall>
+</anti_patterns>
+
+<validation_checklist>
+Before finalizing a skill, verify:
+
+- ✅ YAML frontmatter valid (name matches directory, description in third person)
+- ✅ Body structured with markdown headings (XML tags, if any, only wrap blocks inside a section)
+- ✅ Required sections present: title + purpose, quick start, completion criterion
+- ✅ Conditional sections appropriate for complexity level
+- ✅ Any XML wrappers closed and nested inside a heading
+- ✅ Progressive disclosure applied (SKILL.md < 500 lines)
+- ✅ Reference files structured with markdown headings
+- ✅ File paths use forward slashes
+- ✅ Descriptive file names
+</validation_checklist>

package/skills/skill-creator/references/using-scripts.md

@@ -0,0 +1,122 @@
+# 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:
+
+```markdown
+## 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
+
+```
+
+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>