@soleur/opencode 0.0.0-stage → 1.0.0

package/skills/skill-creator/references/core-principles.md

@@ -0,0 +1,193 @@
+# Core Principles for Skill Authoring
+
+Core principles guide skill authoring decisions. These principles ensure skills are efficient, effective, and maintainable across different models and use cases.
+
+## Standard Markdown Format
+
+Skills use YAML frontmatter and standard markdown headings. Use `#`, `##`, `###` for structure. Keep markdown formatting for content (bold, italic, lists, code blocks, links).
+
+Every skill should have:
+
+- A clear heading describing what the skill does
+- A quick start section with immediate, actionable guidance
+- Success criteria defining how to know it worked
+
+## Conciseness
+
+The context window is shared. A skill shares it with the system prompt, conversation history, other skills' metadata, and the actual request.
+
+Only add context Claude doesn't already have. Challenge each piece of information:
+
+- "Does Claude really need this explanation?"
+- "Can I assume Claude knows this?"
+- "Does this paragraph justify its token cost?"
+
+Assume Claude is smart. Don't explain obvious concepts.
+
+### Concise vs Verbose Example
+
+**Concise** (~50 tokens):
+
+```markdown
+## Quick Start
+Extract PDF text with pdfplumber:
+
+```python
+import pdfplumber
+
+with pdfplumber.open("file.pdf") as pdf:
+    text = pdf.pages[0].extract_text()
+```
+
+```
+
+**Verbose** (~150 tokens):
+```markdown
+## Quick Start
+PDF files are a common file format used for documents. To extract text from them, we'll use a Python library called pdfplumber. First, you'll need to import the library, then open the PDF file using the open method, and finally extract the text from each page. Here's how to do it:
+
+```python
+import pdfplumber
+
+with pdfplumber.open("file.pdf") as pdf:
+    text = pdf.pages[0].extract_text()
+```
+
+This code opens the PDF and extracts text from the first page.
+
+```
+
+The concise version assumes Claude knows what PDFs are, understands Python imports, and can read code. All those assumptions are correct.
+
+### When to Elaborate
+
+Add explanation when:
+- Concept is domain-specific (not general programming knowledge)
+- Pattern is non-obvious or counterintuitive
+- Context affects behavior in subtle ways
+- Trade-offs require judgment
+
+Don't add explanation for:
+- Common programming concepts (loops, functions, imports)
+- Standard library usage (reading files, making HTTP requests)
+- Well-known tools (git, npm, pip)
+- Obvious next steps
+
+## Degrees of Freedom
+
+Match the level of specificity to the task's fragility and variability. Give Claude more freedom for creative tasks, less freedom for fragile operations.
+
+### High Freedom
+
+**When to use:** Multiple approaches are valid, decisions depend on context, heuristics guide the approach, creative solutions welcome.
+
+Example: A code review skill gives principles and criteria but lets Claude adapt the review based on what the code needs.
+
+### Medium Freedom
+
+**When to use:** A preferred pattern exists, some variation is acceptable, configuration affects behavior, templates can be adapted.
+
+Example: A report generation skill provides a template and lets Claude customize based on requirements.
+
+### Low Freedom
+
+**When to use:** Operations are fragile and error-prone, consistency is critical, a specific sequence must be followed, deviation causes failures.
+
+Example: A database migration skill specifies an exact command with no variation allowed.
+
+### Matching Specificity
+
+The key is matching specificity to fragility:
+
+- **Fragile operations** (database migrations, payment processing, security): Low freedom, exact instructions
+- **Standard operations** (API calls, file processing, data transformation): Medium freedom, preferred pattern with flexibility
+- **Creative operations** (code review, content generation, analysis): High freedom, heuristics and principles
+
+Mismatched specificity causes problems:
+- Too much freedom on fragile tasks -> errors and failures
+- Too little freedom on creative tasks -> rigid, suboptimal outputs
+
+## Model Testing
+
+Skills act as additions to models, so effectiveness depends on the underlying model. What works for Opus might need more detail for Haiku.
+
+### Testing Across Models
+
+Test skills with all models planned for use:
+
+**Claude Haiku** (fast, economical) benefits from:
+- More explicit instructions
+- Complete examples (no partial code)
+- Clear success criteria
+- Step-by-step workflows
+
+**Claude Sonnet** (balanced) benefits from:
+- Balanced detail level
+- Clear structure for navigation
+- Progressive disclosure
+- Concise but complete guidance
+
+**Claude Opus** (powerful reasoning) benefits from:
+- Concise instructions
+- Principles over procedures
+- High degrees of freedom
+- Trust in reasoning capabilities
+
+### Balancing Across Models
+
+Aim for instructions that work well across all target models. A good balance provides a complete working example (for Haiku), clear defaults with escape hatches (for Sonnet), and enough context without over-explanation (for Opus).
+
+### Iterative Improvement
+
+1. Start with medium detail level
+2. Test with target models
+3. Observe where models struggle or succeed
+4. Adjust based on actual performance
+5. Re-test and iterate
+
+Don't optimize for one model. Find the balance that works across target models.
+
+## Progressive Disclosure
+
+SKILL.md serves as an overview. Reference files contain details. Claude loads reference files only when needed.
+
+Progressive disclosure keeps token usage proportional to task complexity:
+
+- Simple task: Load SKILL.md only (~500 tokens)
+- Medium task: Load SKILL.md + one reference (~1000 tokens)
+- Complex task: Load SKILL.md + multiple references (~2000 tokens)
+
+Without progressive disclosure, every task loads all content regardless of need.
+
+### Implementation
+
+- Keep SKILL.md under 500 lines
+- Split detailed content into reference files
+- Keep references one level deep from SKILL.md
+- Link to references from relevant sections
+- Use descriptive reference file names
+
+See [skill-structure.md](./skill-structure.md) for progressive disclosure patterns.
+
+## Validation
+
+Validation scripts are force multipliers. They catch errors that Claude might miss and provide actionable feedback.
+
+Good validation scripts:
+- Provide verbose, specific error messages
+- Show available valid options when something is invalid
+- Pinpoint exact location of problems
+- Suggest actionable fixes
+- Are deterministic and reliable
+
+See [workflows-and-validation.md](./workflows-and-validation.md) for validation patterns.
+
+## Summary
+
+- **Standard Markdown**: Use markdown headings for structure; XML tags are optional wrappers inside a section
+- **Authoring levers**: Leading words, the two loads (and the invocation choice), co-location, and criterion demand are in [authoring-levers.md](authoring-levers.md)
+- **Conciseness**: Only add context Claude doesn't have. Assume Claude is smart
+- **Degrees of Freedom**: Match specificity to fragility
+- **Model Testing**: Test with all target models. Balance detail level
+- **Progressive Disclosure**: Keep SKILL.md concise. Split details into reference files
+- **Validation**: Make validation scripts verbose and specific

package/skills/skill-creator/references/executable-code.md

@@ -0,0 +1,188 @@
+<when_to_use_scripts>
+Even if Claude could write a script, pre-made scripts offer advantages:
+
+- More reliable than generated code
+- Save tokens (no need to include code in context)
+- Save time (no code generation required)
+- Ensure consistency across uses
+
+<execution_vs_reference>
+Make clear whether Claude should:
+
+- **Execute the script** (most common): "Run `analyze_form.py` to extract fields"
+- **Read it as reference** (for complex logic): "See `analyze_form.py` for the extraction algorithm"
+
+For most utility scripts, execution is preferred.
+</execution_vs_reference>
+
+<how_scripts_work>
+When Claude executes a script via bash:
+
+1. Script code never enters context window
+2. Only script output consumes tokens
+3. Far more efficient than having Claude generate equivalent code
+</how_scripts_work>
+</when_to_use_scripts>
+
+<file_organization>
+<scripts_directory>
+**Best practice**: Place all executable scripts in a `scripts/` subdirectory within the skill folder.
+
+```
+skill-name/
+├── SKILL.md
+├── scripts/
+│   ├── main_utility.py
+│   ├── helper_script.py
+│   └── validator.py
+└── references/
+    └── api-docs.md
+```
+
+**Benefits**:
+
+- Keeps skill root clean and organized
+- Clear separation between documentation and executable code
+- Consistent pattern across all skills
+- Easy to reference: `python scripts/script_name.py`
+
+**Reference pattern**: In SKILL.md, reference scripts using the `scripts/` path:
+
+```bash
+python ~/.claude/skills/skill-name/scripts/analyze.py input.har
+```
+
+</scripts_directory>
+</file_organization>
+
+<utility_scripts_pattern>
+<example>
+
+## Utility scripts
+
+**analyze_form.py**: Extract all form fields from PDF
+
+```bash
+python scripts/analyze_form.py input.pdf > fields.json
+```
+
+Output format:
+
+```json
+{
+  "field_name": { "type": "text", "x": 100, "y": 200 },
+  "signature": { "type": "sig", "x": 150, "y": 500 }
+}
+```
+
+**validate_boxes.py**: Check for overlapping bounding boxes
+
+```bash
+python scripts/validate_boxes.py fields.json
+# Returns: "OK" or lists conflicts
+```
+
+**fill_form.py**: Apply field values to PDF
+
+```bash
+python scripts/fill_form.py input.pdf fields.json output.pdf
+```
+
+</example>
+</utility_scripts_pattern>
+
+<solve_dont_punt>
+Handle error conditions rather than punting to Claude.
+
+<example type="good">
+```python
+def process_file(path):
+    """Process a file, creating it if it doesn't exist."""
+    try:
+        with open(path) as f:
+            return f.read()
+    except FileNotFoundError:
+        print(f"File {path} not found, creating default")
+        with open(path, 'w') as f:
+            f.write('')
+        return ''
+    except PermissionError:
+        print(f"Cannot access {path}, using default")
+        return ''
+```
+</example>
+
+<example type="bad">
+```python
+def process_file(path):
+    # Just fail and let Claude figure it out
+    return open(path).read()
+```
+</example>
+
+<configuration_values>
+Document configuration parameters to avoid "voodoo constants":
+
+<example type="good">
+```python
+# HTTP requests typically complete within 30 seconds
+REQUEST_TIMEOUT = 30
+
+# Three retries balances reliability vs speed
+
+MAX_RETRIES = 3
+
+```
+</example>
+
+<example type="bad">
+```python
+TIMEOUT = 47  # Why 47?
+RETRIES = 5   # Why 5?
+```
+
+</example>
+</configuration_values>
+</solve_dont_punt>
+
+<package_dependencies>
+<runtime_constraints>
+Skills run in code execution environment with platform-specific limitations:
+
+- **claude.ai**: Can install packages from npm and PyPI
+- **Anthropic API**: No network access and no runtime package installation
+</runtime_constraints>
+
+<guidance>
+List required packages in your SKILL.md and verify they're available.
+
+<example type="good">
+Install required package: `pip install pypdf`
+
+Then use it:
+
+```python
+from pypdf import PdfReader
+reader = PdfReader("file.pdf")
+```
+
+</example>
+
+<example type="bad">
+"Use the pdf library to process the file."
+</example>
+</guidance>
+</package_dependencies>
+
+<mcp_tool_references>
+If your Skill uses MCP (Model Context Protocol) tools, always use fully qualified tool names.
+
+<format>ServerName:tool_name</format>
+
+<examples>
+- Use the BigQuery:bigquery_schema tool to retrieve table schemas.
+- Use the GitHub:create_issue tool to create issues.
+</examples>
+
+Without the server prefix, Claude may fail to locate the tool, especially when multiple MCP servers are available.
+</mcp_tool_references>