giteadmin/.dotfiles
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add skills

Browse Source
This commit is contained in:
Jonathan Agmon
2026-03-22 23:21:49 +02:00
parent 4cbbbae1ef
commit c09d9151ca
104 changed files with 23879 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1014
.config/opencode/skills/.skill-builder.disabled/SKILL.md Normal file
View File

File diff suppressed because it is too large Load Diff

615
.config/opencode/skills/.skill-builder.disabled/references/eval-templates.md Normal file
View File

@@ -0,0 +1,615 @@
# Test Case Templates
Copy-paste templates for creating test cases based on skill type.
## Table of Contents
1. [File Transform Skills](#file-transform-skills)
2. [Code Generation Skills](#code-generation-skills)
3. [Workflow Skills](#workflow-skills)
4. [Tool Integration Skills](#tool-integration-skills)
5. [Documentation Skills](#documentation-skills)
---
## File Transform Skills
For skills that convert, parse, or reformat files.
### Example: CSV to JSON Converter
```json
{
"skill_name": "csv-to-json",
"description": "Converts CSV files to JSON format with data type handling",
"evals": [
{
"id": 1,
"name": "common-case",
"type": "common",
"prompt": "Convert the CSV file at ./data/sales.csv to JSON and save it as ./output/sales.json. The CSV has headers: date, product, quantity, price. Make sure dates are in ISO 8601 format.",
"expected_output": "A JSON file at ./output/sales.json containing an array of objects, each representing a row from the CSV with properly formatted dates.",
"assertions": [
"JSON file exists at ./output/sales.json",
"File contains valid JSON array",
"All dates are in ISO 8601 format (YYYY-MM-DD)",
"Numeric fields (quantity, price) are numbers, not strings"
]
},
{
"id": 2,
"name": "edge-case-large-file",
"type": "edge",
"prompt": "Convert a CSV file with 50,000 rows at ./data/export.csv to JSON. The file contains some rows with missing values in the 'email' column and special characters (emojis) in the 'notes' column.",
"expected_output": "JSON file is created successfully, handling missing values as null or empty strings, and preserving special characters correctly.",
"assertions": [
"Large file is processed without memory errors",
"Missing email values are handled (null or empty string)",
"Special characters and emojis are preserved in output",
"All 50,000 rows are converted"
]
},
{
"id": 3,
"name": "varied-phrasing-casual",
"type": "variation",
"prompt": "Hey, I've got this spreadsheet data/export.csv that I need to turn into JSON. Can you do that for me? Also, the dates are in MM/DD/YYYY format right now - can you make them proper ISO format?",
"expected_output": "Same as common case: JSON file with ISO 8601 dates",
"assertions": [
"Skill triggers with casual language ('turn into', 'proper format')",
"Implicit date formatting requirement is handled",
"Output matches common case results"
]
}
]
}
```
### Template: File Transform Skill
```json
{
"skill_name": "YOUR_SKILL_NAME",
"description": "[Describe what file transformations this skill does]",
"evals": [
{
"id": 1,
"name": "common-case",
"type": "common",
"prompt": "[Realistic request with specific file paths and formats]",
"expected_output": "[What the transformed file should contain]",
"assertions": [
"Output file exists at expected location",
"File is valid [format: JSON, XML, etc.]",
"Data is correctly transformed",
"Specific requirements met (encoding, formatting, etc.)"
]
},
{
"id": 2,
"name": "edge-case",
"type": "edge",
"prompt": "[Large files, special characters, missing data, malformed input]",
"expected_output": "[Graceful handling or error with helpful message]",
"assertions": [
"Edge case is handled appropriately",
"No data loss or corruption",
"Error messages are helpful if transformation fails"
]
},
{
"id": 3,
"name": "varied-phrasing",
"type": "variation",
"prompt": "[Same request with casual language, different wording]",
"expected_output": "[Same as common case]",
"assertions": [
"Skill triggers with varied phrasing",
"Output matches common case",
"Implicit requirements are understood"
]
}
]
}
```
---
## Code Generation Skills
For skills that generate code, scripts, or templates.
### Example: Python Script Generator
```json
{
"skill_name": "python-script-gen",
"description": "Generates Python scripts for file operations and data processing",
"evals": [
{
"id": 1,
"name": "common-case",
"type": "common",
"prompt": "Create a Python script that recursively finds all .log files in /var/log, compresses them with gzip if they're older than 30 days, and moves them to /archive. Handle permission errors gracefully and log all actions to cleanup.log.",
"expected_output": "A Python script that implements the log cleanup functionality with proper error handling, logging, and follows Python best practices.",
"assertions": [
"Script is syntactically valid Python",
"Implements recursive file search",
"Compresses files older than 30 days",
"Handles permission errors gracefully",
"Logs actions to cleanup.log"
]
},
{
"id": 2,
"name": "edge-case-empty-directory",
"type": "edge",
"prompt": "Create a Python script that processes all CSV files in ./data and generates a summary report. What should it do if the directory is empty or doesn't exist?",
"expected_output": "Script handles empty/non-existent directories gracefully with informative error messages and doesn't crash.",
"assertions": [
"Script checks if directory exists before processing",
"Handles empty directory case gracefully",
"Provides informative error message",
"Returns appropriate exit code"
]
},
{
"id": 3,
"name": "varied-phrasing-brief",
"type": "variation",
"prompt": "Write me a python script to backup my photos. It should copy everything from ~/Pictures to ~/Backups/photos with today's date in the folder name. Skip duplicates if possible.",
"expected_output": "Python backup script with timestamped folder and duplicate detection",
"assertions": [
"Skill works with brief, casual description",
"Generates complete script without requiring clarification",
"Handles date formatting for folder name",
"Implements duplicate detection"
]
}
]
}
```
### Template: Code Generation Skill
```json
{
"skill_name": "YOUR_SKILL_NAME",
"description": "[Describe what code this skill generates]",
"evals": [
{
"id": 1,
"name": "common-case",
"type": "common",
"prompt": "[Detailed request with specific requirements and constraints]",
"expected_output": "[Description of the generated code]",
"assertions": [
"Code is syntactically valid",
"Implements all requested features",
"Follows language best practices",
"Includes error handling where appropriate",
"Is well-structured and readable"
]
},
{
"id": 2,
"name": "edge-case",
"type": "edge",
"prompt": "[Ambiguous requirements, missing data, error conditions]",
"expected_output": "[Code handles edge cases or asks for clarification]",
"assertions": [
"Edge cases are handled appropriately",
"Error conditions are managed",
"Code doesn't crash on unexpected input"
]
},
{
"id": 3,
"name": "varied-phrasing",
"type": "variation",
"prompt": "[Same request with minimal details or casual language]",
"expected_output": "[Same quality as common case]",
"assertions": [
"Skill fills in reasonable defaults",
"Generates complete solution",
"Output quality matches detailed request"
]
}
]
}
```
---
## Workflow Skills
For skills that guide multi-step processes.
### Example: Release Workflow
```json
{
"skill_name": "release-workflow",
"description": "Guides the complete software release process",
"evals": [
{
"id": 1,
"name": "common-case",
"type": "common",
"prompt": "I need to create a new release for my Node.js project. The repo is at ~/projects/myapp. We're currently at version 1.2.3 and this is a minor feature release (1.3.0). I need to update the version, create a changelog entry, commit, tag, and push to GitHub.",
"expected_output": "Step-by-step guide covering: version bump in package.json, CHANGELOG.md update, commit creation, annotated tag, and push commands. Should provide copy-pasteable commands.",
"assertions": [
"All release steps are covered",
"Commands are copy-pasteable",
"Version numbers are consistent",
"Validation steps are included",
"Provides rollback guidance"
]
},
{
"id": 2,
"name": "edge-case-dirty-worktree",
"type": "edge",
"prompt": "Help me release version 2.0.0 of my project. By the way, I have some uncommitted changes in my working directory that I'm not sure about.",
"expected_output": "Workflow detects dirty worktree, suggests stashing or committing changes before proceeding with release. Provides commands to handle the situation.",
"assertions": [
"Detects uncommitted changes",
"Warns about dirty worktree",
"Provides options: stash, commit, or abort",
"Doesn't proceed without addressing the issue"
]
},
{
"id": 3,
"name": "varied-phrasing-urgent",
"type": "variation",
"prompt": "Need to push out v2.1.0 ASAP. Hotfix for critical bug. What's the fastest way to get this released?",
"expected_output": "Accelerated workflow prioritizing speed while maintaining essential safety checks",
"assertions": [
"Recognizes urgency from language ('ASAP', 'fastest')",
"Still includes critical safety checks",
"Prioritizes speed without skipping validation",
"Provides streamlined command sequence"
]
}
]
}
```
### Template: Workflow Skill
```json
{
"skill_name": "YOUR_SKILL_NAME",
"description": "[Describe what workflow this skill guides]",
"evals": [
{
"id": 1,
"name": "common-case",
"type": "common",
"prompt": "[Standard workflow request with clear requirements]",
"expected_output": "[Complete step-by-step guide with all necessary steps]",
"assertions": [
"All workflow steps are included",
"Steps are in logical order",
"Validation points are provided",
"Commands are copy-pasteable where applicable",
"Clear success criteria defined"
]
},
{
"id": 2,
"name": "edge-case",
"type": "edge",
"prompt": "[Workflow with complications, errors, or unusual state]",
"expected_output": "[Workflow detects issues and provides guidance]",
"assertions": [
"Detects unusual states or errors",
"Provides recovery options",
"Doesn't proceed blindly",
"Offers rollback or alternative paths"
]
},
{
"id": 3,
"name": "varied-phrasing",
"type": "variation",
"prompt": "[Workflow request with urgency, casual language, or minimal details]",
"expected_output": "[Same workflow adapted to context]",
"assertions": [
"Adapts to urgency level",
"Works with minimal context",
"Still provides complete guidance"
]
}
]
}
```
---
## Tool Integration Skills
For skills that wrap command-line tools.
### Example: Docker Helper
```json
{
"skill_name": "docker-helper",
"description": "Streamlines Docker container and image management",
"evals": [
{
"id": 1,
"name": "common-case",
"type": "common",
"prompt": "I need to deploy my Node.js app using Docker. The Dockerfile is in ~/projects/myapp. Build an image tagged as myapp:v1.0, then run a container named 'myapp-prod' that maps port 3000 to the host. Make sure it restarts automatically if it crashes.",
"expected_output": "Docker commands to build the image and run the container with specified configuration, including restart policy.",
"assertions": [
"Provides correct build command with tag",
"Provides correct run command with port mapping",
"Includes restart policy (--restart unless-stopped or always)",
"Sets container name correctly",
"Commands are copy-pasteable"
]
},
{
"id": 2,
"name": "edge-case-port-conflict",
"type": "edge",
"prompt": "Run my Docker container on port 3000, but I think something might already be using that port on my machine. How do I check and handle this?",
"expected_output": "Commands to check port usage, offer solutions (kill process, use different port, or map to different host port), and proceed accordingly.",
"assertions": [
"Detects potential port conflict",
"Provides command to check port usage",
"Offers multiple solutions",
"Explains trade-offs of each option"
]
},
{
"id": 3,
"name": "varied-phrasing-cleanup",
"type": "variation",
"prompt": "Docker is taking up too much space. Clean up old stuff for me?",
"expected_output": "Commands to clean up stopped containers, unused images, and build cache",
"assertions": [
"Understands implicit request from context",
"Provides safe cleanup commands",
"Warns about data loss where applicable",
"Shows space savings after cleanup"
]
}
]
}
```
### Template: Tool Integration Skill
```json
{
"skill_name": "YOUR_SKILL_NAME",
"description": "[Describe what tool this skill wraps]",
"evals": [
{
"id": 1,
"name": "common-case",
"type": "common",
"prompt": "[Standard tool usage with specific options and requirements]",
"expected_output": "[Correct command(s) with proper flags]",
"assertions": [
"Command syntax is correct",
"All required flags are included",
"Best practices are followed",
"Commands are copy-pasteable",
"Explains what each part does"
]
},
{
"id": 2,
"name": "edge-case",
"type": "edge",
"prompt": "[Tool usage with errors, conflicts, or unusual requirements]",
"expected_output": "[Troubleshooting steps and solutions]",
"assertions": [
"Detects potential issues",
"Provides diagnostic commands",
"Offers multiple solutions",
"Explains risks of each approach"
]
},
{
"id": 3,
"name": "varied-phrasing",
"type": "variation",
"prompt": "[Casual request with vague requirements]",
"expected_output": "[Tool commands with reasonable defaults]",
"assertions": [
"Fills in reasonable defaults",
"Provides complete solution",
"Explains assumptions made"
]
}
]
}
```
---
## Documentation Skills
For skills that help create or review documentation.
### Example: README Generator
```json
{
"skill_name": "readme-generator",
"description": "Creates comprehensive README files for projects",
"evals": [
{
"id": 1,
"name": "common-case",
"type": "common",
"prompt": "Create a README for my Python project. It's a CLI tool called 'file-organizer' that sorts files by type and date. The repo is at ~/projects/file-organizer. It supports Python 3.8+, uses click for CLI, and has features for: organizing by extension, organizing by date, dry-run mode, and config file support.",
"expected_output": "Complete README with: title, description, installation, usage examples, features list, configuration, and contributing sections. Formatted in Markdown.",
"assertions": [
"README is well-structured with clear headings",
"All requested sections are included",
"Installation instructions are clear",
"Usage examples show actual commands",
"Features are listed comprehensively"
]
},
{
"id": 2,
"name": "edge-case-minimal-info",
"type": "edge",
"prompt": "Write a README for my project. It's called 'utils' and it does some stuff with files.",
"expected_output": "README template with placeholder sections and prompts for missing information. Asks clarifying questions or provides generic placeholders.",
"assertions": [
"Creates template structure despite minimal info",
"Uses placeholders for missing details",
"Suggests what information to add",
"Doesn't invent features or functionality"
]
},
{
"id": 3,
"name": "varied-phrasing-casual",
"type": "variation",
"prompt": "Hey can you write a readme for my new js library? It's on npm as 'async-queue'. It helps manage async tasks with a queue so you don't overwhelm APIs. Pretty simple but useful.",
"expected_output": "README with npm installation, basic usage example, and API overview",
"assertions": [
"Understands from package name and casual description",
"Includes npm install instructions",
"Provides JavaScript usage examples",
"Explains the problem it solves"
]
}
]
}
```
### Template: Documentation Skill
```json
{
"skill_name": "YOUR_SKILL_NAME",
"description": "[Describe what documentation this skill helps with]",
"evals": [
{
"id": 1,
"name": "common-case",
"type": "common",
"prompt": "[Detailed request with project information and requirements]",
"expected_output": "[Complete, well-structured documentation]",
"assertions": [
"Documentation is well-organized",
"All required sections are included",
"Examples are clear and relevant",
"Formatting is consistent",
"Language is clear and concise"
]
},
{
"id": 2,
"name": "edge-case",
"type": "edge",
"prompt": "[Vague request with minimal information]",
"expected_output": "[Template with placeholders or clarifying questions]",
"assertions": [
"Creates structure despite limited info",
"Uses appropriate placeholders",
"Identifies missing information",
"Doesn't invent false details"
]
},
{
"id": 3,
"name": "varied-phrasing",
"type": "variation",
"prompt": "[Casual request with implied requirements]",
"expected_output": "[Documentation meeting implicit needs]",
"assertions": [
"Understands implicit requirements",
"Provides complete documentation",
"Matches tone of request"
]
}
]
}
```
---
## Tips for Customizing Templates
### Making Tests Realistic
**Bad:**
```
"Convert CSV to JSON"
```
**Good:**
```
"Convert the CSV file at ./data/sales.csv to JSON and save it as ./output/sales.json. The CSV has headers: date, product, quantity, price. Make sure dates are in ISO 8601 format."
```
### Assertions Should Be Checkable
**Vague:**
```json
"assertions": [
"Output looks good"
]
```
**Specific:**
```json
"assertions": [
"JSON file exists at ./output/sales.json",
"All dates are in ISO 8601 format",
"Numeric fields are numbers, not strings"
]
```
### Edge Cases to Consider
1. **Large data** - Files with 10,000+ rows
2. **Special characters** - Emojis, Unicode, unusual symbols
3. **Missing data** - Empty cells, null values
4. **Wrong format** - CSV with inconsistent columns
5. **Permissions** - Read/write errors
6. **Conflicts** - Port conflicts, file already exists
7. **Empty input** - Zero rows, blank files
8. **Unexpected state** - Dirty git worktree, missing dependencies
### Variation Ideas
1. **Casual language** - "Hey, can you...", "I need to..."
2. **Abbreviated** - Minimal words, assumes context
3. **Urgent** - "ASAP", "quickly", "fastest way"
4. **Uncertain** - "I think", "maybe", "probably"
5. **Brief** - Single sentence, minimal details
6. **Verbose** - Extra context, backstory
---
## Validation Checklist
Before using your evals.json:
- [ ] Contains exactly 3 test cases (common, edge, variation)
- [ ] Each test has unique id (1, 2, 3)
- [ ] Each test has descriptive name
- [ ] Prompts are realistic with specific details
- [ ] Expected outputs are clear
- [ ] Assertions are objectively checkable
- [ ] JSON is valid (run through jq or json linter)
- [ ] File is saved as evals/evals.json in skill directory
Run this to validate:
```bash
jq . evals/evals.json > /dev/null && echo "Valid JSON" || echo "Invalid JSON"
```

607
.config/opencode/skills/.skill-builder.disabled/references/grading-guide.md Normal file
View File

@@ -0,0 +1,607 @@
# Grading Guide
Comprehensive guide for evaluating skill outputs and identifying improvements.
## Table of Contents
1. [The Evaluation Framework](#the-evaluation-framework)
2. [Correctness](#correctness)
3. [Completeness](#completeness)
4. [Format](#format)
5. [Triggering](#triggering)
6. [Efficiency](#efficiency)
7. [Identifying Patterns](#identifying-patterns)
8. [Decision Framework](#decision-framework)
9. [Common Issues and Solutions](#common-issues-and-solutions)
10. [When to Stop Iterating](#when-to-stop-iterating)
---
## The Evaluation Framework
Evaluate skill outputs across five dimensions:
1. **Correctness** - Is the output accurate and correct?
2. **Completeness** - Are all requirements met?
3. **Format** - Does it follow expected structure?
4. **Triggering** - Does it activate appropriately?
5. **Efficiency** - Is it concise yet complete?
Each dimension has specific criteria to check. Use the grade-output.sh script for systematic evaluation.
---
## Correctness
### What to Check
**Output matches expected result:**
- For file transforms: Output file contains correct data
- For code generation: Code works as described
- For workflows: All steps lead to desired outcome
- For documentation: Information is accurate
**No factual errors:**
- Commands use correct syntax
- File paths are accurate
- Versions are correct
- Technical details are right
**Logic is sound:**
- Reasoning makes sense
- Steps follow logically
- No contradictions
- Edge cases considered
**Edge cases handled appropriately:**
- Empty inputs don't crash
- Large inputs work
- Special characters preserved
- Errors handled gracefully
### Examples
**Good (Correct):**
```bash
# Command actually works
docker run -p 3000:3000 --name myapp myimage:v1.0
```
**Bad (Incorrect):**
```bash
# Wrong flag syntax
docker run --port 3000:3000 myimage # Should be -p or --publish
```
**Good (Handles Edge Cases):**
```python
import os
if os.path.exists(filename):
process_file(filename)
else:
print(f"Error: {filename} not found")
```
**Bad (No Edge Case Handling):**
```python
process_file(filename) # Will crash if file doesn't exist
```
---
## Completeness
### What to Check
**All requested tasks completed:**
- Every requirement from prompt addressed
- No steps forgotten
- All files generated
- All transformations applied
**No steps skipped:**
- Validation steps included
- Cleanup steps not forgotten
- Confirmation steps present
- Rollback guidance provided
**Appropriate level of detail:**
- Not too brief (missing context)
- Not too verbose (information overload)
- Explains "why" not just "what"
- Provides examples where helpful
**Relevant context included:**
- Prerequisites mentioned
- Dependencies noted
- Error scenarios covered
- Alternative approaches offered
### Examples
**Good (Complete):**
```
To release version 1.3.0:
1. Update version in package.json: "version": "1.3.0"
2. Add entry to CHANGELOG.md with today's date
3. Commit: git commit -am "chore(release): bump version to 1.3.0"
4. Create tag: git tag -a v1.3.0 -m "Release 1.3.0"
5. Push: git push origin main && git push origin v1.3.0
6. Create GitHub release: gh release create v1.3.0 --notes-from-tag
Prerequisites:
- All tests passing
- CHANGELOG.md updated
- You have push access to repository
```
**Bad (Incomplete):**
```
To release:
1. Update version
2. Create tag
3. Push
```
---
## Format
### What to Check
**Output follows specified format:**
- If skill defines a template, output matches it
- Markdown formatting is correct
- Code blocks use proper syntax highlighting
- Tables are properly formatted
**Consistent with examples in skill:**
- Format matches examples in SKILL.md
- Style is consistent
- Terminology is consistent
- Structure follows patterns
**Easy to read and understand:**
- Clear headings and sections
- Good use of whitespace
- Logical organization
- No wall of text
### Examples
**Good (Well-Formatted):**
```markdown
## Deployment Steps
### 1. Build Docker Image
```bash
docker build -t myapp:v1.0 .
```
### 2. Run Container
```bash
docker run -d -p 3000:3000 --name myapp myapp:v1.0
```
### 3. Verify Deployment
```bash
curl http://localhost:3000/health
```
```
**Bad (Poor Formatting):**
```
step 1: build the image with docker build -t myapp:v1.0 . then step 2 run the container with docker run -d -p 3000:3000 --name myapp myapp:v1.0 and step 3 verify with curl
```
---
## Triggering
### What to Check
**Skill activates when appropriate:**
- Relevant triggers work
- Similar phrasings activate it
- Context clues are recognized
- Doesn't require exact keywords
**Doesn't activate when inappropriate:**
- Adjacent domains don't trigger it
- Ambiguous queries don't wrongly trigger
- Different tools aren't confused
- Scope is respected
### Testing Triggering
Test with 8 queries (4 should-trigger, 4 should-not-trigger):
**Example for Docker skill:**
Should trigger:
1. "Create a docker container for my Node.js app"
2. "Build an image from this Dockerfile"
3. "How do I compose up my services?"
4. "I need to deploy this using containers"
Should not trigger:
1. "Install Docker on my machine" (installation vs usage)
2. "What is containerization?" (education vs hands-on)
3. "Show me Kubernetes commands" (different tool)
4. "Write a fibonacci function" (completely unrelated)
### Examples
**Good (Appropriate Triggering):**
- User: "containerize my app"
- Skill: Docker helper activates ✓
**Bad (Missed Trigger):**
- User: "I need to run my app in containers"
- Skill: Doesn't activate (too narrow description) ✗
**Bad (False Trigger):**
- User: "Install Docker on Ubuntu"
- Skill: Activates but only handles usage, not installation ✗
---
## Efficiency
### What to Check
**No unnecessary steps:**
- Doesn't do redundant work
- Doesn't suggest unnecessary commands
- Shortcuts used where safe
- Process is streamlined
**Reasonable response length:**
- Not excessively verbose
- Doesn't repeat information
- No filler content
- Every sentence adds value
**Not overly verbose:**
- Commands not over-explained
- Doesn't explain obvious steps
- Concise but complete
- Respects user's expertise
### Examples
**Good (Efficient):**
```bash
# Clean up Docker resources
docker system prune -f
```
**Bad (Verbose):**
```bash
# Clean up Docker resources
# First, we need to run the docker command
# Then we use the system subcommand
# Then we use the prune subcommand
# The -f flag means force
docker system prune -f
# This will remove stopped containers, unused networks, and dangling images
```
---
## Identifying Patterns
### Single Test Failure
**Characteristics:**
- Only one test case fails
- Issue is unique to that scenario
- Other tests pass
**Action:**
- Add targeted instruction
- Include example for that edge case
- Fix the specific issue
- Don't generalize prematurely
**Example:**
```
Issue: Large file processing fails
Solution: Add instruction about memory-efficient processing
for files over 10,000 rows
```
### Multiple Test Failures (Same Issue)
**Characteristics:**
- Same problem across 2+ tests
- Pattern suggests root cause
- Symptom appears in different forms
**Action:**
- Fix the root cause
- Add general principle, not specific fix
- Consider extracting to script
- Explain the "why"
**Example:**
```
Issue: Tests 1 and 3 both have incorrect date formatting
Solution: Add general instruction about ISO 8601 date format
rather than fixing each case individually
```
### Multiple Test Failures (Different Issues)
**Characteristics:**
- Different problems in each test
- No clear pattern
- Skill may be too broad
**Action:**
- Clarify scope in description
- Add more specific instructions
- Consider splitting into multiple skills
- Focus on core functionality first
**Example:**
```
Issue: Test 1 fails on format, Test 2 fails on logic, Test 3
never triggers skill
Solution: Clarify what the skill does/doesn't do in description
Add validation steps
```
---
## Decision Framework
### Fix Specific Case When:
- Unique edge case not covered
- One-time issue unlikely to recur
- Fix is simple and doesn't add complexity
- Doesn't indicate systemic problem
**Example:**
```
Test: CSV with Unicode characters fails
Fix: Add note about UTF-8 encoding for international characters
(Don't rewrite entire CSV handling)
```
### Generalize Solution When:
- Same issue in 2+ tests
- Pattern suggests broader applicability
- Fix would benefit similar requests
- Explains underlying principle
**Example:**
```
Tests: Both test 1 and 2 have incorrect error handling
Fix: Add general principle about validating inputs before processing
with examples of common validation checks
```
### Extract to Script When:
- Same multi-step process repeated
- Deterministic operation (not creative)
- Would save time on every invocation
- Logic is complex or error-prone
**Example:**
```
Pattern: All three tests require converting dates to ISO format
Action: Create scripts/convert-dates.py
Include in SKILL.md: "Use scripts/convert-dates.py for date formatting"
```
---
## Common Issues and Solutions
### Issue: Skill Doesn't Trigger
**Symptoms:**
- User says relevant phrase
- Skill doesn't appear in available skills
- Model handles request without skill
**Solutions:**
1. Add specific trigger phrases to description
2. Use "pushy" language: "Make sure to use this skill whenever..."
3. Include synonyms and variations
4. Test with 8 trigger queries
### Issue: Output Format Inconsistent
**Symptoms:**
- Sometimes follows template, sometimes doesn't
- Format varies between similar requests
- Missing sections or elements
**Solutions:**
1. Add explicit format template in SKILL.md
2. Provide multiple examples
3. Explain why format matters
4. Use imperative: "ALWAYS use this template"
### Issue: Edge Cases Not Handled
**Symptoms:**
- Large files cause errors
- Empty inputs crash
- Special characters corrupted
- Missing data causes failures
**Solutions:**
1. Add validation step instructions
2. Include error handling examples
3. Create helper script for complex validation
4. Document known limitations
### Issue: Too Verbose
**Symptoms:**
- Responses are walls of text
- Over-explains obvious steps
- Repeats information
- Takes too long to get to point
**Solutions:**
1. Remove redundant explanations
2. Trust user's expertise
3. Move details to references/
4. Use progressive disclosure
### Issue: Incomplete Responses
**Symptoms:**
- Misses steps in workflow
- Forgets validation
- Doesn't mention prerequisites
- No error handling
**Solutions:**
1. Add comprehensive checklist in SKILL.md
2. Include validation at each step
3. Document prerequisites upfront
4. Add error handling examples
### Issue: Incorrect Commands
**Symptoms:**
- Commands don't work when copied
- Syntax errors
- Wrong flags or options
- Outdated versions
**Solutions:**
1. Test all commands before including
2. Specify version requirements
3. Add validation steps
4. Include error messages to expect
---
## When to Stop Iterating
### Stop When:
1. **User is satisfied**
- User says "this works for me"
- User stops requesting changes
- User starts using skill regularly
2. **Outputs meet expectations**
- All test cases pass
- Common scenarios work
- Edge cases handled reasonably
- No critical issues remain
3. **No meaningful progress**
- Last 2-3 iterations didn't improve results
- Changes are cosmetic only
- Diminishing returns on effort
- 90% solution is good enough
### Don't Stop When:
- **Perfect is the enemy of good** - 90% working is better than endlessly tweaking
- **Edge cases are theoretical** - Don't over-engineer for unlikely scenarios
- **User wants to keep iterating** - Follow user's lead
- **New issues emerge** - Fix real problems as they're found
### The 90% Rule
A skill that works well for 90% of cases is sufficient. Users can handle:
- Rare edge cases manually
- Unique situations with custom guidance
- Complex scenarios with multiple steps
**Focus on:**
- Common use cases (80% of value)
- Clear failure messages (10% of value)
- Good documentation (10% of value)
**Don't focus on:**
- Every possible edge case (diminishing returns)
- Perfect formatting (good enough is fine)
- Handling every possible error (major errors are enough)
---
## Grading Checklist
Use this checklist for each test case:
### Correctness
- [ ] Output matches expected result
- [ ] No factual errors
- [ ] Logic is sound
- [ ] Edge cases handled appropriately
### Completeness
- [ ] All requested tasks completed
- [ ] No steps skipped
- [ ] Appropriate level of detail
- [ ] Relevant context included
### Format
- [ ] Output follows specified format
- [ ] Consistent with examples
- [ ] Easy to read and understand
### Triggering
- [ ] Skill activated when appropriate
- [ ] Did not activate when inappropriate
### Efficiency
- [ ] No unnecessary steps
- [ ] Reasonable response length
- [ ] Not overly verbose
### Overall
- [ ] Would use this skill again
- [ ] Would recommend to others
- [ ] Saves time vs manual approach
- [ ] Output quality meets needs
---
## Recording Results
After grading, record:
```json
{
"test_id": 1,
"result": "pass|fail|partial",
"issues": [
"Description of issue 1",
"Description of issue 2"
],
"suggested_fix": "Brief description of improvement",
"extract_script": false,
"priority": "high|medium|low"
}
```
Use the grade-output.sh script to generate this structure interactively.
---
## Next Steps After Grading
1. **Review all results** - Look for patterns
2. **Prioritize fixes** - High priority first
3. **Update SKILL.md** - Based on issues found
4. **Create scripts** - Extract repeated work
5. **Re-run tests** - Verify improvements
6. **Repeat** - Until satisfied or good enough

888
.config/opencode/skills/.skill-builder.disabled/references/skill-templates.md Normal file
View File

@@ -0,0 +1,888 @@
# Skill Templates
Copy-paste templates for common skill patterns. Use these as starting points when creating new skills.
## Table of Contents
1. [Simple Skill (Knowledge Only)](#simple-skill)
2. [Tool Integration Skill](#tool-integration-skill)
3. [Workflow Skill](#workflow-skill)
4. [Documentation Skill](#documentation-skill)
5. [Testing Your Skill](#testing-your-skill)
---
## Simple Skill
For skills that provide knowledge without scripts or complex resources.
**Use when:** The skill provides guidance, best practices, or reference information that can be explained in text.
### Directory Structure
```
simple-skill/
└── SKILL.md
```
### SKILL.md Template
```markdown
---
name: simple-skill
description: This skill should be used when the user asks to "TRIGGER_PHRASE_1", "TRIGGER_PHRASE_2", or needs help with SPECIFIC_TASK
license: MIT
compatibility: opencode
metadata:
category: CATEGORY
version: "1.0.0"
---
# Simple Skill Name
Brief description of what this skill covers.
## Overview
High-level explanation of the domain or topic.
## Common Tasks
### Task 1: Description
Step-by-step instructions:
1. First step with code example
2. Second step with code example
3. Third step
### Task 2: Description
Step-by-step instructions:
1. First step
2. Second step
## Best Practices
- Bullet point 1
- Bullet point 2
- Bullet point 3
## Important Notes
- Critical caveat 1
- Critical caveat 2
```
### Example: Git Commit Guidelines
```markdown
---
name: git-commit-guide
description: This skill should be used when the user asks to "write a commit message", "format a commit", "conventional commits", or needs help with Git commit standards
license: MIT
compatibility: opencode
---
# Git Commit Guidelines
Follow conventional commits specification for clear, structured commit messages.
## Format
```
<type>(<scope>): <description>
[optional body]
[optional footer]
```
## Types
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation only
- `style`: Code style (formatting, semicolons, etc)
- `refactor`: Code refactoring
- `test`: Adding or updating tests
- `chore`: Maintenance tasks
## Examples
```bash
# Feature
feat(auth): add OAuth2 login support
# Fix with scope
fix(api): resolve null pointer in user endpoint
# Breaking change
feat(db)!: migrate to PostgreSQL
```
## Rules
- Use imperative mood: "add" not "added"
- Don't capitalize first letter
- No period at end
- Keep first line under 72 characters
```
---
## Tool Integration Skill
For skills that interact with command-line tools and include automation scripts.
**Use when:** The skill wraps a CLI tool, provides automation, or requires executable scripts.
### Directory Structure
```
tool-skill/
├── SKILL.md
├── scripts/
│ └── helper.sh
├── references/
│ └── advanced-usage.md
└── evals/
└── evals.json
```
### SKILL.md Template
```markdown
---
name: tool-skill
description: This skill should be used when the user asks to "TRIGGER_PHRASE_1", "run TOOL_NAME", "TOOL_NAME commands", or work with TOOL_NAME
license: MIT
compatibility: opencode
metadata:
category: tools
version: "1.0.0"
---
# Tool Name Integration
Interact with TOOL_NAME for SPECIFIC_PURPOSE.
## Quick Start
Basic usage:
```bash
tool-name --option value
```
## Common Operations
### Operation 1: Description
```bash
# Example command
tool-name command --flag
```
Explanation of what this does.
### Operation 2: Description
```bash
# Example command
tool-name another-command
```
## Scripts
Use helper scripts in `scripts/`:
- `scripts/helper.sh` - What this script does
## Advanced Usage
For detailed options and edge cases, see `references/advanced-usage.md`.
## Important Notes
- Requirement 1
- Requirement 2
- Common pitfall
```
### scripts/helper.sh Template
```bash
#!/bin/bash
#
# Helper script for TOOL_NAME operations
#
set -euo pipefail
# Configuration
DEFAULT_OPTION="value"
# Functions
show_help() {
cat << EOF
Usage: $0 [OPTIONS]
Helper script for TOOL_NAME
Options:
-h, --help Show this help message
-v, --verbose Enable verbose output
-o, --option Specify option value
Examples:
$0 --verbose
$0 --option custom-value
EOF
}
# Parse arguments
VERBOSE=false
OPTION="$DEFAULT_OPTION"
while [[ $# -gt 0 ]]; do
case $1 in
-h|--help)
show_help
exit 0
;;
-v|--verbose)
VERBOSE=true
shift
;;
-o|--option)
OPTION="$2"
shift 2
;;
*)
echo "Unknown option: $1"
show_help
exit 1
;;
esac
done
# Main logic
main() {
[[ "$VERBOSE" == true ]] && echo "Running with option: $OPTION"
# Your tool integration logic here
echo "Helper script executed successfully"
}
main "$@"
```
### Example: Docker Helper
```markdown
---
name: docker-helper
description: This skill should be used when the user asks to "manage docker containers", "build docker images", "docker compose operations", or work with Docker workflows
license: MIT
compatibility: opencode
---
# Docker Helper
Streamline Docker container and image management.
## Quick Commands
### List Running Containers
```bash
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
```
### Clean Up System
```bash
# Remove stopped containers, unused networks, dangling images
docker system prune -f
```
## Scripts
Use helper scripts:
- `scripts/container-logs.sh` - View and follow container logs
- `scripts/cleanup.sh` - Safe cleanup of unused resources
## Docker Compose
### Start Services
```bash
docker compose up -d SERVICE_NAME
```
### View Logs
```bash
docker compose logs -f SERVICE_NAME
```
## References
- `references/compose-patterns.md` - Advanced compose configurations
- `references/troubleshooting.md` - Common issues and solutions
```
---
## Workflow Skill
For skills that guide multi-step processes or complex procedures.
**Use when:** The skill orchestrates a sequence of steps, decisions, or collaborative tasks.
### Directory Structure
```
workflow-skill/
├── SKILL.md
├── scripts/
│ ├── step-validator.sh
│ └── automation.sh
├── references/
│ ├── decision-matrix.md
│ └── examples/
│ └── sample-workflow.md
└── evals/
└── evals.json
```
### SKILL.md Template
```markdown
---
name: workflow-skill
description: This skill should be used when the user asks to "WORKFLOW_NAME", "perform WORKFLOW_TASK", "WORKFLOW_VERB process", or needs help with WORKFLOW_DOMAIN
license: MIT
compatibility: opencode
metadata:
category: workflow
version: "1.0.0"
---
# Workflow Name
Guide the WORKFLOW_PROCESS from start to finish with validation at each step.
## Prerequisites
Before starting, ensure:
1. Requirement 1
2. Requirement 2
3. Requirement 3
## Workflow Overview
```
Step 1 → Step 2 → Step 3 → Completion
↓ ↓ ↓
Validate Validate Validate
```
## Step-by-Step Process
### Step 1: Preparation
**Objective:** What to accomplish in this step
**Actions:**
1. Action item 1
2. Action item 2
**Validation:**
- [ ] Check item 1
- [ ] Check item 2
**Script:** `scripts/step-validator.sh --step 1`
### Step 2: Execution
**Objective:** What to accomplish in this step
**Actions:**
1. Action item 1
2. Action item 2
**Validation:**
- [ ] Check item 1
- [ ] Check item 2
**Decision Point:**
If CONDITION_A:
- Follow path A (see `references/path-a.md`)
If CONDITION_B:
- Follow path B (see `references/path-b.md`)
### Step 3: Verification
**Objective:** Final checks and completion
**Actions:**
1. Run verification command
2. Review output
**Validation:**
- [ ] All checks pass
- [ ] No errors in logs
## Automation
For automated execution:
```bash
scripts/automation.sh --full
```
## Troubleshooting
See `references/troubleshooting.md` for common issues.
## Examples
Complete workflow examples in `references/examples/`.
```
### Example: Release Workflow
```markdown
---
name: release-workflow
description: This skill should be used when the user asks to "create a release", "publish a new version", "tag a release", or prepare software for deployment
license: MIT
compatibility: opencode
---
# Release Workflow
Guide the complete release process from version bump to deployment.
## Prerequisites
- [ ] All tests passing
- [ ] CHANGELOG.md updated
- [ ] Version number decided
## Workflow
### Step 1: Pre-Release Checks
**Actions:**
1. Run full test suite: `npm test`
2. Verify CHANGELOG.md is current
3. Check for uncommitted changes
**Validation:**
```bash
scripts/pre-release-check.sh
```
### Step 2: Version Bump
**Actions:**
1. Update version in package.json
2. Update CHANGELOG.md with release date
3. Commit with message: `chore(release): bump version to X.Y.Z`
**Validation:**
- [ ] Version updated in all files
- [ ] CHANGELOG.md has date
- [ ] Commit created
### Step 3: Create Tag
**Actions:**
1. Create annotated tag: `git tag -a vX.Y.Z -m "Release X.Y.Z"`
2. Push tag: `git push origin vX.Y.Z`
**Validation:**
```bash
scripts/verify-tag.sh vX.Y.Z
```
### Step 4: GitHub Release
**Actions:**
1. Draft release notes from CHANGELOG
2. Create GitHub release
3. Attach artifacts if needed
**Command:**
```bash
gh release create vX.Y.Z --notes-from-tag
```
## Decision Matrix
See `references/decision-matrix.md` for:
- Version numbering (semver vs calver)
- Pre-release vs stable
- Hotfix procedures
```
---
## Documentation Skill
For skills focused on writing, reviewing, or managing documentation.
**Use when:** The skill helps create documentation, enforces standards, or provides writing guidelines.
### Directory Structure
```
docs-skill/
├── SKILL.md
├── references/
│ ├── style-guide.md
│ ├── templates/
│ │ ├── README-template.md
│ │ └── API-doc-template.md
│ └── examples/
│ └── sample-docs/
├── assets/
│ └── diagram-template.png
└── evals/
└── evals.json
```
### SKILL.md Template
```markdown
---
name: docs-skill
description: This skill should be used when the user asks to "write documentation", "create a README", "document this code", "review docs", or needs help with technical writing
license: MIT
compatibility: opencode
metadata:
category: documentation
version: "1.0.0"
---
# Documentation Helper
Create clear, consistent, and effective technical documentation.
## Quick Start
### Create README
Start with the template:
```bash
cp references/templates/README-template.md ./README.md
```
Then fill in:
1. Project name and description
2. Installation steps
3. Usage examples
4. API reference (if applicable)
## Documentation Types
### README.md
Essential sections:
- Title and description
- Installation
- Quick start
- Usage examples
- API reference (if applicable)
- Contributing
- License
Use template: `references/templates/README-template.md`
### API Documentation
Structure:
- Endpoint description
- Request format
- Response format
- Error codes
- Examples
Use template: `references/templates/API-doc-template.md`
### Code Comments
Follow style guide in `references/style-guide.md`:
- JSDoc for JavaScript
- Docstrings for Python
- Rustdoc for Rust
## Style Guide
See `references/style-guide.md` for:
- Tone and voice
- Formatting rules
- Terminology
- Code example standards
## Review Checklist
Before finalizing documentation:
- [ ] Clear and concise
- [ ] No typos or grammar errors
- [ ] Code examples work
- [ ] All links functional
- [ ] Proper heading hierarchy
- [ ] Consistent formatting
## Examples
Review well-documented projects in `references/examples/`.
## Assets
- `assets/diagram-template.png` - Template for architecture diagrams
```
### Example: API Documentation Helper
```markdown
---
name: api-docs-helper
description: This skill should be used when the user asks to "document an API", "create API documentation", "write endpoint docs", or needs help with REST API documentation
license: MIT
compatibility: opencode
---
# API Documentation Helper
Create comprehensive REST API documentation following OpenAPI standards.
## Endpoint Documentation Template
For each endpoint, document:
### 1. Overview
```markdown
## POST /api/v1/resource
Brief description of what this endpoint does.
**Authorization:** Required (Bearer token)
**Rate Limit:** 100 requests/minute
```
### 2. Request
```markdown
### Headers
| Header | Value | Required |
|--------|-------|----------|
| Content-Type | application/json | Yes |
| Authorization | Bearer {token} | Yes |
### Body
```json
{
"field1": "string (required) - Description",
"field2": "number (optional) - Description"
}
```
```
### 3. Response
```markdown
### Success (200 OK)
```json
{
"id": "string",
"created_at": "ISO 8601 datetime",
"status": "active"
}
```
### Error Responses
- `400 Bad Request` - Invalid input
- `401 Unauthorized` - Missing/invalid token
- `404 Not Found` - Resource doesn't exist
```
### 4. Examples
Provide curl and client library examples.
## Standards
Follow conventions in `references/api-standards.md`:
- Use JSON for request/response bodies
- ISO 8601 for dates
- snake_case for field names
- Include pagination metadata for lists
## Tools
Validate documentation:
- `scripts/validate-openapi.sh` - Check OpenAPI spec
- `scripts/check-examples.sh` - Verify code examples work
```
---
## Testing Your Skill
After creating a skill from these templates, follow this testing workflow:
### Step 1: Create Test Cases
Generate test cases for your skill:
```bash
~/.config/opencode/skills/skill-builder/scripts/create-tests.sh ~/.config/opencode/skills/your-skill
```
This creates `evals/evals.json` with 3 template test cases:
1. **Common Case** - Typical usage scenario
2. **Edge Case** - Tricky or unusual situation
3. **Varied Phrasing** - Same intent, different words
### Step 2: Customize Test Prompts
Edit `evals/evals.json` and replace placeholder text with realistic test prompts:
**Good test prompt:**
```
Convert the CSV file at ./data/sales.csv to JSON and save it as ./output/sales.json.
The CSV has headers: date, product, quantity, price. Make sure dates are in ISO 8601 format.
```
**Bad test prompt:**
```
Convert CSV to JSON
```
See `eval-templates.md` for copy-paste templates for different skill types.
### Step 3: Run Tests
Execute the test workflow:
```bash
~/.config/opencode/skills/skill-builder/scripts/run-tests.sh ~/.config/opencode/skills/your-skill
```
This will:
- Display each test prompt
- Guide you through manual testing in opencode
- Record your evaluations (pass/fail/skip)
- Save results to `evals/test-results.json`
### Step 4: Grade Results
Use the grading checklist for systematic evaluation:
```bash
~/.config/opencode/skills/skill-builder/scripts/grade-output.sh ~/.config/opencode/skills/your-skill
```
This evaluates:
- Correctness
- Completeness
- Format
- Triggering
- Efficiency
And generates `evals/grading-report.json` with structured feedback.
### Step 5: Iterate
Based on test results, improve your skill:
1. Review issues in grading report
2. Update SKILL.md with fixes
3. Re-run tests
4. Repeat until satisfied
See `grading-guide.md` for detailed evaluation criteria and decision frameworks.
### Testing by Skill Type
**Simple Skills:**
- May not need formal test cases
- Test manually with 2-3 realistic prompts
- Verify outputs are helpful and accurate
**Tool Integration Skills:**
- Must test all commands work when copied
- Verify edge cases (errors, conflicts)
- Test with different tool versions if possible
**Workflow Skills:**
- Test complete end-to-end flow
- Verify each step produces correct result
- Test decision points and branches
- Check error recovery paths
**Code Generation Skills:**
- Verify generated code is syntactically valid
- Test that code actually runs
- Check edge cases (empty input, large data)
- Validate error handling
### When to Stop Testing
Stop iterating when:
- All critical test cases pass
- User is satisfied with quality
- Common scenarios work reliably
- No longer making meaningful improvements
Remember: A skill that works well for 90% of cases is sufficient. Perfection is the enemy of good.
---
## Tips for All Templates
1. **Replace placeholders immediately** - Search for `TRIGGER_PHRASE`, `TOOL_NAME`, etc.
2. **Write description first** - Include 3-5 specific trigger phrases in quotes
3. **Keep examples working** - Test all code examples before finalizing
4. **Validate early and often** - Run validation after every significant change
5. **Progressive disclosure** - Move details to references/ as the skill grows
6. **Be specific** - Generic skills don't trigger well. Make descriptions concrete.
7. **Test triggers** - After creating, try phrases from your description to verify activation
## Validation Checklist for New Skills
Before considering a skill complete:
- [ ] SKILL.md created with proper frontmatter
- [ ] `name` matches directory name
- [ ] `description` is 20-1024 characters with trigger phrases
- [ ] No second-person writing in body
- [ ] All scripts are executable
- [ ] Referenced files exist and are mentioned in SKILL.md
- [ ] Validation passes: `validate-skill.sh /path/to/skill`
- [ ] Test cases created in `evals/evals.json`
- [ ] Tests pass or issues documented
- [ ] Tested with actual trigger phrases

179
.config/opencode/skills/.skill-builder.disabled/scripts/create-tests.sh Executable file
View File

@@ -0,0 +1,179 @@
#!/bin/bash
#
# create-tests.sh - Interactive test case generator for skills
#
# Usage: ./create-tests.sh <path/to/skill-directory>
#
# This script interactively generates evals/evals.json with 3 template test cases.
#
set -euo pipefail
# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color
# Parse arguments
SKILL_DIR=""
usage() {
echo "Usage: $0 <path/to/skill-directory>"
echo ""
echo "Examples:"
echo " $0 ~/.config/opencode/skills/my-skill"
echo " $0 ./my-skill"
exit 1
}
# Parse command line arguments
while [[ $# -gt 0 ]]; do
case $1 in
-h|--help)
usage
;;
-*)
echo -e "${RED}Error: Unknown option $1${NC}"
usage
;;
*)
if [[ -z "$SKILL_DIR" ]]; then
SKILL_DIR="$1"
else
echo -e "${RED}Error: Multiple skill directories provided${NC}"
usage
fi
shift
;;
esac
done
# Validate skill directory
if [[ -z "$SKILL_DIR" ]]; then
echo -e "${RED}Error: Skill directory is required${NC}"
usage
fi
# Resolve path
SKILL_DIR="$(cd "$SKILL_DIR" 2>/dev/null && pwd)" || {
echo -e "${RED}Error: Cannot access directory: $SKILL_DIR${NC}"
exit 1
}
# Get skill name from directory
SKILL_NAME="$(basename "$SKILL_DIR")"
# Verify SKILL.md exists
if [[ ! -f "$SKILL_DIR/SKILL.md" ]]; then
echo -e "${RED}Error: SKILL.md not found in $SKILL_DIR${NC}"
echo "This does not appear to be a valid skill directory."
exit 1
fi
echo "========================================"
echo "Creating Test Cases for: $SKILL_NAME"
echo "========================================"
echo ""
# Create evals directory
mkdir -p "$SKILL_DIR/evals"
echo -e "${GREEN}✓ Created evals/ directory${NC}"
echo ""
# Check if evals.json already exists
if [[ -f "$SKILL_DIR/evals/evals.json" ]]; then
echo -e "${YELLOW}⚠ evals.json already exists${NC}"
read -p "Overwrite? (y/N): " -n 1 -r
echo
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
echo "Aborted."
exit 0
fi
fi
# Get skill purpose from user
echo "Let's create 3 test cases for your skill."
echo ""
echo "First, tell me about your skill's purpose:"
echo " (e.g., 'Helps users convert CSV files to JSON format')"
read -r SKILL_PURPOSE
if [[ -z "$SKILL_PURPOSE" ]]; then
SKILL_PURPOSE="[Describe what your skill does]"
fi
echo ""
echo "Now I'll generate 3 test case templates."
echo "You can edit evals/evals.json later to customize them."
echo ""
# Generate evals.json
cat > "$SKILL_DIR/evals/evals.json" << EVALSJSON
{
"skill_name": "$SKILL_NAME",
"description": "$SKILL_PURPOSE",
"evals": [
{
"id": 1,
"name": "common-case",
"type": "common",
"prompt": "[REPLACE WITH REALISTIC USER REQUEST]\n\nExample: Convert the CSV file at ./data/sales.csv to JSON format and save it as ./output/sales.json. Make sure dates are in ISO 8601 format.",
"expected_output": "[DESCRIBE EXPECTED RESULT]\n\nExample: A JSON file at ./output/sales.json containing the sales data from the CSV, with all dates converted to ISO 8601 format.",
"assertions": [
"Output file exists at the specified location",
"File is valid JSON",
"Dates are in ISO 8601 format"
],
"notes": "This tests the typical, straightforward use case."
},
{
"id": 2,
"name": "edge-case",
"type": "edge",
"prompt": "[REPLACE WITH EDGE CASE SCENARIO]\n\nExample: Convert a CSV file with 100,000 rows, some containing special characters (emojis, Unicode) and empty values in certain columns. The file is at ./data/large_export.csv.",
"expected_output": "[DESCRIBE EXPECTED BEHAVIOR]\n\nExample: JSON file is created successfully, handling all special characters correctly and preserving empty values as null or empty strings.",
"assertions": [
"Large file is processed without errors",
"Special characters are preserved correctly",
"Empty values are handled appropriately"
],
"notes": "This tests edge cases like large files, special characters, or missing data."
},
{
"id": 3,
"name": "varied-phrasing",
"type": "variation",
"prompt": "[REPLACE WITH SAME INTENT, DIFFERENT WORDS]\n\nExample: Hey, I've got this spreadsheet in data/sales.csv. Can you turn it into JSON for me? And make sure the dates look right - you know, standard format?",
"expected_output": "[SAME AS COMMON CASE]",
"assertions": [
"Skill triggers correctly with casual language",
"Output matches common case results",
"Implicit requirements (date formatting) are handled"
],
"notes": "This tests that the skill works with different phrasings and casual language."
}
]
}
EVALSJSON
echo -e "${GREEN}✓ Created evals/evals.json${NC}"
echo ""
echo "========================================"
echo "Next Steps:"
echo "========================================"
echo ""
echo "1. Edit evals/evals.json"
echo " Replace the [PLACEHOLDER] text with realistic test cases"
echo ""
echo "2. Tips for writing good test prompts:"
echo " - Include file paths (e.g., ./data/file.csv)"
echo " - Add personal context (e.g., 'my boss sent me')"
echo " - Use specific values and column names"
echo " - Mix formal and casual language"
echo ""
echo "3. Run tests when ready:"
echo " ~/.config/opencode/skills/skill-builder/scripts/run-tests.sh $SKILL_DIR"
echo ""
echo -e "${GREEN}Done!${NC}"

363
.config/opencode/skills/.skill-builder.disabled/scripts/grade-output.sh Executable file
View File

@@ -0,0 +1,363 @@
#!/bin/bash
#
# grade-output.sh - Interactive grading checklist for skill outputs
#
# Usage: ./grade-output.sh <path/to/skill-directory>
#
# This script provides a structured checklist for evaluating skill test outputs.
#
set -euo pipefail
# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
CYAN='\033[0;36m'
NC='\033[0m' # No Color
# Parse arguments
SKILL_DIR=""
usage() {
echo "Usage: $0 <path/to/skill-directory>"
echo ""
echo "Examples:"
echo " $0 ~/.config/opencode/skills/my-skill"
echo " $0 ./my-skill"
exit 1
}
# Parse command line arguments
while [[ $# -gt 0 ]]; do
case $1 in
-h|--help)
usage
;;
-*)
echo -e "${RED}Error: Unknown option $1${NC}"
usage
;;
*)
if [[ -z "$SKILL_DIR" ]]; then
SKILL_DIR="$1"
else
echo -e "${RED}Error: Multiple skill directories provided${NC}"
usage
fi
shift
;;
esac
done
# Validate skill directory
if [[ -z "$SKILL_DIR" ]]; then
echo -e "${RED}Error: Skill directory is required${NC}"
usage
fi
# Resolve path
SKILL_DIR="$(cd "$SKILL_DIR" 2>/dev/null && pwd)" || {
echo -e "${RED}Error: Cannot access directory: $SKILL_DIR${NC}"
exit 1
}
# Get skill name from directory
SKILL_NAME="$(basename "$SKILL_DIR")"
echo "========================================"
echo "Grading Output for: $SKILL_NAME"
echo "========================================"
echo ""
# Check for test results
if [[ -f "$SKILL_DIR/evals/test-results.json" ]]; then
echo -e "${BLUE}Found previous test results${NC}"
echo ""
fi
# Initialize grading data
declare -a CRITERIA=(
"Correctness: Output matches expected result"
"Correctness: No factual errors"
"Correctness: Logic is sound"
"Correctness: Edge cases handled appropriately"
"Completeness: All requested tasks completed"
"Completeness: No steps skipped"
"Completeness: Appropriate level of detail"
"Completeness: Relevant context included"
"Format: Output follows specified format"
"Format: Consistent with examples in skill"
"Format: Easy to read and understand"
"Triggering: Skill activated when appropriate"
"Triggering: Did not activate when inappropriate"
"Efficiency: No unnecessary steps"
"Efficiency: Reasonable response length"
"Efficiency: Not overly verbose"
)
GRADES=()
ISSUES=()
# Function to ask yes/no question
ask_yes_no() {
local prompt="$1"
while true; do
read -p "$prompt (y/n): " -n 1 -r
echo
case $REPLY in
[Yy])
return 0
;;
[Nn])
return 1
;;
*)
echo "Please enter y or n"
;;
esac
done
}
echo "This checklist will help you systematically evaluate the skill output."
echo "Answer each question based on the test results you observed."
echo ""
read -p "Press Enter to begin grading..."
echo ""
# Grade each criterion
echo "========================================"
echo -e "${CYAN}Grading Criteria${NC}"
echo "========================================"
echo ""
for criterion in "${CRITERIA[@]}"; do
category="${criterion%%:*}"
description="${criterion#*: }"
echo -e "${BLUE}[$category]${NC} $description"
if ask_yes_no " Does it meet this criterion"; then
GRADES+=("$criterion: PASS")
echo -e " ${GREEN}✓ Pass${NC}"
else
GRADES+=("$criterion: FAIL")
echo -e " ${RED}✗ Fail${NC}"
# Ask for issue description
echo " Briefly describe the issue:"
read -r issue
if [[ -n "$issue" ]]; then
ISSUES+=("[$category] $description: $issue")
fi
fi
echo ""
done
# Overall assessment
echo "========================================"
echo -e "${CYAN}Overall Assessment${NC}"
echo "========================================"
echo ""
echo "Overall Result:"
echo " [p] Pass - All or most criteria met"
echo " [f] Fail - Significant issues found"
echo " [i] Incomplete - Needs more testing"
echo ""
while true; do
read -p "Overall result (p/f/i): " -n 1 -r
echo
case $REPLY in
[Pp])
OVERALL_RESULT="pass"
break
;;
[Ff])
OVERALL_RESULT="fail"
break
;;
[Ii])
OVERALL_RESULT="incomplete"
break
;;
*)
echo "Please enter p, f, or i"
;;
esac
done
echo ""
# Priority assessment
echo "Priority of fixes needed:"
echo " [h] High - Critical issues, skill not usable"
echo " [m] Medium - Important issues, skill partially works"
echo " [l] Low - Minor issues, skill mostly works"
echo ""
while true; do
read -p "Priority (h/m/l): " -n 1 -r
echo
case $REPLY in
[Hh])
PRIORITY="high"
break
;;
[Mm])
PRIORITY="medium"
break
;;
[Ll])
PRIORITY="low"
break
;;
*)
echo "Please enter h, m, or l"
;;
esac
done
echo ""
# Suggested fixes
echo -e "${BLUE}Suggested Improvements (optional):${NC}"
echo "Describe what changes would address the issues:"
read -r SUGGESTED_FIXES
echo ""
# Pattern analysis
echo "========================================"
echo -e "${CYAN}Pattern Analysis${NC}"
echo "========================================"
echo ""
if ask_yes_no "Did the same issue appear in multiple test cases"; then
echo "This suggests a systemic problem. Consider:"
echo " - Fixing the root cause rather than symptoms"
echo " - Adding a helper script for repeated tasks"
echo " - Clarifying instructions in SKILL.md"
PATTERN="systemic"
else
echo "Issues appear to be isolated to specific cases."
PATTERN="isolated"
fi
echo ""
# Extract to script recommendation
if ask_yes_no "Should any repeated work be extracted to a script"; then
echo "Consider creating a script in scripts/ directory."
EXTRACT_SCRIPT="true"
else
EXTRACT_SCRIPT="false"
fi
echo ""
# Generate grading report
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
# Build issues array
ISSUES_JSON="["
for i in "${!ISSUES[@]}"; do
if [[ $i -gt 0 ]]; then
ISSUES_JSON+=","
fi
ISSUES_JSON+="\"${ISSUES[$i]}\""
done
ISSUES_JSON+="]"
# Build grades array
GRADES_JSON="["
for i in "${!GRADES[@]}"; do
if [[ $i -gt 0 ]]; then
GRADES_JSON+=","
fi
GRADES_JSON+="\"${GRADES[$i]}\""
done
GRADES_JSON+="]"
# Calculate pass rate
TOTAL_CRITERIA=${#CRITERIA[@]}
PASSED_COUNT=0
for grade in "${GRADES[@]}"; do
if [[ "$grade" == *"PASS" ]]; then
((PASSED_COUNT++))
fi
done
PASS_RATE=$((PASSED_COUNT * 100 / TOTAL_CRITERIA))
cat > "$SKILL_DIR/evals/grading-report.json" << EOF
{
"skill_name": "$SKILL_NAME",
"timestamp": "$TIMESTAMP",
"overall_result": "$OVERALL_RESULT",
"priority": "$PRIORITY",
"pass_rate": $PASS_RATE,
"criteria_passed": $PASSED_COUNT,
"criteria_total": $TOTAL_CRITERIA,
"pattern_analysis": "$PATTERN",
"extract_script_recommended": $EXTRACT_SCRIPT,
"detailed_grades": $GRADES_JSON,
"issues": $ISSUES_JSON,
"suggested_fixes": "$SUGGESTED_FIXES"
}
EOF
echo "========================================"
echo -e "${GREEN}Grading Report Generated${NC}"
echo "========================================"
echo ""
echo "Saved to: evals/grading-report.json"
echo ""
echo "Summary:"
echo " Overall: $OVERALL_RESULT"
echo " Priority: $PRIORITY"
echo " Pass Rate: $PASS_RATE% ($PASSED_COUNT/$TOTAL_CRITERIA criteria)"
echo " Pattern: $PATTERN issues"
echo ""
if [[ ${#ISSUES[@]} -gt 0 ]]; then
echo -e "${YELLOW}Issues Found:${NC}"
for issue in "${ISSUES[@]}"; do
echo " - $issue"
done
echo ""
fi
# Next steps
echo "========================================"
echo "Next Steps"
echo "========================================"
echo ""
if [[ "$OVERALL_RESULT" == "pass" ]]; then
echo -e "${GREEN}✓ Skill is working well!${NC}"
echo ""
echo "Consider:"
echo " - Adding more edge case tests"
echo " - Optimizing the description"
echo " - Documenting the skill"
else
echo "To improve the skill:"
echo ""
echo "1. Review grading-report.json for details"
echo "2. Update SKILL.md based on the issues found"
echo ""
if [[ "$EXTRACT_SCRIPT" == "true" ]]; then
echo "3. Create helper scripts for repeated tasks"
echo " - Place scripts in scripts/ directory"
echo " - Update SKILL.md to reference them"
echo ""
fi
echo "4. Re-run tests to verify improvements:"
echo " ~/.config/opencode/skills/skill-builder/scripts/run-tests.sh $SKILL_DIR"
fi
echo ""
echo -e "${GREEN}Done!${NC}"

391
.config/opencode/skills/.skill-builder.disabled/scripts/init-skill.sh Executable file
View File

@@ -0,0 +1,391 @@
#!/bin/bash
#
# init-skill.sh - Scaffold a new skill with proper structure
#
# Usage: ./init-skill.sh <skill-name> [options]
#
# Options:
# --local Create in current project (.opencode/skills/) instead of global
# --with-scripts Include scripts/ directory
# --with-refs Include references/ directory
# --with-assets Include assets/ directory
# --with-tests Include evals/ directory for test cases
# --full Include all optional directories
#
set -euo pipefail
# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color
# Get script directory
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SKILL_BUILDER_DIR="$(dirname "$SCRIPT_DIR")"
# Parse arguments
SKILL_NAME=""
LOCAL=false
WITH_SCRIPTS=false
WITH_REFS=false
WITH_ASSETS=false
WITH_TESTS=false
usage() {
echo "Usage: $0 <skill-name> [options]"
echo ""
echo "Options:"
echo " --local Create in current project (.opencode/skills/)"
echo " --with-scripts Include scripts/ directory"
echo " --with-refs Include references/ directory"
echo " --with-assets Include assets/ directory"
echo " --with-tests Include evals/ directory for test cases"
echo " --full Include all optional directories"
echo ""
echo "Examples:"
echo " $0 my-skill"
echo " $0 my-skill --full"
echo " $0 my-skill --local --with-scripts"
exit 1
}
# Validate skill name
validate_name() {
local name="$1"
if [[ -z "$name" ]]; then
echo -e "${RED}Error: Skill name is required${NC}"
usage
fi
if [[ ! "$name" =~ ^[a-z0-9-]+$ ]]; then
echo -e "${RED}Error: Skill name must be lowercase alphanumeric with hyphens only${NC}"
echo " Valid: my-skill, docker-helper, test-runner"
echo " Invalid: My Skill, docker_helper, testRunner"
exit 1
fi
if [[ ${#name} -lt 1 ]]; then
echo -e "${RED}Error: Skill name cannot be empty${NC}"
exit 1
fi
if [[ ${#name} -gt 64 ]]; then
echo -e "${RED}Error: Skill name must be under 64 characters${NC}"
exit 1
fi
}
# Parse command line arguments
while [[ $# -gt 0 ]]; do
case $1 in
--local)
LOCAL=true
shift
;;
--with-scripts)
WITH_SCRIPTS=true
shift
;;
--with-refs)
WITH_REFS=true
shift
;;
--with-assets)
WITH_ASSETS=true
shift
;;
--with-tests)
WITH_TESTS=true
shift
;;
--full)
WITH_SCRIPTS=true
WITH_REFS=true
WITH_ASSETS=true
WITH_TESTS=true
shift
;;
-h|--help)
usage
;;
-*)
echo -e "${RED}Error: Unknown option $1${NC}"
usage
;;
*)
if [[ -z "$SKILL_NAME" ]]; then
SKILL_NAME="$1"
else
echo -e "${RED}Error: Multiple skill names provided${NC}"
usage
fi
shift
;;
esac
done
# Validate skill name
validate_name "$SKILL_NAME"
# Determine target directory
if [[ "$LOCAL" == true ]]; then
# Check if we're in a git repository
if ! git rev-parse --git-dir > /dev/null 2>&1; then
echo -e "${RED}Error: --local requires being in a git repository${NC}"
exit 1
fi
TARGET_DIR=".opencode/skills/$SKILL_NAME"
# Check for AGENTS.md in project
if [[ -f "AGENTS.md" ]]; then
echo -e "${GREEN}✓ Found AGENTS.md in project root${NC}"
else
echo -e "${YELLOW}⚠ No AGENTS.md found in project root${NC}"
echo " Consider creating one for project-specific rules"
fi
else
TARGET_DIR="$HOME/.config/opencode/skills/$SKILL_NAME"
fi
# Check if skill already exists
if [[ -d "$TARGET_DIR" ]]; then
echo -e "${RED}Error: Skill already exists at $TARGET_DIR${NC}"
exit 1
fi
echo -e "${GREEN}Creating skill: $SKILL_NAME${NC}"
echo " Location: $TARGET_DIR"
echo ""
# Create skill directory
mkdir -p "$TARGET_DIR"
# Create SKILL.md
cat > "$TARGET_DIR/SKILL.md" << 'SKILL_TEMPLATE'
---
name: SKILL_NAME_PLACEHOLDER
description: This skill should be used when the user asks to "DESCRIPTION_HERE". Add specific trigger phrases that would activate this skill.
license: MIT
compatibility: opencode
metadata:
category: general
version: "1.0.0"
---
# SKILL_NAME_PLACEHOLDER
Brief description of what this skill does and its purpose.
## What This Skill Provides
1. **Feature 1** - Brief description
2. **Feature 2** - Brief description
3. **Feature 3** - Brief description
## Quick Start
Basic usage example:
```bash
# Example command
some-tool --option value
```
## Common Tasks
### Task 1: Description
Step-by-step instructions:
1. First step
2. Second step
3. Third step
### Task 2: Description
Step-by-step instructions:
1. First step
2. Second step
## Important Notes
- Keep this section brief
- Use bullet points for clarity
- Reference supporting files if available
## Resources
SKILL_TEMPLATE
# Add resource section if directories were created
if [[ "$WITH_REFS" == true ]]; then
cat >> "$TARGET_DIR/SKILL.md" << 'REF_SECTION'
### Reference Files
- `references/detailed-guide.md` - Detailed documentation
REF_SECTION
fi
if [[ "$WITH_SCRIPTS" == true ]]; then
cat >> "$TARGET_DIR/SKILL.md" << 'SCRIPT_SECTION'
### Scripts
- `scripts/helper.sh` - Utility script
SCRIPT_SECTION
fi
if [[ "$WITH_ASSETS" == true ]]; then
cat >> "$TARGET_DIR/SKILL.md" << 'ASSET_SECTION'
### Assets
- `assets/template.txt` - Template file
ASSET_SECTION
fi
# Replace placeholder with actual skill name
sed -i "s/SKILL_NAME_PLACEHOLDER/$SKILL_NAME/g" "$TARGET_DIR/SKILL.md"
# Create optional directories
if [[ "$WITH_SCRIPTS" == true ]]; then
mkdir -p "$TARGET_DIR/scripts"
# Create example script
cat > "$TARGET_DIR/scripts/helper.sh" << 'SCRIPT_EXAMPLE'
#!/bin/bash
#
# Helper script for SKILL_NAME_PLACEHOLDER
#
set -euo pipefail
echo "Helper script for SKILL_NAME_PLACEHOLDER"
echo "Modify this script for your needs"
SCRIPT_EXAMPLE
sed -i "s/SKILL_NAME_PLACEHOLDER/$SKILL_NAME/g" "$TARGET_DIR/scripts/helper.sh"
chmod +x "$TARGET_DIR/scripts/helper.sh"
echo -e "${GREEN} ✓ Created scripts/ directory${NC}"
fi
if [[ "$WITH_REFS" == true ]]; then
mkdir -p "$TARGET_DIR/references"
# Create example reference
cat > "$TARGET_DIR/references/detailed-guide.md" << 'REF_EXAMPLE'
# Detailed Guide for SKILL_NAME_PLACEHOLDER
This file contains detailed documentation that can be referenced on-demand.
## Advanced Usage
Detailed instructions go here...
## Configuration
Configuration options and examples...
## Troubleshooting
Common issues and solutions...
REF_EXAMPLE
sed -i "s/SKILL_NAME_PLACEHOLDER/$SKILL_NAME/g" "$TARGET_DIR/references/detailed-guide.md"
echo -e "${GREEN} ✓ Created references/ directory${NC}"
fi
if [[ "$WITH_ASSETS" == true ]]; then
mkdir -p "$TARGET_DIR/assets"
# Create example asset
cat > "$TARGET_DIR/assets/template.txt" << 'ASSET_EXAMPLE'
# Template file for SKILL_NAME_PLACEHOLDER
This is a template file that can be used as a starting point.
Modify it according to your needs.
ASSET_EXAMPLE
sed -i "s/SKILL_NAME_PLACEHOLDER/$SKILL_NAME/g" "$TARGET_DIR/assets/template.txt"
echo -e "${GREEN} ✓ Created assets/ directory${NC}"
fi
if [[ "$WITH_TESTS" == true ]]; then
mkdir -p "$TARGET_DIR/evals"
# Create template evals.json
cat > "$TARGET_DIR/evals/evals.json" << 'EVALS_TEMPLATE'
{
"skill_name": "SKILL_NAME_PLACEHOLDER",
"evals": [
{
"id": 1,
"name": "common-case",
"prompt": "Typical user request with realistic context, file paths, and specific details. This represents the most common way users will ask for help.",
"expected_output": "Description of what the skill should produce for this request",
"assertions": [
"Check that output contains specific expected content",
"Verify file is created at expected location (if applicable)"
]
},
{
"id": 2,
"name": "edge-case",
"prompt": "Unusual or tricky scenario that tests edge cases, error handling, or complex requirements. Include something that might break the skill.",
"expected_output": "Description of expected behavior for this edge case",
"assertions": [
"Verify edge case is handled appropriately",
"Check for graceful error handling if applicable"
]
},
{
"id": 3,
"name": "varied-phrasing",
"prompt": "Same intent as the common case but expressed with different words, casual language, or alternative phrasing. Tests skill robustness to language variation.",
"expected_output": "Same expected output as common case",
"assertions": [
"Output should match common case results",
"Skill triggers correctly with different phrasing"
]
}
]
}
EVALS_TEMPLATE
sed -i "s/SKILL_NAME_PLACEHOLDER/$SKILL_NAME/g" "$TARGET_DIR/evals/evals.json"
echo -e "${GREEN} ✓ Created evals/ directory with template evals.json${NC}"
fi
echo ""
echo -e "${GREEN}✓ Skill '$SKILL_NAME' created successfully!${NC}"
echo ""
echo "Next steps:"
echo " 1. Edit $TARGET_DIR/SKILL.md"
echo " 2. Fill in the description with specific trigger phrases"
echo " 3. Add your skill content"
if [[ "$WITH_REFS" == true ]]; then
echo " 4. Add detailed content to references/ files"
fi
if [[ "$WITH_SCRIPTS" == true ]]; then
echo " 5. Implement scripts in scripts/ directory"
fi
if [[ "$WITH_TESTS" == true ]]; then
echo " 6. Customize test cases in evals/evals.json"
echo " 7. Run tests: ${SKILL_BUILDER_DIR}/scripts/run-tests.sh $TARGET_DIR"
fi
echo ""
echo "Validate your skill:"
echo " ${SKILL_BUILDER_DIR}/scripts/validate-skill.sh $TARGET_DIR"

325
.config/opencode/skills/.skill-builder.disabled/scripts/run-tests.sh Executable file
View File

@@ -0,0 +1,325 @@
#!/bin/bash
#
# run-tests.sh - Execute test workflow and capture results
#
# Usage: ./run-tests.sh <path/to/skill-directory>
#
# This script guides you through testing each test case manually and records results.
#
set -euo pipefail
# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
CYAN='\033[0;36m'
NC='\033[0m' # No Color
# Parse arguments
SKILL_DIR=""
usage() {
echo "Usage: $0 <path/to/skill-directory>"
echo ""
echo "Examples:"
echo " $0 ~/.config/opencode/skills/my-skill"
echo " $0 ./my-skill"
exit 1
}
# Parse command line arguments
while [[ $# -gt 0 ]]; do
case $1 in
-h|--help)
usage
;;
-*)
echo -e "${RED}Error: Unknown option $1${NC}"
usage
;;
*)
if [[ -z "$SKILL_DIR" ]]; then
SKILL_DIR="$1"
else
echo -e "${RED}Error: Multiple skill directories provided${NC}"
usage
fi
shift
;;
esac
done
# Validate skill directory
if [[ -z "$SKILL_DIR" ]]; then
echo -e "${RED}Error: Skill directory is required${NC}"
usage
fi
# Resolve path
SKILL_DIR="$(cd "$SKILL_DIR" 2>/dev/null && pwd)" || {
echo -e "${RED}Error: Cannot access directory: $SKILL_DIR${NC}"
exit 1
}
# Get skill name from directory
SKILL_NAME="$(basename "$SKILL_DIR")"
# Verify evals.json exists
if [[ ! -f "$SKILL_DIR/evals/evals.json" ]]; then
echo -e "${RED}Error: evals/evals.json not found${NC}"
echo ""
echo "Create test cases first:"
echo " ~/.config/opencode/skills/skill-builder/scripts/create-tests.sh $SKILL_DIR"
exit 1
fi
echo "========================================"
echo "Running Tests for: $SKILL_NAME"
echo "========================================"
echo ""
# Check if jq is available
if ! command -v jq &> /dev/null; then
echo -e "${YELLOW}⚠ jq is not installed${NC}"
echo " Install jq for better JSON handling:"
echo " Ubuntu/Debian: sudo apt-get install jq"
echo " macOS: brew install jq"
echo ""
echo -e "${YELLOW}Falling back to basic parsing...${NC}"
USE_JQ=false
else
USE_JQ=true
fi
# Initialize results array
RESULTS=()
TEST_COUNT=0
PASSED=0
FAILED=0
SKIPPED=0
# Function to extract value from JSON using basic parsing
get_json_value() {
local file="$1"
local key="$2"
local index="${3:-}"
if [[ "$USE_JQ" == true ]]; then
if [[ -n "$index" ]]; then
jq -r ".evals[$index].$key" "$file" 2>/dev/null || echo ""
else
jq -r ".$key" "$file" 2>/dev/null || echo ""
fi
else
# Basic grep-based extraction (fallback)
if [[ -n "$index" ]]; then
# This is a simplified fallback - won't handle nested structures well
grep -A 100 '"evals":' "$file" | grep -A 20 "\"id\": $index" | grep "\"$key\":" | head -1 | sed 's/.*"'$key'": "\(.*\)".*/\1/' | sed 's/",*$//'
else
grep "\"$key\":" "$file" | head -1 | sed 's/.*"'$key'": "\(.*\)".*/\1/' | sed 's/",*$//'
fi
fi
}
# Count test cases
if [[ "$USE_JQ" == true ]]; then
TEST_COUNT=$(jq '.evals | length' "$SKILL_DIR/evals/evals.json")
else
TEST_COUNT=$(grep -c '"id":' "$SKILL_DIR/evals/evals.json" 2>/dev/null || echo "0")
fi
if [[ "$TEST_COUNT" -eq 0 ]]; then
echo -e "${RED}Error: No test cases found in evals.json${NC}"
exit 1
fi
echo "Found $TEST_COUNT test case(s)"
echo ""
# Process each test case
for ((i=0; i<TEST_COUNT; i++)); do
echo "========================================"
echo -e "${CYAN}Test Case $((i+1)) of $TEST_COUNT${NC}"
echo "========================================"
echo ""
# Extract test details
if [[ "$USE_JQ" == true ]]; then
TEST_ID=$(jq -r ".evals[$i].id" "$SKILL_DIR/evals/evals.json")
TEST_NAME=$(jq -r ".evals[$i].name" "$SKILL_DIR/evals/evals.json")
TEST_PROMPT=$(jq -r ".evals[$i].prompt" "$SKILL_DIR/evals/evals.json")
TEST_EXPECTED=$(jq -r ".evals[$i].expected_output" "$SKILL_DIR/evals/evals.json")
TEST_TYPE=$(jq -r ".evals[$i].type // .evals[$i].name" "$SKILL_DIR/evals/evals.json")
else
# Fallback parsing
TEST_ID=$((i+1))
TEST_NAME="test-$((i+1))"
TEST_PROMPT="[Prompt extraction requires jq - install jq for full functionality]"
TEST_EXPECTED="[Expected output extraction requires jq]"
TEST_TYPE="unknown"
fi
echo -e "${BLUE}Test Name:${NC} $TEST_NAME"
echo -e "${BLUE}Type:${NC} $TEST_TYPE"
echo ""
echo -e "${BLUE}Prompt:${NC}"
echo "----------------------------------------"
echo "$TEST_PROMPT"
echo "----------------------------------------"
echo ""
echo -e "${BLUE}Expected Output:${NC}"
echo "$TEST_EXPECTED"
echo ""
# Instructions for manual testing
echo -e "${YELLOW}Instructions:${NC}"
echo "1. Copy the prompt above"
echo "2. Open a new opencode session"
echo "3. Paste the prompt and observe the result"
echo "4. Return here to record the outcome"
echo ""
read -p "Press Enter when ready to record results..."
echo ""
# Get test result
echo "Test Result:"
echo " [p] Pass - Output met expectations"
echo " [f] Fail - Output did not meet expectations"
echo " [s] Skip - Could not test or not applicable"
echo ""
while true; do
read -p "Result (p/f/s): " -n 1 -r
echo
case $REPLY in
[Pp])
TEST_RESULT="pass"
((PASSED++))
break
;;
[Ff])
TEST_RESULT="fail"
((FAILED++))
break
;;
[Ss])
TEST_RESULT="skip"
((SKIPPED++))
break
;;
*)
echo "Please enter p, f, or s"
;;
esac
done
echo ""
# Get notes
echo -e "${BLUE}Notes (optional):${NC}"
echo "Describe any issues, observations, or suggestions:"
read -r TEST_NOTES
# Get timestamp
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
# Build result entry
RESULT_ENTRY=$(cat << EOF
{
"test_id": $TEST_ID,
"test_name": "$TEST_NAME",
"result": "$TEST_RESULT",
"notes": "$TEST_NOTES",
"timestamp": "$TIMESTAMP"
}
EOF
)
RESULTS+=("$RESULT_ENTRY")
echo ""
echo -e "${GREEN}✓ Recorded test result${NC}"
echo ""
# Ask to continue or stop
if [[ $i -lt $((TEST_COUNT-1)) ]]; then
read -p "Continue to next test? (Y/n): " -n 1 -r
echo
if [[ $REPLY =~ ^[Nn]$ ]]; then
echo "Stopping test run..."
break
fi
echo ""
fi
done
# Generate test-results.json
echo "========================================"
echo "Generating Test Results"
echo "========================================"
echo ""
# Create results JSON
RUN_TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
# Build JSON array from results
RESULTS_JSON="["
for i in "${!RESULTS[@]}"; do
if [[ $i -gt 0 ]]; then
RESULTS_JSON+=","
fi
RESULTS_JSON+="${RESULTS[$i]}"
done
RESULTS_JSON+="]"
cat > "$SKILL_DIR/evals/test-results.json" << EOF
{
"skill_name": "$SKILL_NAME",
"run_timestamp": "$RUN_TIMESTAMP",
"summary": {
"total": $((${#RESULTS[@]})),
"passed": $PASSED,
"failed": $FAILED,
"skipped": $SKIPPED
},
"results": $RESULTS_JSON
}
EOF
echo -e "${GREEN}✓ Saved results to evals/test-results.json${NC}"
echo ""
# Display summary
echo "========================================"
echo "Test Run Summary"
echo "========================================"
echo ""
echo "Total Tests: $((${#RESULTS[@]}))"
echo -e "${GREEN}Passed: $PASSED${NC}"
echo -e "${RED}Failed: $FAILED${NC}"
echo -e "${YELLOW}Skipped: $SKIPPED${NC}"
echo ""
# Next steps
if [[ $FAILED -gt 0 ]]; then
echo "========================================"
echo -e "${YELLOW}Next Steps:${NC}"
echo "========================================"
echo ""
echo "Some tests failed. To improve your skill:"
echo ""
echo "1. Review test-results.json for details"
echo "2. Update SKILL.md to address issues"
echo "3. Run tests again:"
echo " $0 $SKILL_DIR"
echo ""
echo "For detailed grading:"
echo " ~/.config/opencode/skills/skill-builder/scripts/grade-output.sh $SKILL_DIR"
echo ""
fi
echo -e "${GREEN}Done!${NC}"

308
.config/opencode/skills/.skill-builder.disabled/scripts/validate-skill.sh Executable file
View File

@@ -0,0 +1,308 @@
#!/bin/bash
#
# validate-skill.sh - Strictly validate a skill's structure and content
#
# Usage: ./validate-skill.sh <path/to/skill-directory> [options]
#
# Options:
# --strict Fail on warnings (default)
# --lenient Only fail on errors, report warnings
# --verbose Show detailed output
#
set -euo pipefail
# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color
# Validation counters
ERRORS=0
WARNINGS=0
# Default mode
STRICT=true
VERBOSE=false
usage() {
echo "Usage: $0 <path/to/skill-directory> [options]"
echo ""
echo "Options:"
echo " --strict Fail on warnings (default)"
echo " --lenient Only fail on errors"
echo " --verbose Show detailed output"
echo ""
echo "Examples:"
echo " $0 ~/.config/opencode/skills/my-skill"
echo " $0 ./my-skill --verbose"
exit 1
}
# Error and warning functions
error() {
echo -e "${RED}✗ ERROR:${NC} $1"
((ERRORS++)) || true
}
warn() {
if [[ "$STRICT" == true ]]; then
echo -e "${YELLOW}✗ WARNING (treated as error in strict mode):${NC} $1"
((ERRORS++)) || true
else
echo -e "${YELLOW}⚠ WARNING:${NC} $1"
((WARNINGS++)) || true
fi
}
info() {
if [[ "$VERBOSE" == true ]]; then
echo -e "${BLUE}ℹ${NC} $1"
fi
}
success() {
echo -e "${GREEN}✓${NC} $1"
}
# Parse arguments
SKILL_DIR=""
while [[ $# -gt 0 ]]; do
case $1 in
--strict)
STRICT=true
shift
;;
--lenient)
STRICT=false
shift
;;
--verbose)
VERBOSE=true
shift
;;
-h|--help)
usage
;;
-*)
echo -e "${RED}Error: Unknown option $1${NC}"
usage
;;
*)
if [[ -z "$SKILL_DIR" ]]; then
SKILL_DIR="$1"
else
echo -e "${RED}Error: Multiple skill directories provided${NC}"
usage
fi
shift
;;
esac
done
# Validate skill directory argument
if [[ -z "$SKILL_DIR" ]]; then
echo -e "${RED}Error: Skill directory is required${NC}"
usage
fi
# Resolve path
SKILL_DIR="$(cd "$SKILL_DIR" 2>/dev/null && pwd)" || {
echo -e "${RED}Error: Cannot access directory: $SKILL_DIR${NC}"
exit 1
}
# Get skill name from directory
SKILL_NAME="$(basename "$SKILL_DIR")"
echo "========================================"
echo "Validating skill: $SKILL_NAME"
echo "Directory: $SKILL_DIR"
echo "========================================"
echo ""
# Check 1: Directory exists
if [[ ! -d "$SKILL_DIR" ]]; then
error "Directory does not exist: $SKILL_DIR"
exit 1
fi
success "Directory exists"
# Check 2: SKILL.md exists
SKILL_MD="$SKILL_DIR/SKILL.md"
if [[ ! -f "$SKILL_MD" ]]; then
error "SKILL.md file not found in $SKILL_DIR"
error "Skill must contain a SKILL.md file"
exit 1
fi
success "SKILL.md file exists"
# Check 3: SKILL.md starts with YAML frontmatter
if ! head -1 "$SKILL_MD" | grep -q '^---\s*$'; then
error "SKILL.md must start with YAML frontmatter (---)"
else
success "SKILL.md starts with YAML frontmatter"
fi
# Extract frontmatter content
FRONTMATTER=$(sed -n '/^---$/,/^---$/p' "$SKILL_MD" | head -n -1 | tail -n +2)
info "Extracted frontmatter"
# Check 4: Name field exists and is valid
if ! echo "$FRONTMATTER" | grep -q '^name:'; then
error "Frontmatter missing required field: 'name'"
else
FM_NAME=$(echo "$FRONTMATTER" | grep '^name:' | sed 's/^name:\s*//' | tr -d '"' | tr -d "'")
if [[ -z "$FM_NAME" ]]; then
error "'name' field is empty"
elif [[ ! "$FM_NAME" =~ ^[a-z0-9-]+$ ]]; then
error "'name' must be lowercase alphanumeric with hyphens: '$FM_NAME'"
elif [[ "$FM_NAME" != "$SKILL_NAME" ]]; then
error "'name' ($FM_NAME) does not match directory name ($SKILL_NAME)"
else
success "'name' field is valid: $FM_NAME"
fi
fi
# Check 5: Description field exists and is valid
if ! echo "$FRONTMATTER" | grep -q '^description:'; then
error "Frontmatter missing required field: 'description'"
else
FM_DESC=$(echo "$FRONTMATTER" | sed -n '/^description:/,/^\S/{/^description:/p;/^\S/q}' | sed 's/^description:\s*//' | tr -d '"' | tr -d "'" | sed ':a;N;$!ba;s/\n/ /g')
DESC_LEN=${#FM_DESC}
if [[ -z "$FM_DESC" ]]; then
error "'description' field is empty"
elif [[ $DESC_LEN -lt 20 ]]; then
error "'description' must be at least 20 characters (found $DESC_LEN)"
elif [[ $DESC_LEN -gt 1024 ]]; then
error "'description' must be at most 1024 characters (found $DESC_LEN)"
else
success "'description' field length is valid ($DESC_LEN chars)"
fi
# Check for common description issues
if echo "$FM_DESC" | grep -qi '^use this skill'; then
warn "Description uses second person ('Use this skill'). Use third person: 'This skill should be used when...'"
fi
if echo "$FM_DESC" | grep -qi '^this skill provides\|^this skill helps'; then
warn "Description is vague. Include specific trigger phrases users would say"
fi
# Check for quoted phrases (allow either single or double quotes in original)
if ! echo "$FRONTMATTER" | grep -A 5 '^description:' | grep -q '"\|\"'; then
warn "Description should include specific trigger phrases in quotes, e.g.: \"create X\", \"configure Y\""
fi
fi
# Check 6: No unknown frontmatter fields (informational)
KNOWN_FIELDS="^name:\|^description:\|^license:\|^compatibility:\|^metadata:\|^allowed-tools:"
UNKNOWN_FIELDS=$(echo "$FRONTMATTER" | grep -v '^\s*$' | grep -v "$KNOWN_FIELDS" || true)
if [[ -n "$UNKNOWN_FIELDS" ]]; then
info "Unknown frontmatter fields (will be ignored):"
echo "$UNKNOWN_FIELDS" | sed 's/^/ /'
fi
# Check 7: YAML syntax is valid
if ! echo "$FRONTMATTER" | python3 -c "import yaml, sys; yaml.safe_load(sys.stdin)" 2>/dev/null; then
# Fallback: check with basic pattern matching
if echo "$FRONTMATTER" | grep -q '^\s*:\s*$'; then
error "Invalid YAML syntax: empty key found"
fi
# Count lines with colons to detect malformed entries
MALFORMED=$(echo "$FRONTMATTER" | grep -c '^\s*[^:]*:\s*$' || true)
if [[ $MALFORMED -gt 0 ]]; then
error "Potential YAML syntax issues detected"
fi
else
success "YAML frontmatter syntax appears valid"
fi
# Check 8: SKILL.md has content after frontmatter
# Remove everything from line 1 through the second occurrence of ---
BODY_CONTENT=$(sed '0,/^---$/d;0,/^---$/d' "$SKILL_MD")
if [[ -z "$(echo "$BODY_CONTENT" | tr -d '[:space:]')" ]]; then
error "SKILL.md has no content after frontmatter"
else
success "SKILL.md has body content"
fi
# Check 9: Check for common writing style issues in body
if echo "$BODY_CONTENT" | grep -qE '^You (should|need|can|must)'; then
warn "Body uses second person ('You should...'). Prefer imperative form: 'Do this...'"
fi
if echo "$BODY_CONTENT" | grep -q '^When to Use This Skill'; then
warn "'When to Use This Skill' section in body is redundant. Include triggers in description field instead"
fi
# Check 10: Verify referenced files exist
if [[ -d "$SKILL_DIR/references" ]]; then
REF_COUNT=$(find "$SKILL_DIR/references" -type f | wc -l)
success "References directory exists with $REF_COUNT file(s)"
# Check if references are mentioned in SKILL.md
for ref_file in "$SKILL_DIR/references"/*; do
if [[ -f "$ref_file" ]]; then
ref_name=$(basename "$ref_file")
if ! grep -q "$ref_name" "$SKILL_MD"; then
warn "Reference file '$ref_name' is not mentioned in SKILL.md"
fi
fi
done
fi
if [[ -d "$SKILL_DIR/scripts" ]]; then
SCRIPT_COUNT=$(find "$SKILL_DIR/scripts" -type f | wc -l)
success "Scripts directory exists with $SCRIPT_COUNT file(s)"
# Check scripts are executable
for script in "$SKILL_DIR/scripts"/*; do
if [[ -f "$script" ]] && [[ ! -x "$script" ]]; then
warn "Script '$(basename "$script")' is not executable (run: chmod +x)"
fi
done
fi
if [[ -d "$SKILL_DIR/assets" ]]; then
ASSET_COUNT=$(find "$SKILL_DIR/assets" -type f | wc -l)
success "Assets directory exists with $ASSET_COUNT file(s)"
fi
# Check 11: File organization
if [[ -f "$SKILL_DIR/README.md" ]]; then
warn "README.md found. Skills should not include README.md files"
fi
if [[ -f "$SKILL_DIR/CHANGELOG.md" ]]; then
warn "CHANGELOG.md found. Skills should not include auxiliary documentation"
fi
echo ""
echo "========================================"
# Final report
if [[ $ERRORS -eq 0 ]]; then
echo -e "${GREEN}✓ VALIDATION PASSED${NC}"
if [[ $WARNINGS -gt 0 ]]; then
echo -e "${YELLOW} $WARNINGS warning(s) (not treated as errors)${NC}"
fi
echo ""
echo "Your skill is ready to use!"
exit 0
else
echo -e "${RED}✗ VALIDATION FAILED${NC}"
echo -e "${RED} $ERRORS error(s) found${NC}"
if [[ $WARNINGS -gt 0 ]]; then
echo -e "${YELLOW} $WARNINGS warning(s)${NC}"
fi
echo ""
echo "Fix the errors above and run validation again."
exit 1
fi

682
.config/opencode/skills/agent-browser.disabled/SKILL.md.disabled Normal file
View File

@@ -0,0 +1,682 @@
---
name: agent-browser
description: Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction.
allowed-tools: Bash(npx agent-browser:*), Bash(agent-browser:*)
---
# Browser Automation with agent-browser
The CLI uses Chrome/Chromium via CDP directly. Install via `npm i -g agent-browser`, `brew install agent-browser`, or `cargo install agent-browser`. Run `agent-browser install` to download Chrome. Run `agent-browser upgrade` to update to the latest version.
## Core Workflow
Every browser automation follows this pattern:
1. **Navigate**: `agent-browser open <url>`
2. **Snapshot**: `agent-browser snapshot -i` (get element refs like `@e1`, `@e2`)
3. **Interact**: Use refs to click, fill, select
4. **Re-snapshot**: After navigation or DOM changes, get fresh refs
```bash
agent-browser open https://example.com/form
agent-browser snapshot -i
# Output: @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Submit"
agent-browser fill @e1 "user@example.com"
agent-browser fill @e2 "password123"
agent-browser click @e3
agent-browser wait --load networkidle
agent-browser snapshot -i # Check result
```
## Command Chaining
Commands can be chained with `&&` in a single shell invocation. The browser persists between commands via a background daemon, so chaining is safe and more efficient than separate calls.
```bash
# Chain open + wait + snapshot in one call
agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser snapshot -i
# Chain multiple interactions
agent-browser fill @e1 "user@example.com" && agent-browser fill @e2 "password123" && agent-browser click @e3
# Navigate and capture
agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser screenshot page.png
```
**When to chain:** Use `&&` when you don't need to read the output of an intermediate command before proceeding (e.g., open + wait + screenshot). Run commands separately when you need to parse the output first (e.g., snapshot to discover refs, then interact using those refs).
## Handling Authentication
When automating a site that requires login, choose the approach that fits:
**Option 1: Import auth from the user's browser (fastest for one-off tasks)**
```bash
# Connect to the user's running Chrome (they're already logged in)
agent-browser --auto-connect state save ./auth.json
# Use that auth state
agent-browser --state ./auth.json open https://app.example.com/dashboard
```
State files contain session tokens in plaintext -- add to `.gitignore` and delete when no longer needed. Set `AGENT_BROWSER_ENCRYPTION_KEY` for encryption at rest.
**Option 2: Persistent profile (simplest for recurring tasks)**
```bash
# First run: login manually or via automation
agent-browser --profile ~/.myapp open https://app.example.com/login
# ... fill credentials, submit ...
# All future runs: already authenticated
agent-browser --profile ~/.myapp open https://app.example.com/dashboard
```
**Option 3: Session name (auto-save/restore cookies + localStorage)**
```bash
agent-browser --session-name myapp open https://app.example.com/login
# ... login flow ...
agent-browser close # State auto-saved
# Next time: state auto-restored
agent-browser --session-name myapp open https://app.example.com/dashboard
```
**Option 4: Auth vault (credentials stored encrypted, login by name)**
```bash
echo "$PASSWORD" | agent-browser auth save myapp --url https://app.example.com/login --username user --password-stdin
agent-browser auth login myapp
```
**Option 5: State file (manual save/load)**
```bash
# After logging in:
agent-browser state save ./auth.json
# In a future session:
agent-browser state load ./auth.json
agent-browser open https://app.example.com/dashboard
```
See [references/authentication.md](references/authentication.md) for OAuth, 2FA, cookie-based auth, and token refresh patterns.
## Essential Commands
```bash
# Navigation
agent-browser open <url> # Navigate (aliases: goto, navigate)
agent-browser close # Close browser
# Snapshot
agent-browser snapshot -i # Interactive elements with refs (recommended)
agent-browser snapshot -i -C # Include cursor-interactive elements (divs with onclick, cursor:pointer)
agent-browser snapshot -s "#selector" # Scope to CSS selector
# Interaction (use @refs from snapshot)
agent-browser click @e1 # Click element
agent-browser click @e1 --new-tab # Click and open in new tab
agent-browser fill @e2 "text" # Clear and type text
agent-browser type @e2 "text" # Type without clearing
agent-browser select @e1 "option" # Select dropdown option
agent-browser check @e1 # Check checkbox
agent-browser press Enter # Press key
agent-browser keyboard type "text" # Type at current focus (no selector)
agent-browser keyboard inserttext "text" # Insert without key events
agent-browser scroll down 500 # Scroll page
agent-browser scroll down 500 --selector "div.content" # Scroll within a specific container
# Get information
agent-browser get text @e1 # Get element text
agent-browser get url # Get current URL
agent-browser get title # Get page title
agent-browser get cdp-url # Get CDP WebSocket URL
# Wait
agent-browser wait @e1 # Wait for element
agent-browser wait --load networkidle # Wait for network idle
agent-browser wait --url "**/page" # Wait for URL pattern
agent-browser wait 2000 # Wait milliseconds
agent-browser wait --text "Welcome" # Wait for text to appear (substring match)
agent-browser wait --fn "!document.body.innerText.includes('Loading...')" # Wait for text to disappear
agent-browser wait "#spinner" --state hidden # Wait for element to disappear
# Downloads
agent-browser download @e1 ./file.pdf # Click element to trigger download
agent-browser wait --download ./output.zip # Wait for any download to complete
agent-browser --download-path ./downloads open <url> # Set default download directory
# Network
agent-browser network requests # Inspect tracked requests
agent-browser network route "**/api/*" --abort # Block matching requests
agent-browser network har start # Start HAR recording
agent-browser network har stop ./capture.har # Stop and save HAR file
# Viewport & Device Emulation
agent-browser set viewport 1920 1080 # Set viewport size (default: 1280x720)
agent-browser set viewport 1920 1080 2 # 2x retina (same CSS size, higher res screenshots)
agent-browser set device "iPhone 14" # Emulate device (viewport + user agent)
# Capture
agent-browser screenshot # Screenshot to temp dir
agent-browser screenshot --full # Full page screenshot
agent-browser screenshot --annotate # Annotated screenshot with numbered element labels
agent-browser screenshot --screenshot-dir ./shots # Save to custom directory
agent-browser screenshot --screenshot-format jpeg --screenshot-quality 80
agent-browser pdf output.pdf # Save as PDF
# Clipboard
agent-browser clipboard read # Read text from clipboard
agent-browser clipboard write "Hello, World!" # Write text to clipboard
agent-browser clipboard copy # Copy current selection
agent-browser clipboard paste # Paste from clipboard
# Diff (compare page states)
agent-browser diff snapshot # Compare current vs last snapshot
agent-browser diff snapshot --baseline before.txt # Compare current vs saved file
agent-browser diff screenshot --baseline before.png # Visual pixel diff
agent-browser diff url <url1> <url2> # Compare two pages
agent-browser diff url <url1> <url2> --wait-until networkidle # Custom wait strategy
agent-browser diff url <url1> <url2> --selector "#main" # Scope to element
```
## Batch Execution
Execute multiple commands in a single invocation by piping a JSON array of string arrays to `batch`. This avoids per-command process startup overhead when running multi-step workflows.
```bash
echo '[
["open", "https://example.com"],
["snapshot", "-i"],
["click", "@e1"],
["screenshot", "result.png"]
]' | agent-browser batch --json
# Stop on first error
agent-browser batch --bail < commands.json
```
Use `batch` when you have a known sequence of commands that don't depend on intermediate output. Use separate commands or `&&` chaining when you need to parse output between steps (e.g., snapshot to discover refs, then interact).
## Common Patterns
### Form Submission
```bash
agent-browser open https://example.com/signup
agent-browser snapshot -i
agent-browser fill @e1 "Jane Doe"
agent-browser fill @e2 "jane@example.com"
agent-browser select @e3 "California"
agent-browser check @e4
agent-browser click @e5
agent-browser wait --load networkidle
```
### Authentication with Auth Vault (Recommended)
```bash
# Save credentials once (encrypted with AGENT_BROWSER_ENCRYPTION_KEY)
# Recommended: pipe password via stdin to avoid shell history exposure
echo "pass" | agent-browser auth save github --url https://github.com/login --username user --password-stdin
# Login using saved profile (LLM never sees password)
agent-browser auth login github
# List/show/delete profiles
agent-browser auth list
agent-browser auth show github
agent-browser auth delete github
```
### Authentication with State Persistence
```bash
# Login once and save state
agent-browser open https://app.example.com/login
agent-browser snapshot -i
agent-browser fill @e1 "$USERNAME"
agent-browser fill @e2 "$PASSWORD"
agent-browser click @e3
agent-browser wait --url "**/dashboard"
agent-browser state save auth.json
# Reuse in future sessions
agent-browser state load auth.json
agent-browser open https://app.example.com/dashboard
```
### Session Persistence
```bash
# Auto-save/restore cookies and localStorage across browser restarts
agent-browser --session-name myapp open https://app.example.com/login
# ... login flow ...
agent-browser close # State auto-saved to ~/.agent-browser/sessions/
# Next time, state is auto-loaded
agent-browser --session-name myapp open https://app.example.com/dashboard
# Encrypt state at rest
export AGENT_BROWSER_ENCRYPTION_KEY=$(openssl rand -hex 32)
agent-browser --session-name secure open https://app.example.com
# Manage saved states
agent-browser state list
agent-browser state show myapp-default.json
agent-browser state clear myapp
agent-browser state clean --older-than 7
```
### Working with Iframes
Iframe content is automatically inlined in snapshots. Refs inside iframes carry frame context, so you can interact with them directly.
```bash
agent-browser open https://example.com/checkout
agent-browser snapshot -i
# @e1 [heading] "Checkout"
# @e2 [Iframe] "payment-frame"
# @e3 [input] "Card number"
# @e4 [input] "Expiry"
# @e5 [button] "Pay"
# Interact directly — no frame switch needed
agent-browser fill @e3 "4111111111111111"
agent-browser fill @e4 "12/28"
agent-browser click @e5
# To scope a snapshot to one iframe:
agent-browser frame @e2
agent-browser snapshot -i # Only iframe content
agent-browser frame main # Return to main frame
```
### Data Extraction
```bash
agent-browser open https://example.com/products
agent-browser snapshot -i
agent-browser get text @e5 # Get specific element text
agent-browser get text body > page.txt # Get all page text
# JSON output for parsing
agent-browser snapshot -i --json
agent-browser get text @e1 --json
```
### Parallel Sessions
```bash
agent-browser --session site1 open https://site-a.com
agent-browser --session site2 open https://site-b.com
agent-browser --session site1 snapshot -i
agent-browser --session site2 snapshot -i
agent-browser session list
```
### Connect to Existing Chrome
```bash
# Auto-discover running Chrome with remote debugging enabled
agent-browser --auto-connect open https://example.com
agent-browser --auto-connect snapshot
# Or with explicit CDP port
agent-browser --cdp 9222 snapshot
```
Auto-connect discovers Chrome via `DevToolsActivePort`, common debugging ports (9222, 9229), and falls back to a direct WebSocket connection if HTTP-based CDP discovery fails.
### Color Scheme (Dark Mode)
```bash
# Persistent dark mode via flag (applies to all pages and new tabs)
agent-browser --color-scheme dark open https://example.com
# Or via environment variable
AGENT_BROWSER_COLOR_SCHEME=dark agent-browser open https://example.com
# Or set during session (persists for subsequent commands)
agent-browser set media dark
```
### Viewport & Responsive Testing
```bash
# Set a custom viewport size (default is 1280x720)
agent-browser set viewport 1920 1080
agent-browser screenshot desktop.png
# Test mobile-width layout
agent-browser set viewport 375 812
agent-browser screenshot mobile.png
# Retina/HiDPI: same CSS layout at 2x pixel density
# Screenshots stay at logical viewport size, but content renders at higher DPI
agent-browser set viewport 1920 1080 2
agent-browser screenshot retina.png
# Device emulation (sets viewport + user agent in one step)
agent-browser set device "iPhone 14"
agent-browser screenshot device.png
```
The `scale` parameter (3rd argument) sets `window.devicePixelRatio` without changing CSS layout. Use it when testing retina rendering or capturing higher-resolution screenshots.
### Visual Browser (Debugging)
```bash
agent-browser --headed open https://example.com
agent-browser highlight @e1 # Highlight element
agent-browser inspect # Open Chrome DevTools for the active page
agent-browser record start demo.webm # Record session
agent-browser profiler start # Start Chrome DevTools profiling
agent-browser profiler stop trace.json # Stop and save profile (path optional)
```
Use `AGENT_BROWSER_HEADED=1` to enable headed mode via environment variable. Browser extensions work in both headed and headless mode.
### Local Files (PDFs, HTML)
```bash
# Open local files with file:// URLs
agent-browser --allow-file-access open file:///path/to/document.pdf
agent-browser --allow-file-access open file:///path/to/page.html
agent-browser screenshot output.png
```
### iOS Simulator (Mobile Safari)
```bash
# List available iOS simulators
agent-browser device list
# Launch Safari on a specific device
agent-browser -p ios --device "iPhone 16 Pro" open https://example.com
# Same workflow as desktop - snapshot, interact, re-snapshot
agent-browser -p ios snapshot -i
agent-browser -p ios tap @e1 # Tap (alias for click)
agent-browser -p ios fill @e2 "text"
agent-browser -p ios swipe up # Mobile-specific gesture
# Take screenshot
agent-browser -p ios screenshot mobile.png
# Close session (shuts down simulator)
agent-browser -p ios close
```
**Requirements:** macOS with Xcode, Appium (`npm install -g appium && appium driver install xcuitest`)
**Real devices:** Works with physical iOS devices if pre-configured. Use `--device "<UDID>"` where UDID is from `xcrun xctrace list devices`.
## Security
All security features are opt-in. By default, agent-browser imposes no restrictions on navigation, actions, or output.
### Content Boundaries (Recommended for AI Agents)
Enable `--content-boundaries` to wrap page-sourced output in markers that help LLMs distinguish tool output from untrusted page content:
```bash
export AGENT_BROWSER_CONTENT_BOUNDARIES=1
agent-browser snapshot
# Output:
# --- AGENT_BROWSER_PAGE_CONTENT nonce=<hex> origin=https://example.com ---
# [accessibility tree]
# --- END_AGENT_BROWSER_PAGE_CONTENT nonce=<hex> ---
```
### Domain Allowlist
Restrict navigation to trusted domains. Wildcards like `*.example.com` also match the bare domain `example.com`. Sub-resource requests, WebSocket, and EventSource connections to non-allowed domains are also blocked. Include CDN domains your target pages depend on:
```bash
export AGENT_BROWSER_ALLOWED_DOMAINS="example.com,*.example.com"
agent-browser open https://example.com # OK
agent-browser open https://malicious.com # Blocked
```
### Action Policy
Use a policy file to gate destructive actions:
```bash
export AGENT_BROWSER_ACTION_POLICY=./policy.json
```
Example `policy.json`:
```json
{ "default": "deny", "allow": ["navigate", "snapshot", "click", "scroll", "wait", "get"] }
```
Auth vault operations (`auth login`, etc.) bypass action policy but domain allowlist still applies.
### Output Limits
Prevent context flooding from large pages:
```bash
export AGENT_BROWSER_MAX_OUTPUT=50000
```
## Diffing (Verifying Changes)
Use `diff snapshot` after performing an action to verify it had the intended effect. This compares the current accessibility tree against the last snapshot taken in the session.
```bash
# Typical workflow: snapshot -> action -> diff
agent-browser snapshot -i # Take baseline snapshot
agent-browser click @e2 # Perform action
agent-browser diff snapshot # See what changed (auto-compares to last snapshot)
```
For visual regression testing or monitoring:
```bash
# Save a baseline screenshot, then compare later
agent-browser screenshot baseline.png
# ... time passes or changes are made ...
agent-browser diff screenshot --baseline baseline.png
# Compare staging vs production
agent-browser diff url https://staging.example.com https://prod.example.com --screenshot
```
`diff snapshot` output uses `+` for additions and `-` for removals, similar to git diff. `diff screenshot` produces a diff image with changed pixels highlighted in red, plus a mismatch percentage.
## Timeouts and Slow Pages
The default timeout is 25 seconds. This can be overridden with the `AGENT_BROWSER_DEFAULT_TIMEOUT` environment variable (value in milliseconds). For slow websites or large pages, use explicit waits instead of relying on the default timeout:
```bash
# Wait for network activity to settle (best for slow pages)
agent-browser wait --load networkidle
# Wait for a specific element to appear
agent-browser wait "#content"
agent-browser wait @e1
# Wait for a specific URL pattern (useful after redirects)
agent-browser wait --url "**/dashboard"
# Wait for a JavaScript condition
agent-browser wait --fn "document.readyState === 'complete'"
# Wait a fixed duration (milliseconds) as a last resort
agent-browser wait 5000
```
When dealing with consistently slow websites, use `wait --load networkidle` after `open` to ensure the page is fully loaded before taking a snapshot. If a specific element is slow to render, wait for it directly with `wait <selector>` or `wait @ref`.
## Session Management and Cleanup
When running multiple agents or automations concurrently, always use named sessions to avoid conflicts:
```bash
# Each agent gets its own isolated session
agent-browser --session agent1 open site-a.com
agent-browser --session agent2 open site-b.com
# Check active sessions
agent-browser session list
```
Always close your browser session when done to avoid leaked processes:
```bash
agent-browser close # Close default session
agent-browser --session agent1 close # Close specific session
```
If a previous session was not closed properly, the daemon may still be running. Use `agent-browser close` to clean it up before starting new work.
To auto-shutdown the daemon after a period of inactivity (useful for ephemeral/CI environments):
```bash
AGENT_BROWSER_IDLE_TIMEOUT_MS=60000 agent-browser open example.com
```
## Ref Lifecycle (Important)
Refs (`@e1`, `@e2`, etc.) are invalidated when the page changes. Always re-snapshot after:
- Clicking links or buttons that navigate
- Form submissions
- Dynamic content loading (dropdowns, modals)
```bash
agent-browser click @e5 # Navigates to new page
agent-browser snapshot -i # MUST re-snapshot
agent-browser click @e1 # Use new refs
```
## Annotated Screenshots (Vision Mode)
Use `--annotate` to take a screenshot with numbered labels overlaid on interactive elements. Each label `[N]` maps to ref `@eN`. This also caches refs, so you can interact with elements immediately without a separate snapshot.
```bash
agent-browser screenshot --annotate
# Output includes the image path and a legend:
# [1] @e1 button "Submit"
# [2] @e2 link "Home"
# [3] @e3 textbox "Email"
agent-browser click @e2 # Click using ref from annotated screenshot
```
Use annotated screenshots when:
- The page has unlabeled icon buttons or visual-only elements
- You need to verify visual layout or styling
- Canvas or chart elements are present (invisible to text snapshots)
- You need spatial reasoning about element positions
## Semantic Locators (Alternative to Refs)
When refs are unavailable or unreliable, use semantic locators:
```bash
agent-browser find text "Sign In" click
agent-browser find label "Email" fill "user@test.com"
agent-browser find role button click --name "Submit"
agent-browser find placeholder "Search" type "query"
agent-browser find testid "submit-btn" click
```
## JavaScript Evaluation (eval)
Use `eval` to run JavaScript in the browser context. **Shell quoting can corrupt complex expressions** -- use `--stdin` or `-b` to avoid issues.
```bash
# Simple expressions work with regular quoting
agent-browser eval 'document.title'
agent-browser eval 'document.querySelectorAll("img").length'
# Complex JS: use --stdin with heredoc (RECOMMENDED)
agent-browser eval --stdin <<'EVALEOF'
JSON.stringify(
Array.from(document.querySelectorAll("img"))
.filter(i => !i.alt)
.map(i => ({ src: i.src.split("/").pop(), width: i.width }))
)
EVALEOF
# Alternative: base64 encoding (avoids all shell escaping issues)
agent-browser eval -b "$(echo -n 'Array.from(document.querySelectorAll("a")).map(a => a.href)' | base64)"
```
**Why this matters:** When the shell processes your command, inner double quotes, `!` characters (history expansion), backticks, and `$()` can all corrupt the JavaScript before it reaches agent-browser. The `--stdin` and `-b` flags bypass shell interpretation entirely.
**Rules of thumb:**
- Single-line, no nested quotes -> regular `eval 'expression'` with single quotes is fine
- Nested quotes, arrow functions, template literals, or multiline -> use `eval --stdin <<'EVALEOF'`
- Programmatic/generated scripts -> use `eval -b` with base64
## Configuration File
Create `agent-browser.json` in the project root for persistent settings:
```json
{
"headed": true,
"proxy": "http://localhost:8080",
"profile": "./browser-data"
}
```
Priority (lowest to highest): `~/.agent-browser/config.json` < `./agent-browser.json` < env vars < CLI flags. Use `--config <path>` or `AGENT_BROWSER_CONFIG` env var for a custom config file (exits with error if missing/invalid). All CLI options map to camelCase keys (e.g., `--executable-path` -> `"executablePath"`). Boolean flags accept `true`/`false` values (e.g., `--headed false` overrides config). Extensions from user and project configs are merged, not replaced.
## Deep-Dive Documentation
| Reference | When to Use |
| -------------------------------------------------------------------- | --------------------------------------------------------- |
| [references/commands.md](references/commands.md) | Full command reference with all options |
| [references/snapshot-refs.md](references/snapshot-refs.md) | Ref lifecycle, invalidation rules, troubleshooting |
| [references/session-management.md](references/session-management.md) | Parallel sessions, state persistence, concurrent scraping |
| [references/authentication.md](references/authentication.md) | Login flows, OAuth, 2FA handling, state reuse |
| [references/video-recording.md](references/video-recording.md) | Recording workflows for debugging and documentation |
| [references/profiling.md](references/profiling.md) | Chrome DevTools profiling for performance analysis |
| [references/proxy-support.md](references/proxy-support.md) | Proxy configuration, geo-testing, rotating proxies |
## Browser Engine Selection
Use `--engine` to choose a local browser engine. The default is `chrome`.
```bash
# Use Lightpanda (fast headless browser, requires separate install)
agent-browser --engine lightpanda open example.com
# Via environment variable
export AGENT_BROWSER_ENGINE=lightpanda
agent-browser open example.com
# With custom binary path
agent-browser --engine lightpanda --executable-path /path/to/lightpanda open example.com
```
Supported engines:
- `chrome` (default) -- Chrome/Chromium via CDP
- `lightpanda` -- Lightpanda headless browser via CDP (10x faster, 10x less memory than Chrome)
Lightpanda does not support `--extension`, `--profile`, `--state`, or `--allow-file-access`. Install Lightpanda from https://lightpanda.io/docs/open-source/installation.
## Ready-to-Use Templates
| Template | Description |
| ------------------------------------------------------------------------ | ----------------------------------- |
| [templates/form-automation.sh](templates/form-automation.sh) | Form filling with validation |
| [templates/authenticated-session.sh](templates/authenticated-session.sh) | Login once, reuse state |
| [templates/capture-workflow.sh](templates/capture-workflow.sh) | Content extraction with screenshots |
```bash
./templates/form-automation.sh https://example.com/form
./templates/authenticated-session.sh https://app.example.com/login
./templates/capture-workflow.sh https://example.com ./output
```

303
.config/opencode/skills/agent-browser.disabled/references/authentication.md Normal file
View File

@@ -0,0 +1,303 @@
# Authentication Patterns
Login flows, session persistence, OAuth, 2FA, and authenticated browsing.
**Related**: [session-management.md](session-management.md) for state persistence details, [SKILL.md](../SKILL.md) for quick start.
## Contents
- [Import Auth from Your Browser](#import-auth-from-your-browser)
- [Persistent Profiles](#persistent-profiles)
- [Session Persistence](#session-persistence)
- [Basic Login Flow](#basic-login-flow)
- [Saving Authentication State](#saving-authentication-state)
- [Restoring Authentication](#restoring-authentication)
- [OAuth / SSO Flows](#oauth--sso-flows)
- [Two-Factor Authentication](#two-factor-authentication)
- [HTTP Basic Auth](#http-basic-auth)
- [Cookie-Based Auth](#cookie-based-auth)
- [Token Refresh Handling](#token-refresh-handling)
- [Security Best Practices](#security-best-practices)
## Import Auth from Your Browser
The fastest way to authenticate is to reuse cookies from a Chrome session you are already logged into.
**Step 1: Start Chrome with remote debugging**
```bash
# macOS
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222
# Linux
google-chrome --remote-debugging-port=9222
# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
```
Log in to your target site(s) in this Chrome window as you normally would.
> **Security note:** `--remote-debugging-port` exposes full browser control on localhost. Any local process can connect and read cookies, execute JS, etc. Only use on trusted machines and close Chrome when done.
**Step 2: Grab the auth state**
```bash
# Auto-discover the running Chrome and save its cookies + localStorage
agent-browser --auto-connect state save ./my-auth.json
```
**Step 3: Reuse in automation**
```bash
# Load auth at launch
agent-browser --state ./my-auth.json open https://app.example.com/dashboard
# Or load into an existing session
agent-browser state load ./my-auth.json
agent-browser open https://app.example.com/dashboard
```
This works for any site, including those with complex OAuth flows, SSO, or 2FA -- as long as Chrome already has valid session cookies.
> **Security note:** State files contain session tokens in plaintext. Add them to `.gitignore`, delete when no longer needed, and set `AGENT_BROWSER_ENCRYPTION_KEY` for encryption at rest. See [Security Best Practices](#security-best-practices).
**Tip:** Combine with `--session-name` so the imported auth auto-persists across restarts:
```bash
agent-browser --session-name myapp state load ./my-auth.json
# From now on, state is auto-saved/restored for "myapp"
```
## Persistent Profiles
Use `--profile` to point agent-browser at a Chrome user data directory. This persists everything (cookies, IndexedDB, service workers, cache) across browser restarts without explicit save/load:
```bash
# First run: login once
agent-browser --profile ~/.myapp-profile open https://app.example.com/login
# ... complete login flow ...
# All subsequent runs: already authenticated
agent-browser --profile ~/.myapp-profile open https://app.example.com/dashboard
```
Use different paths for different projects or test users:
```bash
agent-browser --profile ~/.profiles/admin open https://app.example.com
agent-browser --profile ~/.profiles/viewer open https://app.example.com
```
Or set via environment variable:
```bash
export AGENT_BROWSER_PROFILE=~/.myapp-profile
agent-browser open https://app.example.com/dashboard
```
## Session Persistence
Use `--session-name` to auto-save and restore cookies + localStorage by name, without managing files:
```bash
# Auto-saves state on close, auto-restores on next launch
agent-browser --session-name twitter open https://twitter.com
# ... login flow ...
agent-browser close # state saved to ~/.agent-browser/sessions/
# Next time: state is automatically restored
agent-browser --session-name twitter open https://twitter.com
```
Encrypt state at rest:
```bash
export AGENT_BROWSER_ENCRYPTION_KEY=$(openssl rand -hex 32)
agent-browser --session-name secure open https://app.example.com
```
## Basic Login Flow
```bash
# Navigate to login page
agent-browser open https://app.example.com/login
agent-browser wait --load networkidle
# Get form elements
agent-browser snapshot -i
# Output: @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Sign In"
# Fill credentials
agent-browser fill @e1 "user@example.com"
agent-browser fill @e2 "password123"
# Submit
agent-browser click @e3
agent-browser wait --load networkidle
# Verify login succeeded
agent-browser get url # Should be dashboard, not login
```
## Saving Authentication State
After logging in, save state for reuse:
```bash
# Login first (see above)
agent-browser open https://app.example.com/login
agent-browser snapshot -i
agent-browser fill @e1 "user@example.com"
agent-browser fill @e2 "password123"
agent-browser click @e3
agent-browser wait --url "**/dashboard"
# Save authenticated state
agent-browser state save ./auth-state.json
```
## Restoring Authentication
Skip login by loading saved state:
```bash
# Load saved auth state
agent-browser state load ./auth-state.json
# Navigate directly to protected page
agent-browser open https://app.example.com/dashboard
# Verify authenticated
agent-browser snapshot -i
```
## OAuth / SSO Flows
For OAuth redirects:
```bash
# Start OAuth flow
agent-browser open https://app.example.com/auth/google
# Handle redirects automatically
agent-browser wait --url "**/accounts.google.com**"
agent-browser snapshot -i
# Fill Google credentials
agent-browser fill @e1 "user@gmail.com"
agent-browser click @e2 # Next button
agent-browser wait 2000
agent-browser snapshot -i
agent-browser fill @e3 "password"
agent-browser click @e4 # Sign in
# Wait for redirect back
agent-browser wait --url "**/app.example.com**"
agent-browser state save ./oauth-state.json
```
## Two-Factor Authentication
Handle 2FA with manual intervention:
```bash
# Login with credentials
agent-browser open https://app.example.com/login --headed # Show browser
agent-browser snapshot -i
agent-browser fill @e1 "user@example.com"
agent-browser fill @e2 "password123"
agent-browser click @e3
# Wait for user to complete 2FA manually
echo "Complete 2FA in the browser window..."
agent-browser wait --url "**/dashboard" --timeout 120000
# Save state after 2FA
agent-browser state save ./2fa-state.json
```
## HTTP Basic Auth
For sites using HTTP Basic Authentication:
```bash
# Set credentials before navigation
agent-browser set credentials username password
# Navigate to protected resource
agent-browser open https://protected.example.com/api
```
## Cookie-Based Auth
Manually set authentication cookies:
```bash
# Set auth cookie
agent-browser cookies set session_token "abc123xyz"
# Navigate to protected page
agent-browser open https://app.example.com/dashboard
```
## Token Refresh Handling
For sessions with expiring tokens:
```bash
#!/bin/bash
# Wrapper that handles token refresh
STATE_FILE="./auth-state.json"
# Try loading existing state
if [[ -f "$STATE_FILE" ]]; then
agent-browser state load "$STATE_FILE"
agent-browser open https://app.example.com/dashboard
# Check if session is still valid
URL=$(agent-browser get url)
if [[ "$URL" == *"/login"* ]]; then
echo "Session expired, re-authenticating..."
# Perform fresh login
agent-browser snapshot -i
agent-browser fill @e1 "$USERNAME"
agent-browser fill @e2 "$PASSWORD"
agent-browser click @e3
agent-browser wait --url "**/dashboard"
agent-browser state save "$STATE_FILE"
fi
else
# First-time login
agent-browser open https://app.example.com/login
# ... login flow ...
fi
```
## Security Best Practices
1. **Never commit state files** - They contain session tokens
```bash
echo "*.auth-state.json" >> .gitignore
```
2. **Use environment variables for credentials**
```bash
agent-browser fill @e1 "$APP_USERNAME"
agent-browser fill @e2 "$APP_PASSWORD"
```
3. **Clean up after automation**
```bash
agent-browser cookies clear
rm -f ./auth-state.json
```
4. **Use short-lived sessions for CI/CD**
```bash
# Don't persist state in CI
agent-browser open https://app.example.com/login
# ... login and perform actions ...
agent-browser close # Session ends, nothing persisted
```

292
.config/opencode/skills/agent-browser.disabled/references/commands.md Normal file
View File

@@ -0,0 +1,292 @@
# Command Reference
Complete reference for all agent-browser commands. For quick start and common patterns, see SKILL.md.
## Navigation
```bash
agent-browser open <url> # Navigate to URL (aliases: goto, navigate)
# Supports: https://, http://, file://, about:, data://
# Auto-prepends https:// if no protocol given
agent-browser back # Go back
agent-browser forward # Go forward
agent-browser reload # Reload page
agent-browser close # Close browser (aliases: quit, exit)
agent-browser connect 9222 # Connect to browser via CDP port
```
## Snapshot (page analysis)
```bash
agent-browser snapshot # Full accessibility tree
agent-browser snapshot -i # Interactive elements only (recommended)
agent-browser snapshot -c # Compact output
agent-browser snapshot -d 3 # Limit depth to 3
agent-browser snapshot -s "#main" # Scope to CSS selector
```
## Interactions (use @refs from snapshot)
```bash
agent-browser click @e1 # Click
agent-browser click @e1 --new-tab # Click and open in new tab
agent-browser dblclick @e1 # Double-click
agent-browser focus @e1 # Focus element
agent-browser fill @e2 "text" # Clear and type
agent-browser type @e2 "text" # Type without clearing
agent-browser press Enter # Press key (alias: key)
agent-browser press Control+a # Key combination
agent-browser keydown Shift # Hold key down
agent-browser keyup Shift # Release key
agent-browser hover @e1 # Hover
agent-browser check @e1 # Check checkbox
agent-browser uncheck @e1 # Uncheck checkbox
agent-browser select @e1 "value" # Select dropdown option
agent-browser select @e1 "a" "b" # Select multiple options
agent-browser scroll down 500 # Scroll page (default: down 300px)
agent-browser scrollintoview @e1 # Scroll element into view (alias: scrollinto)
agent-browser drag @e1 @e2 # Drag and drop
agent-browser upload @e1 file.pdf # Upload files
```
## Get Information
```bash
agent-browser get text @e1 # Get element text
agent-browser get html @e1 # Get innerHTML
agent-browser get value @e1 # Get input value
agent-browser get attr @e1 href # Get attribute
agent-browser get title # Get page title
agent-browser get url # Get current URL
agent-browser get cdp-url # Get CDP WebSocket URL
agent-browser get count ".item" # Count matching elements
agent-browser get box @e1 # Get bounding box
agent-browser get styles @e1 # Get computed styles (font, color, bg, etc.)
```
## Check State
```bash
agent-browser is visible @e1 # Check if visible
agent-browser is enabled @e1 # Check if enabled
agent-browser is checked @e1 # Check if checked
```
## Screenshots and PDF
```bash
agent-browser screenshot # Save to temporary directory
agent-browser screenshot path.png # Save to specific path
agent-browser screenshot --full # Full page
agent-browser pdf output.pdf # Save as PDF
```
## Video Recording
```bash
agent-browser record start ./demo.webm # Start recording
agent-browser click @e1 # Perform actions
agent-browser record stop # Stop and save video
agent-browser record restart ./take2.webm # Stop current + start new
```
## Wait
```bash
agent-browser wait @e1 # Wait for element
agent-browser wait 2000 # Wait milliseconds
agent-browser wait --text "Success" # Wait for text (or -t)
agent-browser wait --url "**/dashboard" # Wait for URL pattern (or -u)
agent-browser wait --load networkidle # Wait for network idle (or -l)
agent-browser wait --fn "window.ready" # Wait for JS condition (or -f)
```
## Mouse Control
```bash
agent-browser mouse move 100 200 # Move mouse
agent-browser mouse down left # Press button
agent-browser mouse up left # Release button
agent-browser mouse wheel 100 # Scroll wheel
```
## Semantic Locators (alternative to refs)
```bash
agent-browser find role button click --name "Submit"
agent-browser find text "Sign In" click
agent-browser find text "Sign In" click --exact # Exact match only
agent-browser find label "Email" fill "user@test.com"
agent-browser find placeholder "Search" type "query"
agent-browser find alt "Logo" click
agent-browser find title "Close" click
agent-browser find testid "submit-btn" click
agent-browser find first ".item" click
agent-browser find last ".item" click
agent-browser find nth 2 "a" hover
```
## Browser Settings
```bash
agent-browser set viewport 1920 1080 # Set viewport size
agent-browser set viewport 1920 1080 2 # 2x retina (same CSS size, higher res screenshots)
agent-browser set device "iPhone 14" # Emulate device
agent-browser set geo 37.7749 -122.4194 # Set geolocation (alias: geolocation)
agent-browser set offline on # Toggle offline mode
agent-browser set headers '{"X-Key":"v"}' # Extra HTTP headers
agent-browser set credentials user pass # HTTP basic auth (alias: auth)
agent-browser set media dark # Emulate color scheme
agent-browser set media light reduced-motion # Light mode + reduced motion
```
## Cookies and Storage
```bash
agent-browser cookies # Get all cookies
agent-browser cookies set name value # Set cookie
agent-browser cookies clear # Clear cookies
agent-browser storage local # Get all localStorage
agent-browser storage local key # Get specific key
agent-browser storage local set k v # Set value
agent-browser storage local clear # Clear all
```
## Network
```bash
agent-browser network route <url> # Intercept requests
agent-browser network route <url> --abort # Block requests
agent-browser network route <url> --body '{}' # Mock response
agent-browser network unroute [url] # Remove routes
agent-browser network requests # View tracked requests
agent-browser network requests --filter api # Filter requests
```
## Tabs and Windows
```bash
agent-browser tab # List tabs
agent-browser tab new [url] # New tab
agent-browser tab 2 # Switch to tab by index
agent-browser tab close # Close current tab
agent-browser tab close 2 # Close tab by index
agent-browser window new # New window
```
## Frames
```bash
agent-browser frame "#iframe" # Switch to iframe by CSS selector
agent-browser frame @e3 # Switch to iframe by element ref
agent-browser frame main # Back to main frame
```
### Iframe support
Iframes are detected automatically during snapshots. When the main-frame snapshot runs, `Iframe` nodes are resolved and their content is inlined beneath the iframe element in the output (one level of nesting; iframes within iframes are not expanded).
```bash
agent-browser snapshot -i
# @e3 [Iframe] "payment-frame"
# @e4 [input] "Card number"
# @e5 [button] "Pay"
# Interact directly — refs inside iframes already work
agent-browser fill @e4 "4111111111111111"
agent-browser click @e5
# Or switch frame context for scoped snapshots
agent-browser frame @e3 # Switch using element ref
agent-browser snapshot -i # Snapshot scoped to that iframe
agent-browser frame main # Return to main frame
```
The `frame` command accepts:
- **Element refs** — `frame @e3` resolves the ref to an iframe element
- **CSS selectors** — `frame "#payment-iframe"` finds the iframe by selector
- **Frame name/URL** — matches against the browser's frame tree
## Dialogs
```bash
agent-browser dialog accept [text] # Accept dialog
agent-browser dialog dismiss # Dismiss dialog
```
## JavaScript
```bash
agent-browser eval "document.title" # Simple expressions only
agent-browser eval -b "<base64>" # Any JavaScript (base64 encoded)
agent-browser eval --stdin # Read script from stdin
```
Use `-b`/`--base64` or `--stdin` for reliable execution. Shell escaping with nested quotes and special characters is error-prone.
```bash
# Base64 encode your script, then:
agent-browser eval -b "ZG9jdW1lbnQucXVlcnlTZWxlY3RvcignW3NyYyo9Il9uZXh0Il0nKQ=="
# Or use stdin with heredoc for multiline scripts:
cat <<'EOF' | agent-browser eval --stdin
const links = document.querySelectorAll('a');
Array.from(links).map(a => a.href);
EOF
```
## State Management
```bash
agent-browser state save auth.json # Save cookies, storage, auth state
agent-browser state load auth.json # Restore saved state
```
## Global Options
```bash
agent-browser --session <name> ... # Isolated browser session
agent-browser --json ... # JSON output for parsing
agent-browser --headed ... # Show browser window (not headless)
agent-browser --full ... # Full page screenshot (-f)
agent-browser --cdp <port> ... # Connect via Chrome DevTools Protocol
agent-browser -p <provider> ... # Cloud browser provider (--provider)
agent-browser --proxy <url> ... # Use proxy server
agent-browser --proxy-bypass <hosts> # Hosts to bypass proxy
agent-browser --headers <json> ... # HTTP headers scoped to URL's origin
agent-browser --executable-path <p> # Custom browser executable
agent-browser --extension <path> ... # Load browser extension (repeatable)
agent-browser --ignore-https-errors # Ignore SSL certificate errors
agent-browser --help # Show help (-h)
agent-browser --version # Show version (-V)
agent-browser <command> --help # Show detailed help for a command
```
## Debugging
```bash
agent-browser --headed open example.com # Show browser window
agent-browser --cdp 9222 snapshot # Connect via CDP port
agent-browser connect 9222 # Alternative: connect command
agent-browser console # View console messages
agent-browser console --clear # Clear console
agent-browser errors # View page errors
agent-browser errors --clear # Clear errors
agent-browser highlight @e1 # Highlight element
agent-browser inspect # Open Chrome DevTools for this session
agent-browser trace start # Start recording trace
agent-browser trace stop trace.zip # Stop and save trace
agent-browser profiler start # Start Chrome DevTools profiling
agent-browser profiler stop trace.json # Stop and save profile
```
## Environment Variables
```bash
AGENT_BROWSER_SESSION="mysession" # Default session name
AGENT_BROWSER_EXECUTABLE_PATH="/path/chrome" # Custom browser path
AGENT_BROWSER_EXTENSIONS="/ext1,/ext2" # Comma-separated extension paths
AGENT_BROWSER_PROVIDER="browserbase" # Cloud browser provider
AGENT_BROWSER_STREAM_PORT="9223" # WebSocket streaming port
AGENT_BROWSER_HOME="/path/to/agent-browser" # Custom install location
```

120
.config/opencode/skills/agent-browser.disabled/references/profiling.md Normal file
View File

@@ -0,0 +1,120 @@
# Profiling
Capture Chrome DevTools performance profiles during browser automation for performance analysis.
**Related**: [commands.md](commands.md) for full command reference, [SKILL.md](../SKILL.md) for quick start.
## Contents
- [Basic Profiling](#basic-profiling)
- [Profiler Commands](#profiler-commands)
- [Categories](#categories)
- [Use Cases](#use-cases)
- [Output Format](#output-format)
- [Viewing Profiles](#viewing-profiles)
- [Limitations](#limitations)
## Basic Profiling
```bash
# Start profiling
agent-browser profiler start
# Perform actions
agent-browser navigate https://example.com
agent-browser click "#button"
agent-browser wait 1000
# Stop and save
agent-browser profiler stop ./trace.json
```
## Profiler Commands
```bash
# Start profiling with default categories
agent-browser profiler start
# Start with custom trace categories
agent-browser profiler start --categories "devtools.timeline,v8.execute,blink.user_timing"
# Stop profiling and save to file
agent-browser profiler stop ./trace.json
```
## Categories
The `--categories` flag accepts a comma-separated list of Chrome trace categories. Default categories include:
- `devtools.timeline` -- standard DevTools performance traces
- `v8.execute` -- time spent running JavaScript
- `blink` -- renderer events
- `blink.user_timing` -- `performance.mark()` / `performance.measure()` calls
- `latencyInfo` -- input-to-latency tracking
- `renderer.scheduler` -- task scheduling and execution
- `toplevel` -- broad-spectrum basic events
Several `disabled-by-default-*` categories are also included for detailed timeline, call stack, and V8 CPU profiling data.
## Use Cases
### Diagnosing Slow Page Loads
```bash
agent-browser profiler start
agent-browser navigate https://app.example.com
agent-browser wait --load networkidle
agent-browser profiler stop ./page-load-profile.json
```
### Profiling User Interactions
```bash
agent-browser navigate https://app.example.com
agent-browser profiler start
agent-browser click "#submit"
agent-browser wait 2000
agent-browser profiler stop ./interaction-profile.json
```
### CI Performance Regression Checks
```bash
#!/bin/bash
agent-browser profiler start
agent-browser navigate https://app.example.com
agent-browser wait --load networkidle
agent-browser profiler stop "./profiles/build-${BUILD_ID}.json"
```
## Output Format
The output is a JSON file in Chrome Trace Event format:
```json
{
"traceEvents": [
{ "cat": "devtools.timeline", "name": "RunTask", "ph": "X", "ts": 12345, "dur": 100, ... },
...
],
"metadata": {
"clock-domain": "LINUX_CLOCK_MONOTONIC"
}
}
```
The `metadata.clock-domain` field is set based on the host platform (Linux or macOS). On Windows it is omitted.
## Viewing Profiles
Load the output JSON file in any of these tools:
- **Chrome DevTools**: Performance panel > Load profile (Ctrl+Shift+I > Performance)
- **Perfetto UI**: https://ui.perfetto.dev/ -- drag and drop the JSON file
- **Trace Viewer**: `chrome://tracing` in any Chromium browser
## Limitations
- Only works with Chromium-based browsers (Chrome, Edge). Not supported on Firefox or WebKit.
- Trace data accumulates in memory while profiling is active (capped at 5 million events). Stop profiling promptly after the area of interest.
- Data collection on stop has a 30-second timeout. If the browser is unresponsive, the stop command may fail.

194
.config/opencode/skills/agent-browser.disabled/references/proxy-support.md Normal file
View File

@@ -0,0 +1,194 @@
# Proxy Support
Proxy configuration for geo-testing, rate limiting avoidance, and corporate environments.
**Related**: [commands.md](commands.md) for global options, [SKILL.md](../SKILL.md) for quick start.
## Contents
- [Basic Proxy Configuration](#basic-proxy-configuration)
- [Authenticated Proxy](#authenticated-proxy)
- [SOCKS Proxy](#socks-proxy)
- [Proxy Bypass](#proxy-bypass)
- [Common Use Cases](#common-use-cases)
- [Verifying Proxy Connection](#verifying-proxy-connection)
- [Troubleshooting](#troubleshooting)
- [Best Practices](#best-practices)
## Basic Proxy Configuration
Use the `--proxy` flag or set proxy via environment variable:
```bash
# Via CLI flag
agent-browser --proxy "http://proxy.example.com:8080" open https://example.com
# Via environment variable
export HTTP_PROXY="http://proxy.example.com:8080"
agent-browser open https://example.com
# HTTPS proxy
export HTTPS_PROXY="https://proxy.example.com:8080"
agent-browser open https://example.com
# Both
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"
agent-browser open https://example.com
```
## Authenticated Proxy
For proxies requiring authentication:
```bash
# Include credentials in URL
export HTTP_PROXY="http://username:password@proxy.example.com:8080"
agent-browser open https://example.com
```
## SOCKS Proxy
```bash
# SOCKS5 proxy
export ALL_PROXY="socks5://proxy.example.com:1080"
agent-browser open https://example.com
# SOCKS5 with auth
export ALL_PROXY="socks5://user:pass@proxy.example.com:1080"
agent-browser open https://example.com
```
## Proxy Bypass
Skip proxy for specific domains using `--proxy-bypass` or `NO_PROXY`:
```bash
# Via CLI flag
agent-browser --proxy "http://proxy.example.com:8080" --proxy-bypass "localhost,*.internal.com" open https://example.com
# Via environment variable
export NO_PROXY="localhost,127.0.0.1,.internal.company.com"
agent-browser open https://internal.company.com # Direct connection
agent-browser open https://external.com # Via proxy
```
## Common Use Cases
### Geo-Location Testing
```bash
#!/bin/bash
# Test site from different regions using geo-located proxies
PROXIES=(
"http://us-proxy.example.com:8080"
"http://eu-proxy.example.com:8080"
"http://asia-proxy.example.com:8080"
)
for proxy in "${PROXIES[@]}"; do
export HTTP_PROXY="$proxy"
export HTTPS_PROXY="$proxy"
region=$(echo "$proxy" | grep -oP '^\w+-\w+')
echo "Testing from: $region"
agent-browser --session "$region" open https://example.com
agent-browser --session "$region" screenshot "./screenshots/$region.png"
agent-browser --session "$region" close
done
```
### Rotating Proxies for Scraping
```bash
#!/bin/bash
# Rotate through proxy list to avoid rate limiting
PROXY_LIST=(
"http://proxy1.example.com:8080"
"http://proxy2.example.com:8080"
"http://proxy3.example.com:8080"
)
URLS=(
"https://site.com/page1"
"https://site.com/page2"
"https://site.com/page3"
)
for i in "${!URLS[@]}"; do
proxy_index=$((i % ${#PROXY_LIST[@]}))
export HTTP_PROXY="${PROXY_LIST[$proxy_index]}"
export HTTPS_PROXY="${PROXY_LIST[$proxy_index]}"
agent-browser open "${URLS[$i]}"
agent-browser get text body > "output-$i.txt"
agent-browser close
sleep 1 # Polite delay
done
```
### Corporate Network Access
```bash
#!/bin/bash
# Access internal sites via corporate proxy
export HTTP_PROXY="http://corpproxy.company.com:8080"
export HTTPS_PROXY="http://corpproxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1,.company.com"
# External sites go through proxy
agent-browser open https://external-vendor.com
# Internal sites bypass proxy
agent-browser open https://intranet.company.com
```
## Verifying Proxy Connection
```bash
# Check your apparent IP
agent-browser open https://httpbin.org/ip
agent-browser get text body
# Should show proxy's IP, not your real IP
```
## Troubleshooting
### Proxy Connection Failed
```bash
# Test proxy connectivity first
curl -x http://proxy.example.com:8080 https://httpbin.org/ip
# Check if proxy requires auth
export HTTP_PROXY="http://user:pass@proxy.example.com:8080"
```
### SSL/TLS Errors Through Proxy
Some proxies perform SSL inspection. If you encounter certificate errors:
```bash
# For testing only - not recommended for production
agent-browser open https://example.com --ignore-https-errors
```
### Slow Performance
```bash
# Use proxy only when necessary
export NO_PROXY="*.cdn.com,*.static.com" # Direct CDN access
```
## Best Practices
1. **Use environment variables** - Don't hardcode proxy credentials
2. **Set NO_PROXY appropriately** - Avoid routing local traffic through proxy
3. **Test proxy before automation** - Verify connectivity with simple requests
4. **Handle proxy failures gracefully** - Implement retry logic for unstable proxies
5. **Rotate proxies for large scraping jobs** - Distribute load and avoid bans

193
.config/opencode/skills/agent-browser.disabled/references/session-management.md Normal file
View File

@@ -0,0 +1,193 @@
# Session Management
Multiple isolated browser sessions with state persistence and concurrent browsing.
**Related**: [authentication.md](authentication.md) for login patterns, [SKILL.md](../SKILL.md) for quick start.
## Contents
- [Named Sessions](#named-sessions)
- [Session Isolation Properties](#session-isolation-properties)
- [Session State Persistence](#session-state-persistence)
- [Common Patterns](#common-patterns)
- [Default Session](#default-session)
- [Session Cleanup](#session-cleanup)
- [Best Practices](#best-practices)
## Named Sessions
Use `--session` flag to isolate browser contexts:
```bash
# Session 1: Authentication flow
agent-browser --session auth open https://app.example.com/login
# Session 2: Public browsing (separate cookies, storage)
agent-browser --session public open https://example.com
# Commands are isolated by session
agent-browser --session auth fill @e1 "user@example.com"
agent-browser --session public get text body
```
## Session Isolation Properties
Each session has independent:
- Cookies
- LocalStorage / SessionStorage
- IndexedDB
- Cache
- Browsing history
- Open tabs
## Session State Persistence
### Save Session State
```bash
# Save cookies, storage, and auth state
agent-browser state save /path/to/auth-state.json
```
### Load Session State
```bash
# Restore saved state
agent-browser state load /path/to/auth-state.json
# Continue with authenticated session
agent-browser open https://app.example.com/dashboard
```
### State File Contents
```json
{
"cookies": [...],
"localStorage": {...},
"sessionStorage": {...},
"origins": [...]
}
```
## Common Patterns
### Authenticated Session Reuse
```bash
#!/bin/bash
# Save login state once, reuse many times
STATE_FILE="/tmp/auth-state.json"
# Check if we have saved state
if [[ -f "$STATE_FILE" ]]; then
agent-browser state load "$STATE_FILE"
agent-browser open https://app.example.com/dashboard
else
# Perform login
agent-browser open https://app.example.com/login
agent-browser snapshot -i
agent-browser fill @e1 "$USERNAME"
agent-browser fill @e2 "$PASSWORD"
agent-browser click @e3
agent-browser wait --load networkidle
# Save for future use
agent-browser state save "$STATE_FILE"
fi
```
### Concurrent Scraping
```bash
#!/bin/bash
# Scrape multiple sites concurrently
# Start all sessions
agent-browser --session site1 open https://site1.com &
agent-browser --session site2 open https://site2.com &
agent-browser --session site3 open https://site3.com &
wait
# Extract from each
agent-browser --session site1 get text body > site1.txt
agent-browser --session site2 get text body > site2.txt
agent-browser --session site3 get text body > site3.txt
# Cleanup
agent-browser --session site1 close
agent-browser --session site2 close
agent-browser --session site3 close
```
### A/B Testing Sessions
```bash
# Test different user experiences
agent-browser --session variant-a open "https://app.com?variant=a"
agent-browser --session variant-b open "https://app.com?variant=b"
# Compare
agent-browser --session variant-a screenshot /tmp/variant-a.png
agent-browser --session variant-b screenshot /tmp/variant-b.png
```
## Default Session
When `--session` is omitted, commands use the default session:
```bash
# These use the same default session
agent-browser open https://example.com
agent-browser snapshot -i
agent-browser close # Closes default session
```
## Session Cleanup
```bash
# Close specific session
agent-browser --session auth close
# List active sessions
agent-browser session list
```
## Best Practices
### 1. Name Sessions Semantically
```bash
# GOOD: Clear purpose
agent-browser --session github-auth open https://github.com
agent-browser --session docs-scrape open https://docs.example.com
# AVOID: Generic names
agent-browser --session s1 open https://github.com
```
### 2. Always Clean Up
```bash
# Close sessions when done
agent-browser --session auth close
agent-browser --session scrape close
```
### 3. Handle State Files Securely
```bash
# Don't commit state files (contain auth tokens!)
echo "*.auth-state.json" >> .gitignore
# Delete after use
rm /tmp/auth-state.json
```
### 4. Timeout Long Sessions
```bash
# Set timeout for automated scripts
timeout 60 agent-browser --session long-task get text body
```

219
.config/opencode/skills/agent-browser.disabled/references/snapshot-refs.md Normal file
View File

@@ -0,0 +1,219 @@
# Snapshot and Refs
Compact element references that reduce context usage dramatically for AI agents.
**Related**: [commands.md](commands.md) for full command reference, [SKILL.md](../SKILL.md) for quick start.
## Contents
- [How Refs Work](#how-refs-work)
- [Snapshot Command](#the-snapshot-command)
- [Using Refs](#using-refs)
- [Ref Lifecycle](#ref-lifecycle)
- [Best Practices](#best-practices)
- [Ref Notation Details](#ref-notation-details)
- [Troubleshooting](#troubleshooting)
## How Refs Work
Traditional approach:
```
Full DOM/HTML → AI parses → CSS selector → Action (~3000-5000 tokens)
```
agent-browser approach:
```
Compact snapshot → @refs assigned → Direct interaction (~200-400 tokens)
```
## The Snapshot Command
```bash
# Basic snapshot (shows page structure)
agent-browser snapshot
# Interactive snapshot (-i flag) - RECOMMENDED
agent-browser snapshot -i
```
### Snapshot Output Format
```
Page: Example Site - Home
URL: https://example.com
@e1 [header]
@e2 [nav]
@e3 [a] "Home"
@e4 [a] "Products"
@e5 [a] "About"
@e6 [button] "Sign In"
@e7 [main]
@e8 [h1] "Welcome"
@e9 [form]
@e10 [input type="email"] placeholder="Email"
@e11 [input type="password"] placeholder="Password"
@e12 [button type="submit"] "Log In"
@e13 [footer]
@e14 [a] "Privacy Policy"
```
## Using Refs
Once you have refs, interact directly:
```bash
# Click the "Sign In" button
agent-browser click @e6
# Fill email input
agent-browser fill @e10 "user@example.com"
# Fill password
agent-browser fill @e11 "password123"
# Submit the form
agent-browser click @e12
```
## Ref Lifecycle
**IMPORTANT**: Refs are invalidated when the page changes!
```bash
# Get initial snapshot
agent-browser snapshot -i
# @e1 [button] "Next"
# Click triggers page change
agent-browser click @e1
# MUST re-snapshot to get new refs!
agent-browser snapshot -i
# @e1 [h1] "Page 2" ← Different element now!
```
## Best Practices
### 1. Always Snapshot Before Interacting
```bash
# CORRECT
agent-browser open https://example.com
agent-browser snapshot -i # Get refs first
agent-browser click @e1 # Use ref
# WRONG
agent-browser open https://example.com
agent-browser click @e1 # Ref doesn't exist yet!
```
### 2. Re-Snapshot After Navigation
```bash
agent-browser click @e5 # Navigates to new page
agent-browser snapshot -i # Get new refs
agent-browser click @e1 # Use new refs
```
### 3. Re-Snapshot After Dynamic Changes
```bash
agent-browser click @e1 # Opens dropdown
agent-browser snapshot -i # See dropdown items
agent-browser click @e7 # Select item
```
### 4. Snapshot Specific Regions
For complex pages, snapshot specific areas:
```bash
# Snapshot just the form
agent-browser snapshot @e9
```
## Ref Notation Details
```
@e1 [tag type="value"] "text content" placeholder="hint"
│ │ │ │ │
│ │ │ │ └─ Additional attributes
│ │ │ └─ Visible text
│ │ └─ Key attributes shown
│ └─ HTML tag name
└─ Unique ref ID
```
### Common Patterns
```
@e1 [button] "Submit" # Button with text
@e2 [input type="email"] # Email input
@e3 [input type="password"] # Password input
@e4 [a href="/page"] "Link Text" # Anchor link
@e5 [select] # Dropdown
@e6 [textarea] placeholder="Message" # Text area
@e7 [div class="modal"] # Container (when relevant)
@e8 [img alt="Logo"] # Image
@e9 [checkbox] checked # Checked checkbox
@e10 [radio] selected # Selected radio
```
## Iframes
Snapshots automatically detect and inline iframe content. When the main-frame snapshot runs, each `Iframe` node is resolved and its child accessibility tree is included directly beneath it in the output. Refs assigned to elements inside iframes carry frame context, so interactions like `click`, `fill`, and `type` work without manually switching frames.
```bash
agent-browser snapshot -i
# @e1 [heading] "Checkout"
# @e2 [Iframe] "payment-frame"
# @e3 [input] "Card number"
# @e4 [input] "Expiry"
# @e5 [button] "Pay"
# @e6 [button] "Cancel"
# Interact with iframe elements directly using their refs
agent-browser fill @e3 "4111111111111111"
agent-browser fill @e4 "12/28"
agent-browser click @e5
```
**Key details:**
- Only one level of iframe nesting is expanded (iframes within iframes are not recursed)
- Cross-origin iframes that block accessibility tree access are silently skipped
- Empty iframes or iframes with no interactive content are omitted from the output
- To scope a snapshot to a single iframe, use `frame @ref` then `snapshot -i`
## Troubleshooting
### "Ref not found" Error
```bash
# Ref may have changed - re-snapshot
agent-browser snapshot -i
```
### Element Not Visible in Snapshot
```bash
# Scroll down to reveal element
agent-browser scroll down 1000
agent-browser snapshot -i
# Or wait for dynamic content
agent-browser wait 1000
agent-browser snapshot -i
```
### Too Many Elements
```bash
# Snapshot specific container
agent-browser snapshot @e5
# Or use get text for content-only extraction
agent-browser get text @e5
```

173
.config/opencode/skills/agent-browser.disabled/references/video-recording.md Normal file
View File

@@ -0,0 +1,173 @@
# Video Recording
Capture browser automation as video for debugging, documentation, or verification.
**Related**: [commands.md](commands.md) for full command reference, [SKILL.md](../SKILL.md) for quick start.
## Contents
- [Basic Recording](#basic-recording)
- [Recording Commands](#recording-commands)
- [Use Cases](#use-cases)
- [Best Practices](#best-practices)
- [Output Format](#output-format)
- [Limitations](#limitations)
## Basic Recording
```bash
# Start recording
agent-browser record start ./demo.webm
# Perform actions
agent-browser open https://example.com
agent-browser snapshot -i
agent-browser click @e1
agent-browser fill @e2 "test input"
# Stop and save
agent-browser record stop
```
## Recording Commands
```bash
# Start recording to file
agent-browser record start ./output.webm
# Stop current recording
agent-browser record stop
# Restart with new file (stops current + starts new)
agent-browser record restart ./take2.webm
```
## Use Cases
### Debugging Failed Automation
```bash
#!/bin/bash
# Record automation for debugging
agent-browser record start ./debug-$(date +%Y%m%d-%H%M%S).webm
# Run your automation
agent-browser open https://app.example.com
agent-browser snapshot -i
agent-browser click @e1 || {
echo "Click failed - check recording"
agent-browser record stop
exit 1
}
agent-browser record stop
```
### Documentation Generation
```bash
#!/bin/bash
# Record workflow for documentation
agent-browser record start ./docs/how-to-login.webm
agent-browser open https://app.example.com/login
agent-browser wait 1000 # Pause for visibility
agent-browser snapshot -i
agent-browser fill @e1 "demo@example.com"
agent-browser wait 500
agent-browser fill @e2 "password"
agent-browser wait 500
agent-browser click @e3
agent-browser wait --load networkidle
agent-browser wait 1000 # Show result
agent-browser record stop
```
### CI/CD Test Evidence
```bash
#!/bin/bash
# Record E2E test runs for CI artifacts
TEST_NAME="${1:-e2e-test}"
RECORDING_DIR="./test-recordings"
mkdir -p "$RECORDING_DIR"
agent-browser record start "$RECORDING_DIR/$TEST_NAME-$(date +%s).webm"
# Run test
if run_e2e_test; then
echo "Test passed"
else
echo "Test failed - recording saved"
fi
agent-browser record stop
```
## Best Practices
### 1. Add Pauses for Clarity
```bash
# Slow down for human viewing
agent-browser click @e1
agent-browser wait 500 # Let viewer see result
```
### 2. Use Descriptive Filenames
```bash
# Include context in filename
agent-browser record start ./recordings/login-flow-2024-01-15.webm
agent-browser record start ./recordings/checkout-test-run-42.webm
```
### 3. Handle Recording in Error Cases
```bash
#!/bin/bash
set -e
cleanup() {
agent-browser record stop 2>/dev/null || true
agent-browser close 2>/dev/null || true
}
trap cleanup EXIT
agent-browser record start ./automation.webm
# ... automation steps ...
```
### 4. Combine with Screenshots
```bash
# Record video AND capture key frames
agent-browser record start ./flow.webm
agent-browser open https://example.com
agent-browser screenshot ./screenshots/step1-homepage.png
agent-browser click @e1
agent-browser screenshot ./screenshots/step2-after-click.png
agent-browser record stop
```
## Output Format
- Default format: WebM (VP8/VP9 codec)
- Compatible with all modern browsers and video players
- Compressed but high quality
## Limitations
- Recording adds slight overhead to automation
- Large recordings can consume significant disk space
- Some headless environments may have codec limitations

105
.config/opencode/skills/agent-browser.disabled/templates/authenticated-session.sh Executable file
View File

@@ -0,0 +1,105 @@
#!/bin/bash
# Template: Authenticated Session Workflow
# Purpose: Login once, save state, reuse for subsequent runs
# Usage: ./authenticated-session.sh <login-url> [state-file]
#
# RECOMMENDED: Use the auth vault instead of this template:
# echo "<pass>" | agent-browser auth save myapp --url <login-url> --username <user> --password-stdin
# agent-browser auth login myapp
# The auth vault stores credentials securely and the LLM never sees passwords.
#
# Environment variables:
# APP_USERNAME - Login username/email
# APP_PASSWORD - Login password
#
# Two modes:
# 1. Discovery mode (default): Shows form structure so you can identify refs
# 2. Login mode: Performs actual login after you update the refs
#
# Setup steps:
# 1. Run once to see form structure (discovery mode)
# 2. Update refs in LOGIN FLOW section below
# 3. Set APP_USERNAME and APP_PASSWORD
# 4. Delete the DISCOVERY section
set -euo pipefail
LOGIN_URL="${1:?Usage: $0 <login-url> [state-file]}"
STATE_FILE="${2:-./auth-state.json}"
echo "Authentication workflow: $LOGIN_URL"
# ================================================================
# SAVED STATE: Skip login if valid saved state exists
# ================================================================
if [[ -f "$STATE_FILE" ]]; then
echo "Loading saved state from $STATE_FILE..."
if agent-browser --state "$STATE_FILE" open "$LOGIN_URL" 2>/dev/null; then
agent-browser wait --load networkidle
CURRENT_URL=$(agent-browser get url)
if [[ "$CURRENT_URL" != *"login"* ]] && [[ "$CURRENT_URL" != *"signin"* ]]; then
echo "Session restored successfully"
agent-browser snapshot -i
exit 0
fi
echo "Session expired, performing fresh login..."
agent-browser close 2>/dev/null || true
else
echo "Failed to load state, re-authenticating..."
fi
rm -f "$STATE_FILE"
fi
# ================================================================
# DISCOVERY MODE: Shows form structure (delete after setup)
# ================================================================
echo "Opening login page..."
agent-browser open "$LOGIN_URL"
agent-browser wait --load networkidle
echo ""
echo "Login form structure:"
echo "---"
agent-browser snapshot -i
echo "---"
echo ""
echo "Next steps:"
echo " 1. Note the refs: username=@e?, password=@e?, submit=@e?"
echo " 2. Update the LOGIN FLOW section below with your refs"
echo " 3. Set: export APP_USERNAME='...' APP_PASSWORD='...'"
echo " 4. Delete this DISCOVERY MODE section"
echo ""
agent-browser close
exit 0
# ================================================================
# LOGIN FLOW: Uncomment and customize after discovery
# ================================================================
# : "${APP_USERNAME:?Set APP_USERNAME environment variable}"
# : "${APP_PASSWORD:?Set APP_PASSWORD environment variable}"
#
# agent-browser open "$LOGIN_URL"
# agent-browser wait --load networkidle
# agent-browser snapshot -i
#
# # Fill credentials (update refs to match your form)
# agent-browser fill @e1 "$APP_USERNAME"
# agent-browser fill @e2 "$APP_PASSWORD"
# agent-browser click @e3
# agent-browser wait --load networkidle
#
# # Verify login succeeded
# FINAL_URL=$(agent-browser get url)
# if [[ "$FINAL_URL" == *"login"* ]] || [[ "$FINAL_URL" == *"signin"* ]]; then
# echo "Login failed - still on login page"
# agent-browser screenshot /tmp/login-failed.png
# agent-browser close
# exit 1
# fi
#
# # Save state for future runs
# echo "Saving state to $STATE_FILE"
# agent-browser state save "$STATE_FILE"
# echo "Login successful"
# agent-browser snapshot -i

69
.config/opencode/skills/agent-browser.disabled/templates/capture-workflow.sh Executable file
View File

@@ -0,0 +1,69 @@
#!/bin/bash
# Template: Content Capture Workflow
# Purpose: Extract content from web pages (text, screenshots, PDF)
# Usage: ./capture-workflow.sh <url> [output-dir]
#
# Outputs:
# - page-full.png: Full page screenshot
# - page-structure.txt: Page element structure with refs
# - page-text.txt: All text content
# - page.pdf: PDF version
#
# Optional: Load auth state for protected pages
set -euo pipefail
TARGET_URL="${1:?Usage: $0 <url> [output-dir]}"
OUTPUT_DIR="${2:-.}"
echo "Capturing: $TARGET_URL"
mkdir -p "$OUTPUT_DIR"
# Optional: Load authentication state
# if [[ -f "./auth-state.json" ]]; then
# echo "Loading authentication state..."
# agent-browser state load "./auth-state.json"
# fi
# Navigate to target
agent-browser open "$TARGET_URL"
agent-browser wait --load networkidle
# Get metadata
TITLE=$(agent-browser get title)
URL=$(agent-browser get url)
echo "Title: $TITLE"
echo "URL: $URL"
# Capture full page screenshot
agent-browser screenshot --full "$OUTPUT_DIR/page-full.png"
echo "Saved: $OUTPUT_DIR/page-full.png"
# Get page structure with refs
agent-browser snapshot -i > "$OUTPUT_DIR/page-structure.txt"
echo "Saved: $OUTPUT_DIR/page-structure.txt"
# Extract all text content
agent-browser get text body > "$OUTPUT_DIR/page-text.txt"
echo "Saved: $OUTPUT_DIR/page-text.txt"
# Save as PDF
agent-browser pdf "$OUTPUT_DIR/page.pdf"
echo "Saved: $OUTPUT_DIR/page.pdf"
# Optional: Extract specific elements using refs from structure
# agent-browser get text @e5 > "$OUTPUT_DIR/main-content.txt"
# Optional: Handle infinite scroll pages
# for i in {1..5}; do
# agent-browser scroll down 1000
# agent-browser wait 1000
# done
# agent-browser screenshot --full "$OUTPUT_DIR/page-scrolled.png"
# Cleanup
agent-browser close
echo ""
echo "Capture complete:"
ls -la "$OUTPUT_DIR"

62
.config/opencode/skills/agent-browser.disabled/templates/form-automation.sh Executable file
View File

@@ -0,0 +1,62 @@
#!/bin/bash
# Template: Form Automation Workflow
# Purpose: Fill and submit web forms with validation
# Usage: ./form-automation.sh <form-url>
#
# This template demonstrates the snapshot-interact-verify pattern:
# 1. Navigate to form
# 2. Snapshot to get element refs
# 3. Fill fields using refs
# 4. Submit and verify result
#
# Customize: Update the refs (@e1, @e2, etc.) based on your form's snapshot output
set -euo pipefail
FORM_URL="${1:?Usage: $0 <form-url>}"
echo "Form automation: $FORM_URL"
# Step 1: Navigate to form
agent-browser open "$FORM_URL"
agent-browser wait --load networkidle
# Step 2: Snapshot to discover form elements
echo ""
echo "Form structure:"
agent-browser snapshot -i
# Step 3: Fill form fields (customize these refs based on snapshot output)
#
# Common field types:
# agent-browser fill @e1 "John Doe" # Text input
# agent-browser fill @e2 "user@example.com" # Email input
# agent-browser fill @e3 "SecureP@ss123" # Password input
# agent-browser select @e4 "Option Value" # Dropdown
# agent-browser check @e5 # Checkbox
# agent-browser click @e6 # Radio button
# agent-browser fill @e7 "Multi-line text" # Textarea
# agent-browser upload @e8 /path/to/file.pdf # File upload
#
# Uncomment and modify:
# agent-browser fill @e1 "Test User"
# agent-browser fill @e2 "test@example.com"
# agent-browser click @e3 # Submit button
# Step 4: Wait for submission
# agent-browser wait --load networkidle
# agent-browser wait --url "**/success" # Or wait for redirect
# Step 5: Verify result
echo ""
echo "Result:"
agent-browser get url
agent-browser snapshot -i
# Optional: Capture evidence
agent-browser screenshot /tmp/form-result.png
echo "Screenshot saved: /tmp/form-result.png"
# Cleanup
agent-browser close
echo "Done"

164
.config/opencode/skills/brainstorming/SKILL.md Normal file
View File

@@ -0,0 +1,164 @@
---
name: brainstorming
description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
---
# Brainstorming Ideas Into Designs
Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.
<HARD-GATE>
Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
</HARD-GATE>
## Anti-Pattern: "This Is Too Simple To Need A Design"
Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
## Checklist
You MUST create a task for each of these items and complete them in order:
1. **Explore project context** — check files, docs, recent commits
2. **Offer visual companion** (if topic will involve visual questions) — this is its own message, not combined with a clarifying question. See the Visual Companion section below.
3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
4. **Propose 2-3 approaches** — with trade-offs and your recommendation
5. **Present design** — in sections scaled to their complexity, get user approval after each section
6. **Write design doc** — save to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` and commit
7. **Spec review loop** — dispatch spec-document-reviewer subagent with precisely crafted review context (never your session history); fix issues and re-dispatch until approved (max 3 iterations, then surface to human)
8. **User reviews written spec** — ask user to review the spec file before proceeding
9. **Transition to implementation** — invoke writing-plans skill to create implementation plan
## Process Flow
```dot
digraph brainstorming {
"Explore project context" [shape=box];
"Visual questions ahead?" [shape=diamond];
"Offer Visual Companion\n(own message, no other content)" [shape=box];
"Ask clarifying questions" [shape=box];
"Propose 2-3 approaches" [shape=box];
"Present design sections" [shape=box];
"User approves design?" [shape=diamond];
"Write design doc" [shape=box];
"Spec review loop" [shape=box];
"Spec review passed?" [shape=diamond];
"User reviews spec?" [shape=diamond];
"Invoke writing-plans skill" [shape=doublecircle];
"Explore project context" -> "Visual questions ahead?";
"Visual questions ahead?" -> "Offer Visual Companion\n(own message, no other content)" [label="yes"];
"Visual questions ahead?" -> "Ask clarifying questions" [label="no"];
"Offer Visual Companion\n(own message, no other content)" -> "Ask clarifying questions";
"Ask clarifying questions" -> "Propose 2-3 approaches";
"Propose 2-3 approaches" -> "Present design sections";
"Present design sections" -> "User approves design?";
"User approves design?" -> "Present design sections" [label="no, revise"];
"User approves design?" -> "Write design doc" [label="yes"];
"Write design doc" -> "Spec review loop";
"Spec review loop" -> "Spec review passed?";
"Spec review passed?" -> "Spec review loop" [label="issues found,\nfix and re-dispatch"];
"Spec review passed?" -> "User reviews spec?" [label="approved"];
"User reviews spec?" -> "Write design doc" [label="changes requested"];
"User reviews spec?" -> "Invoke writing-plans skill" [label="approved"];
}
```
**The terminal state is invoking writing-plans.** Do NOT invoke frontend-design, mcp-builder, or any other implementation skill. The ONLY skill you invoke after brainstorming is writing-plans.
## The Process
**Understanding the idea:**
- Check out the current project state first (files, docs, recent commits)
- Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first.
- If the project is too large for a single spec, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order should they be built? Then brainstorm the first sub-project through the normal design flow. Each sub-project gets its own spec → plan → implementation cycle.
- For appropriately-scoped projects, ask questions one at a time to refine the idea
- Prefer multiple choice questions when possible, but open-ended is fine too
- Only one question per message - if a topic needs more exploration, break it into multiple questions
- Focus on understanding: purpose, constraints, success criteria
**Exploring approaches:**
- Propose 2-3 different approaches with trade-offs
- Present options conversationally with your recommendation and reasoning
- Lead with your recommended option and explain why
**Presenting the design:**
- Once you believe you understand what you're building, present the design
- Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
- Ask after each section whether it looks right so far
- Cover: architecture, components, data flow, error handling, testing
- Be ready to go back and clarify if something doesn't make sense
**Design for isolation and clarity:**
- Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently
- For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on?
- Can someone understand what a unit does without reading its internals? Can you change the internals without breaking consumers? If not, the boundaries need work.
- Smaller, well-bounded units are also easier for you to work with - you reason better about code you can hold in context at once, and your edits are more reliable when files are focused. When a file grows large, that's often a signal that it's doing too much.
**Working in existing codebases:**
- Explore the current structure before proposing changes. Follow existing patterns.
- Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design - the way a good developer improves code they're working in.
- Don't propose unrelated refactoring. Stay focused on what serves the current goal.
## After the Design
**Documentation:**
- Write the validated design (spec) to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
- (User preferences for spec location override this default)
- Use elements-of-style:writing-clearly-and-concisely skill if available
- Commit the design document to git
**Spec Review Loop:**
After writing the spec document:
1. Dispatch spec-document-reviewer subagent (see spec-document-reviewer-prompt.md)
2. If Issues Found: fix, re-dispatch, repeat until Approved
3. If loop exceeds 3 iterations, surface to human for guidance
**User Review Gate:**
After the spec review loop passes, ask the user to review the written spec before proceeding:
> "Spec written and committed to `<path>`. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."
Wait for the user's response. If they request changes, make them and re-run the spec review loop. Only proceed once the user approves.
**Implementation:**
- Invoke the writing-plans skill to create a detailed implementation plan
- Do NOT invoke any other skill. writing-plans is the next step.
## Key Principles
- **One question at a time** - Don't overwhelm with multiple questions
- **Multiple choice preferred** - Easier to answer than open-ended when possible
- **YAGNI ruthlessly** - Remove unnecessary features from all designs
- **Explore alternatives** - Always propose 2-3 approaches before settling
- **Incremental validation** - Present design, get approval before moving on
- **Be flexible** - Go back and clarify when something doesn't make sense
## Visual Companion
A browser-based companion for showing mockups, diagrams, and visual options during brainstorming. Available as a tool — not a mode. Accepting the companion means it's available for questions that benefit from visual treatment; it does NOT mean every question goes through the browser.
**Offering the companion:** When you anticipate that upcoming questions will involve visual content (mockups, layouts, diagrams), offer it once for consent:
> "Some of what we're working on might be easier to explain if I can show it to you in a web browser. I can put together mockups, diagrams, comparisons, and other visuals as we go. This feature is still new and can be token-intensive. Want to try it? (Requires opening a local URL)"
**This offer MUST be its own message.** Do not combine it with clarifying questions, context summaries, or any other content. The message should contain ONLY the offer above and nothing else. Wait for the user's response before continuing. If they decline, proceed with text-only brainstorming.
**Per-question decision:** Even after the user accepts, decide FOR EACH QUESTION whether to use the browser or the terminal. The test: **would the user understand this better by seeing it than reading it?**
- **Use the browser** for content that IS visual — mockups, wireframes, layout comparisons, architecture diagrams, side-by-side visual designs
- **Use the terminal** for content that is text — requirements questions, conceptual choices, tradeoff lists, A/B/C/D text options, scope decisions
A question about a UI topic is not automatically a visual question. "What does personality mean in this context?" is a conceptual question — use the terminal. "Which wizard layout works better?" is a visual question — use the browser.
If they agree to the companion, read the detailed guide before proceeding:
`skills/brainstorming/visual-companion.md`

214
.config/opencode/skills/brainstorming/scripts/frame-template.html Normal file
View File

@@ -0,0 +1,214 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Superpowers Brainstorming</title>
<style>
/*
* BRAINSTORM COMPANION FRAME TEMPLATE
*
* This template provides a consistent frame with:
* - OS-aware light/dark theming
* - Fixed header and selection indicator bar
* - Scrollable main content area
* - CSS helpers for common UI patterns
*
* Content is injected via placeholder comment in #claude-content.
*/
* { box-sizing: border-box; margin: 0; padding: 0; }
html, body { height: 100%; overflow: hidden; }
/* ===== THEME VARIABLES ===== */
:root {
--bg-primary: #f5f5f7;
--bg-secondary: #ffffff;
--bg-tertiary: #e5e5e7;
--border: #d1d1d6;
--text-primary: #1d1d1f;
--text-secondary: #86868b;
--text-tertiary: #aeaeb2;
--accent: #0071e3;
--accent-hover: #0077ed;
--success: #34c759;
--warning: #ff9f0a;
--error: #ff3b30;
--selected-bg: #e8f4fd;
--selected-border: #0071e3;
}
@media (prefers-color-scheme: dark) {
:root {
--bg-primary: #1d1d1f;
--bg-secondary: #2d2d2f;
--bg-tertiary: #3d3d3f;
--border: #424245;
--text-primary: #f5f5f7;
--text-secondary: #86868b;
--text-tertiary: #636366;
--accent: #0a84ff;
--accent-hover: #409cff;
--selected-bg: rgba(10, 132, 255, 0.15);
--selected-border: #0a84ff;
}
}
body {
font-family: system-ui, -apple-system, BlinkMacSystemFont, sans-serif;
background: var(--bg-primary);
color: var(--text-primary);
display: flex;
flex-direction: column;
line-height: 1.5;
}
/* ===== FRAME STRUCTURE ===== */
.header {
background: var(--bg-secondary);
padding: 0.5rem 1.5rem;
display: flex;
justify-content: space-between;
align-items: center;
border-bottom: 1px solid var(--border);
flex-shrink: 0;
}
.header h1 { font-size: 0.85rem; font-weight: 500; color: var(--text-secondary); }
.header .status { font-size: 0.7rem; color: var(--success); display: flex; align-items: center; gap: 0.4rem; }
.header .status::before { content: ''; width: 6px; height: 6px; background: var(--success); border-radius: 50%; }
.main { flex: 1; overflow-y: auto; }
#claude-content { padding: 2rem; min-height: 100%; }
.indicator-bar {
background: var(--bg-secondary);
border-top: 1px solid var(--border);
padding: 0.5rem 1.5rem;
flex-shrink: 0;
text-align: center;
}
.indicator-bar span {
font-size: 0.75rem;
color: var(--text-secondary);
}
.indicator-bar .selected-text {
color: var(--accent);
font-weight: 500;
}
/* ===== TYPOGRAPHY ===== */
h2 { font-size: 1.5rem; font-weight: 600; margin-bottom: 0.5rem; }
h3 { font-size: 1.1rem; font-weight: 600; margin-bottom: 0.25rem; }
.subtitle { color: var(--text-secondary); margin-bottom: 1.5rem; }
.section { margin-bottom: 2rem; }
.label { font-size: 0.7rem; color: var(--text-secondary); text-transform: uppercase; letter-spacing: 0.05em; margin-bottom: 0.5rem; }
/* ===== OPTIONS (for A/B/C choices) ===== */
.options { display: flex; flex-direction: column; gap: 0.75rem; }
.option {
background: var(--bg-secondary);
border: 2px solid var(--border);
border-radius: 12px;
padding: 1rem 1.25rem;
cursor: pointer;
transition: all 0.15s ease;
display: flex;
align-items: flex-start;
gap: 1rem;
}
.option:hover { border-color: var(--accent); }
.option.selected { background: var(--selected-bg); border-color: var(--selected-border); }
.option .letter {
background: var(--bg-tertiary);
color: var(--text-secondary);
width: 1.75rem; height: 1.75rem;
border-radius: 6px;
display: flex; align-items: center; justify-content: center;
font-weight: 600; font-size: 0.85rem; flex-shrink: 0;
}
.option.selected .letter { background: var(--accent); color: white; }
.option .content { flex: 1; }
.option .content h3 { font-size: 0.95rem; margin-bottom: 0.15rem; }
.option .content p { color: var(--text-secondary); font-size: 0.85rem; margin: 0; }
/* ===== CARDS (for showing designs/mockups) ===== */
.cards { display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: 1rem; }
.card {
background: var(--bg-secondary);
border: 1px solid var(--border);
border-radius: 12px;
overflow: hidden;
cursor: pointer;
transition: all 0.15s ease;
}
.card:hover { border-color: var(--accent); transform: translateY(-2px); box-shadow: 0 4px 12px rgba(0,0,0,0.1); }
.card.selected { border-color: var(--selected-border); border-width: 2px; }
.card-image { background: var(--bg-tertiary); aspect-ratio: 16/10; display: flex; align-items: center; justify-content: center; }
.card-body { padding: 1rem; }
.card-body h3 { margin-bottom: 0.25rem; }
.card-body p { color: var(--text-secondary); font-size: 0.85rem; }
/* ===== MOCKUP CONTAINER ===== */
.mockup {
background: var(--bg-secondary);
border: 1px solid var(--border);
border-radius: 12px;
overflow: hidden;
margin-bottom: 1.5rem;
}
.mockup-header {
background: var(--bg-tertiary);
padding: 0.5rem 1rem;
font-size: 0.75rem;
color: var(--text-secondary);
border-bottom: 1px solid var(--border);
}
.mockup-body { padding: 1.5rem; }
/* ===== SPLIT VIEW (side-by-side comparison) ===== */
.split { display: grid; grid-template-columns: 1fr 1fr; gap: 1.5rem; }
@media (max-width: 700px) { .split { grid-template-columns: 1fr; } }
/* ===== PROS/CONS ===== */
.pros-cons { display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; margin: 1rem 0; }
.pros, .cons { background: var(--bg-secondary); border-radius: 8px; padding: 1rem; }
.pros h4 { color: var(--success); font-size: 0.85rem; margin-bottom: 0.5rem; }
.cons h4 { color: var(--error); font-size: 0.85rem; margin-bottom: 0.5rem; }
.pros ul, .cons ul { margin-left: 1.25rem; font-size: 0.85rem; color: var(--text-secondary); }
.pros li, .cons li { margin-bottom: 0.25rem; }
/* ===== PLACEHOLDER (for mockup areas) ===== */
.placeholder {
background: var(--bg-tertiary);
border: 2px dashed var(--border);
border-radius: 8px;
padding: 2rem;
text-align: center;
color: var(--text-tertiary);
}
/* ===== INLINE MOCKUP ELEMENTS ===== */
.mock-nav { background: var(--accent); color: white; padding: 0.75rem 1rem; display: flex; gap: 1.5rem; font-size: 0.9rem; }
.mock-sidebar { background: var(--bg-tertiary); padding: 1rem; min-width: 180px; }
.mock-content { padding: 1.5rem; flex: 1; }
.mock-button { background: var(--accent); color: white; border: none; padding: 0.5rem 1rem; border-radius: 6px; font-size: 0.85rem; }
.mock-input { background: var(--bg-primary); border: 1px solid var(--border); border-radius: 6px; padding: 0.5rem; width: 100%; }
</style>
</head>
<body>
<div class="header">
<h1><a href="https://github.com/obra/superpowers" style="color: inherit; text-decoration: none;">Superpowers Brainstorming</a></h1>
<div class="status">Connected</div>
</div>
<div class="main">
<div id="claude-content">
<!-- CONTENT -->
</div>
</div>
<div class="indicator-bar">
<span id="indicator-text">Click an option above, then return to the terminal</span>
</div>
</body>
</html>

88
.config/opencode/skills/brainstorming/scripts/helper.js Normal file
View File

@@ -0,0 +1,88 @@
(function() {
const WS_URL = 'ws://' + window.location.host;
let ws = null;
let eventQueue = [];
function connect() {
ws = new WebSocket(WS_URL);
ws.onopen = () => {
eventQueue.forEach(e => ws.send(JSON.stringify(e)));
eventQueue = [];
};
ws.onmessage = (msg) => {
const data = JSON.parse(msg.data);
if (data.type === 'reload') {
window.location.reload();
}
};
ws.onclose = () => {
setTimeout(connect, 1000);
};
}
function sendEvent(event) {
event.timestamp = Date.now();
if (ws && ws.readyState === WebSocket.OPEN) {
ws.send(JSON.stringify(event));
} else {
eventQueue.push(event);
}
}
// Capture clicks on choice elements
document.addEventListener('click', (e) => {
const target = e.target.closest('[data-choice]');
if (!target) return;
sendEvent({
type: 'click',
text: target.textContent.trim(),
choice: target.dataset.choice,
id: target.id || null
});
// Update indicator bar (defer so toggleSelect runs first)
setTimeout(() => {
const indicator = document.getElementById('indicator-text');
if (!indicator) return;
const container = target.closest('.options') || target.closest('.cards');
const selected = container ? container.querySelectorAll('.selected') : [];
if (selected.length === 0) {
indicator.textContent = 'Click an option above, then return to the terminal';
} else if (selected.length === 1) {
const label = selected[0].querySelector('h3, .content h3, .card-body h3')?.textContent?.trim() || selected[0].dataset.choice;
indicator.innerHTML = '<span class="selected-text">' + label + ' selected</span> — return to terminal to continue';
} else {
indicator.innerHTML = '<span class="selected-text">' + selected.length + ' selected</span> — return to terminal to continue';
}
}, 0);
});
// Frame UI: selection tracking
window.selectedChoice = null;
window.toggleSelect = function(el) {
const container = el.closest('.options') || el.closest('.cards');
const multi = container && container.dataset.multiselect !== undefined;
if (container && !multi) {
container.querySelectorAll('.option, .card').forEach(o => o.classList.remove('selected'));
}
if (multi) {
el.classList.toggle('selected');
} else {
el.classList.add('selected');
}
window.selectedChoice = el.dataset.choice;
};
// Expose API for explicit use
window.brainstorm = {
send: sendEvent,
choice: (value, metadata = {}) => sendEvent({ type: 'choice', value, ...metadata })
};
connect();
})();

338
.config/opencode/skills/brainstorming/scripts/server.cjs Normal file
View File

@@ -0,0 +1,338 @@
const crypto = require('crypto');
const http = require('http');
const fs = require('fs');
const path = require('path');
// ========== WebSocket Protocol (RFC 6455) ==========
const OPCODES = { TEXT: 0x01, CLOSE: 0x08, PING: 0x09, PONG: 0x0A };
const WS_MAGIC = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
function computeAcceptKey(clientKey) {
return crypto.createHash('sha1').update(clientKey + WS_MAGIC).digest('base64');
}
function encodeFrame(opcode, payload) {
const fin = 0x80;
const len = payload.length;
let header;
if (len < 126) {
header = Buffer.alloc(2);
header[0] = fin | opcode;
header[1] = len;
} else if (len < 65536) {
header = Buffer.alloc(4);
header[0] = fin | opcode;
header[1] = 126;
header.writeUInt16BE(len, 2);
} else {
header = Buffer.alloc(10);
header[0] = fin | opcode;
header[1] = 127;
header.writeBigUInt64BE(BigInt(len), 2);
}
return Buffer.concat([header, payload]);
}
function decodeFrame(buffer) {
if (buffer.length < 2) return null;
const secondByte = buffer[1];
const opcode = buffer[0] & 0x0F;
const masked = (secondByte & 0x80) !== 0;
let payloadLen = secondByte & 0x7F;
let offset = 2;
if (!masked) throw new Error('Client frames must be masked');
if (payloadLen === 126) {
if (buffer.length < 4) return null;
payloadLen = buffer.readUInt16BE(2);
offset = 4;
} else if (payloadLen === 127) {
if (buffer.length < 10) return null;
payloadLen = Number(buffer.readBigUInt64BE(2));
offset = 10;
}
const maskOffset = offset;
const dataOffset = offset + 4;
const totalLen = dataOffset + payloadLen;
if (buffer.length < totalLen) return null;
const mask = buffer.slice(maskOffset, dataOffset);
const data = Buffer.alloc(payloadLen);
for (let i = 0; i < payloadLen; i++) {
data[i] = buffer[dataOffset + i] ^ mask[i % 4];
}
return { opcode, payload: data, bytesConsumed: totalLen };
}
// ========== Configuration ==========
const PORT = process.env.BRAINSTORM_PORT || (49152 + Math.floor(Math.random() * 16383));
const HOST = process.env.BRAINSTORM_HOST || '127.0.0.1';
const URL_HOST = process.env.BRAINSTORM_URL_HOST || (HOST === '127.0.0.1' ? 'localhost' : HOST);
const SCREEN_DIR = process.env.BRAINSTORM_DIR || '/tmp/brainstorm';
const OWNER_PID = process.env.BRAINSTORM_OWNER_PID ? Number(process.env.BRAINSTORM_OWNER_PID) : null;
const MIME_TYPES = {
'.html': 'text/html', '.css': 'text/css', '.js': 'application/javascript',
'.json': 'application/json', '.png': 'image/png', '.jpg': 'image/jpeg',
'.jpeg': 'image/jpeg', '.gif': 'image/gif', '.svg': 'image/svg+xml'
};
// ========== Templates and Constants ==========
const WAITING_PAGE = `<!DOCTYPE html>
<html>
<head><meta charset="utf-8"><title>Brainstorm Companion</title>
<style>body { font-family: system-ui, sans-serif; padding: 2rem; max-width: 800px; margin: 0 auto; }
h1 { color: #333; } p { color: #666; }</style>
</head>
<body><h1>Brainstorm Companion</h1>
<p>Waiting for the agent to push a screen...</p></body></html>`;
const frameTemplate = fs.readFileSync(path.join(__dirname, 'frame-template.html'), 'utf-8');
const helperScript = fs.readFileSync(path.join(__dirname, 'helper.js'), 'utf-8');
const helperInjection = '<script>\n' + helperScript + '\n</script>';
// ========== Helper Functions ==========
function isFullDocument(html) {
const trimmed = html.trimStart().toLowerCase();
return trimmed.startsWith('<!doctype') || trimmed.startsWith('<html');
}
function wrapInFrame(content) {
return frameTemplate.replace('<!-- CONTENT -->', content);
}
function getNewestScreen() {
const files = fs.readdirSync(SCREEN_DIR)
.filter(f => f.endsWith('.html'))
.map(f => {
const fp = path.join(SCREEN_DIR, f);
return { path: fp, mtime: fs.statSync(fp).mtime.getTime() };
})
.sort((a, b) => b.mtime - a.mtime);
return files.length > 0 ? files[0].path : null;
}
// ========== HTTP Request Handler ==========
function handleRequest(req, res) {
touchActivity();
if (req.method === 'GET' && req.url === '/') {
const screenFile = getNewestScreen();
let html = screenFile
? (raw => isFullDocument(raw) ? raw : wrapInFrame(raw))(fs.readFileSync(screenFile, 'utf-8'))
: WAITING_PAGE;
if (html.includes('</body>')) {
html = html.replace('</body>', helperInjection + '\n</body>');
} else {
html += helperInjection;
}
res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
res.end(html);
} else if (req.method === 'GET' && req.url.startsWith('/files/')) {
const fileName = req.url.slice(7);
const filePath = path.join(SCREEN_DIR, path.basename(fileName));
if (!fs.existsSync(filePath)) {
res.writeHead(404);
res.end('Not found');
return;
}
const ext = path.extname(filePath).toLowerCase();
const contentType = MIME_TYPES[ext] || 'application/octet-stream';
res.writeHead(200, { 'Content-Type': contentType });
res.end(fs.readFileSync(filePath));
} else {
res.writeHead(404);
res.end('Not found');
}
}
// ========== WebSocket Connection Handling ==========
const clients = new Set();
function handleUpgrade(req, socket) {
const key = req.headers['sec-websocket-key'];
if (!key) { socket.destroy(); return; }
const accept = computeAcceptKey(key);
socket.write(
'HTTP/1.1 101 Switching Protocols\r\n' +
'Upgrade: websocket\r\n' +
'Connection: Upgrade\r\n' +
'Sec-WebSocket-Accept: ' + accept + '\r\n\r\n'
);
let buffer = Buffer.alloc(0);
clients.add(socket);
socket.on('data', (chunk) => {
buffer = Buffer.concat([buffer, chunk]);
while (buffer.length > 0) {
let result;
try {
result = decodeFrame(buffer);
} catch (e) {
socket.end(encodeFrame(OPCODES.CLOSE, Buffer.alloc(0)));
clients.delete(socket);
return;
}
if (!result) break;
buffer = buffer.slice(result.bytesConsumed);
switch (result.opcode) {
case OPCODES.TEXT:
handleMessage(result.payload.toString());
break;
case OPCODES.CLOSE:
socket.end(encodeFrame(OPCODES.CLOSE, Buffer.alloc(0)));
clients.delete(socket);
return;
case OPCODES.PING:
socket.write(encodeFrame(OPCODES.PONG, result.payload));
break;
case OPCODES.PONG:
break;
default: {
const closeBuf = Buffer.alloc(2);
closeBuf.writeUInt16BE(1003);
socket.end(encodeFrame(OPCODES.CLOSE, closeBuf));
clients.delete(socket);
return;
}
}
}
});
socket.on('close', () => clients.delete(socket));
socket.on('error', () => clients.delete(socket));
}
function handleMessage(text) {
let event;
try {
event = JSON.parse(text);
} catch (e) {
console.error('Failed to parse WebSocket message:', e.message);
return;
}
touchActivity();
console.log(JSON.stringify({ source: 'user-event', ...event }));
if (event.choice) {
const eventsFile = path.join(SCREEN_DIR, '.events');
fs.appendFileSync(eventsFile, JSON.stringify(event) + '\n');
}
}
function broadcast(msg) {
const frame = encodeFrame(OPCODES.TEXT, Buffer.from(JSON.stringify(msg)));
for (const socket of clients) {
try { socket.write(frame); } catch (e) { clients.delete(socket); }
}
}
// ========== Activity Tracking ==========
const IDLE_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
let lastActivity = Date.now();
function touchActivity() {
lastActivity = Date.now();
}
// ========== File Watching ==========
const debounceTimers = new Map();
// ========== Server Startup ==========
function startServer() {
if (!fs.existsSync(SCREEN_DIR)) fs.mkdirSync(SCREEN_DIR, { recursive: true });
// Track known files to distinguish new screens from updates.
// macOS fs.watch reports 'rename' for both new files and overwrites,
// so we can't rely on eventType alone.
const knownFiles = new Set(
fs.readdirSync(SCREEN_DIR).filter(f => f.endsWith('.html'))
);
const server = http.createServer(handleRequest);
server.on('upgrade', handleUpgrade);
const watcher = fs.watch(SCREEN_DIR, (eventType, filename) => {
if (!filename || !filename.endsWith('.html')) return;
if (debounceTimers.has(filename)) clearTimeout(debounceTimers.get(filename));
debounceTimers.set(filename, setTimeout(() => {
debounceTimers.delete(filename);
const filePath = path.join(SCREEN_DIR, filename);
if (!fs.existsSync(filePath)) return; // file was deleted
touchActivity();
if (!knownFiles.has(filename)) {
knownFiles.add(filename);
const eventsFile = path.join(SCREEN_DIR, '.events');
if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile);
console.log(JSON.stringify({ type: 'screen-added', file: filePath }));
} else {
console.log(JSON.stringify({ type: 'screen-updated', file: filePath }));
}
broadcast({ type: 'reload' });
}, 100));
});
watcher.on('error', (err) => console.error('fs.watch error:', err.message));
function shutdown(reason) {
console.log(JSON.stringify({ type: 'server-stopped', reason }));
const infoFile = path.join(SCREEN_DIR, '.server-info');
if (fs.existsSync(infoFile)) fs.unlinkSync(infoFile);
fs.writeFileSync(
path.join(SCREEN_DIR, '.server-stopped'),
JSON.stringify({ reason, timestamp: Date.now() }) + '\n'
);
watcher.close();
clearInterval(lifecycleCheck);
server.close(() => process.exit(0));
}
function ownerAlive() {
if (!OWNER_PID) return true;
try { process.kill(OWNER_PID, 0); return true; } catch (e) { return false; }
}
// Check every 60s: exit if owner process died or idle for 30 minutes
const lifecycleCheck = setInterval(() => {
if (!ownerAlive()) shutdown('owner process exited');
else if (Date.now() - lastActivity > IDLE_TIMEOUT_MS) shutdown('idle timeout');
}, 60 * 1000);
lifecycleCheck.unref();
server.listen(PORT, HOST, () => {
const info = JSON.stringify({
type: 'server-started', port: Number(PORT), host: HOST,
url_host: URL_HOST, url: 'http://' + URL_HOST + ':' + PORT,
screen_dir: SCREEN_DIR
});
console.log(info);
fs.writeFileSync(path.join(SCREEN_DIR, '.server-info'), info + '\n');
});
}
if (require.main === module) {
startServer();
}
module.exports = { computeAcceptKey, encodeFrame, decodeFrame, OPCODES };

153
.config/opencode/skills/brainstorming/scripts/start-server.sh Executable file
View File

@@ -0,0 +1,153 @@
#!/usr/bin/env bash
# Start the brainstorm server and output connection info
# Usage: start-server.sh [--project-dir <path>] [--host <bind-host>] [--url-host <display-host>] [--foreground] [--background]
#
# Starts server on a random high port, outputs JSON with URL.
# Each session gets its own directory to avoid conflicts.
#
# Options:
# --project-dir <path> Store session files under <path>/.superpowers/brainstorm/
# instead of /tmp. Files persist after server stops.
# --host <bind-host> Host/interface to bind (default: 127.0.0.1).
# Use 0.0.0.0 in remote/containerized environments.
# --url-host <host> Hostname shown in returned URL JSON.
# --foreground Run server in the current terminal (no backgrounding).
# --background Force background mode (overrides Codex auto-foreground).
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
# Parse arguments
PROJECT_DIR=""
FOREGROUND="false"
FORCE_BACKGROUND="false"
BIND_HOST="127.0.0.1"
URL_HOST=""
while [[ $# -gt 0 ]]; do
case "$1" in
--project-dir)
PROJECT_DIR="$2"
shift 2
;;
--host)
BIND_HOST="$2"
shift 2
;;
--url-host)
URL_HOST="$2"
shift 2
;;
--foreground|--no-daemon)
FOREGROUND="true"
shift
;;
--background|--daemon)
FORCE_BACKGROUND="true"
shift
;;
*)
echo "{\"error\": \"Unknown argument: $1\"}"
exit 1
;;
esac
done
if [[ -z "$URL_HOST" ]]; then
if [[ "$BIND_HOST" == "127.0.0.1" || "$BIND_HOST" == "localhost" ]]; then
URL_HOST="localhost"
else
URL_HOST="$BIND_HOST"
fi
fi
# Some environments reap detached/background processes. Auto-foreground when detected.
if [[ -n "${CODEX_CI:-}" && "$FOREGROUND" != "true" && "$FORCE_BACKGROUND" != "true" ]]; then
FOREGROUND="true"
fi
# Windows/Git Bash reaps nohup background processes. Auto-foreground when detected.
if [[ "$FOREGROUND" != "true" && "$FORCE_BACKGROUND" != "true" ]]; then
case "${OSTYPE:-}" in
msys*|cygwin*|mingw*) FOREGROUND="true" ;;
esac
if [[ -n "${MSYSTEM:-}" ]]; then
FOREGROUND="true"
fi
fi
# Generate unique session directory
SESSION_ID="$$-$(date +%s)"
if [[ -n "$PROJECT_DIR" ]]; then
SCREEN_DIR="${PROJECT_DIR}/.superpowers/brainstorm/${SESSION_ID}"
else
SCREEN_DIR="/tmp/brainstorm-${SESSION_ID}"
fi
PID_FILE="${SCREEN_DIR}/.server.pid"
LOG_FILE="${SCREEN_DIR}/.server.log"
# Create fresh session directory
mkdir -p "$SCREEN_DIR"
# Kill any existing server
if [[ -f "$PID_FILE" ]]; then
old_pid=$(cat "$PID_FILE")
kill "$old_pid" 2>/dev/null
rm -f "$PID_FILE"
fi
cd "$SCRIPT_DIR"
# Resolve the harness PID (grandparent of this script).
# $PPID is the ephemeral shell the harness spawned to run us — it dies
# when this script exits. The harness itself is $PPID's parent.
OWNER_PID="$(ps -o ppid= -p "$PPID" 2>/dev/null | tr -d ' ')"
if [[ -z "$OWNER_PID" || "$OWNER_PID" == "1" ]]; then
OWNER_PID="$PPID"
fi
# On Windows/MSYS2, the MSYS2 PID namespace is invisible to Node.js.
# Skip owner-PID monitoring — the 30-minute idle timeout prevents orphans.
case "${OSTYPE:-}" in
msys*|cygwin*|mingw*) OWNER_PID="" ;;
esac
# Foreground mode for environments that reap detached/background processes.
if [[ "$FOREGROUND" == "true" ]]; then
echo "$$" > "$PID_FILE"
env BRAINSTORM_DIR="$SCREEN_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" BRAINSTORM_OWNER_PID="$OWNER_PID" node server.cjs
exit $?
fi
# Start server, capturing output to log file
# Use nohup to survive shell exit; disown to remove from job table
nohup env BRAINSTORM_DIR="$SCREEN_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" BRAINSTORM_OWNER_PID="$OWNER_PID" node server.cjs > "$LOG_FILE" 2>&1 &
SERVER_PID=$!
disown "$SERVER_PID" 2>/dev/null
echo "$SERVER_PID" > "$PID_FILE"
# Wait for server-started message (check log file)
for i in {1..50}; do
if grep -q "server-started" "$LOG_FILE" 2>/dev/null; then
# Verify server is still alive after a short window (catches process reapers)
alive="true"
for _ in {1..20}; do
if ! kill -0 "$SERVER_PID" 2>/dev/null; then
alive="false"
break
fi
sleep 0.1
done
if [[ "$alive" != "true" ]]; then
echo "{\"error\": \"Server started but was killed. Retry in a persistent terminal with: $SCRIPT_DIR/start-server.sh${PROJECT_DIR:+ --project-dir $PROJECT_DIR} --host $BIND_HOST --url-host $URL_HOST --foreground\"}"
exit 1
fi
grep "server-started" "$LOG_FILE" | head -1
exit 0
fi
sleep 0.1
done
# Timeout - server didn't start
echo '{"error": "Server failed to start within 5 seconds"}'
exit 1

55
.config/opencode/skills/brainstorming/scripts/stop-server.sh Executable file
View File

@@ -0,0 +1,55 @@
#!/usr/bin/env bash
# Stop the brainstorm server and clean up
# Usage: stop-server.sh <screen_dir>
#
# Kills the server process. Only deletes session directory if it's
# under /tmp (ephemeral). Persistent directories (.superpowers/) are
# kept so mockups can be reviewed later.
SCREEN_DIR="$1"
if [[ -z "$SCREEN_DIR" ]]; then
echo '{"error": "Usage: stop-server.sh <screen_dir>"}'
exit 1
fi
PID_FILE="${SCREEN_DIR}/.server.pid"
if [[ -f "$PID_FILE" ]]; then
pid=$(cat "$PID_FILE")
# Try to stop gracefully, fallback to force if still alive
kill "$pid" 2>/dev/null || true
# Wait for graceful shutdown (up to ~2s)
for i in {1..20}; do
if ! kill -0 "$pid" 2>/dev/null; then
break
fi
sleep 0.1
done
# If still running, escalate to SIGKILL
if kill -0 "$pid" 2>/dev/null; then
kill -9 "$pid" 2>/dev/null || true
# Give SIGKILL a moment to take effect
sleep 0.1
fi
if kill -0 "$pid" 2>/dev/null; then
echo '{"status": "failed", "error": "process still running"}'
exit 1
fi
rm -f "$PID_FILE" "${SCREEN_DIR}/.server.log"
# Only delete ephemeral /tmp directories
if [[ "$SCREEN_DIR" == /tmp/* ]]; then
rm -rf "$SCREEN_DIR"
fi
echo '{"status": "stopped"}'
else
echo '{"status": "not_running"}'
fi

49
.config/opencode/skills/brainstorming/spec-document-reviewer-prompt.md Normal file
View File

@@ -0,0 +1,49 @@
# Spec Document Reviewer Prompt Template
Use this template when dispatching a spec document reviewer subagent.
**Purpose:** Verify the spec is complete, consistent, and ready for implementation planning.
**Dispatch after:** Spec document is written to docs/superpowers/specs/
```
Task tool (general-purpose):
description: "Review spec document"
prompt: |
You are a spec document reviewer. Verify this spec is complete and ready for planning.
**Spec to review:** [SPEC_FILE_PATH]
## What to Check
| Category | What to Look For |
|----------|------------------|
| Completeness | TODOs, placeholders, "TBD", incomplete sections |
| Consistency | Internal contradictions, conflicting requirements |
| Clarity | Requirements ambiguous enough to cause someone to build the wrong thing |
| Scope | Focused enough for a single plan — not covering multiple independent subsystems |
| YAGNI | Unrequested features, over-engineering |
## Calibration
**Only flag issues that would cause real problems during implementation planning.**
A missing section, a contradiction, or a requirement so ambiguous it could be
interpreted two different ways — those are issues. Minor wording improvements,
stylistic preferences, and "sections less detailed than others" are not.
Approve unless there are serious gaps that would lead to a flawed plan.
## Output Format
## Spec Review
**Status:** Approved | Issues Found
**Issues (if any):**
- [Section X]: [specific issue] - [why it matters for planning]
**Recommendations (advisory, do not block approval):**
- [suggestions for improvement]
```
**Reviewer returns:** Status, Issues (if any), Recommendations

286
.config/opencode/skills/brainstorming/visual-companion.md Normal file
View File

@@ -0,0 +1,286 @@
# Visual Companion Guide
Browser-based visual brainstorming companion for showing mockups, diagrams, and options.
## When to Use
Decide per-question, not per-session. The test: **would the user understand this better by seeing it than reading it?**
**Use the browser** when the content itself is visual:
- **UI mockups** — wireframes, layouts, navigation structures, component designs
- **Architecture diagrams** — system components, data flow, relationship maps
- **Side-by-side visual comparisons** — comparing two layouts, two color schemes, two design directions
- **Design polish** — when the question is about look and feel, spacing, visual hierarchy
- **Spatial relationships** — state machines, flowcharts, entity relationships rendered as diagrams
**Use the terminal** when the content is text or tabular:
- **Requirements and scope questions** — "what does X mean?", "which features are in scope?"
- **Conceptual A/B/C choices** — picking between approaches described in words
- **Tradeoff lists** — pros/cons, comparison tables
- **Technical decisions** — API design, data modeling, architectural approach selection
- **Clarifying questions** — anything where the answer is words, not a visual preference
A question *about* a UI topic is not automatically a visual question. "What kind of wizard do you want?" is conceptual — use the terminal. "Which of these wizard layouts feels right?" is visual — use the browser.
## How It Works
The server watches a directory for HTML files and serves the newest one to the browser. You write HTML content, the user sees it in their browser and can click to select options. Selections are recorded to a `.events` file that you read on your next turn.
**Content fragments vs full documents:** If your HTML file starts with `<!DOCTYPE` or `<html`, the server serves it as-is (just injects the helper script). Otherwise, the server automatically wraps your content in the frame template — adding the header, CSS theme, selection indicator, and all interactive infrastructure. **Write content fragments by default.** Only write full documents when you need complete control over the page.
## Starting a Session
```bash
# Start server with persistence (mockups saved to project)
scripts/start-server.sh --project-dir /path/to/project
# Returns: {"type":"server-started","port":52341,"url":"http://localhost:52341",
# "screen_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000"}
```
Save `screen_dir` from the response. Tell user to open the URL.
**Finding connection info:** The server writes its startup JSON to `$SCREEN_DIR/.server-info`. If you launched the server in the background and didn't capture stdout, read that file to get the URL and port. When using `--project-dir`, check `<project>/.superpowers/brainstorm/` for the session directory.
**Note:** Pass the project root as `--project-dir` so mockups persist in `.superpowers/brainstorm/` and survive server restarts. Without it, files go to `/tmp` and get cleaned up. Remind the user to add `.superpowers/` to `.gitignore` if it's not already there.
**Launching the server by platform:**
**Claude Code (macOS / Linux):**
```bash
# Default mode works — the script backgrounds the server itself
scripts/start-server.sh --project-dir /path/to/project
```
**Claude Code (Windows):**
```bash
# Windows auto-detects and uses foreground mode, which blocks the tool call.
# Use run_in_background: true on the Bash tool call so the server survives
# across conversation turns.
scripts/start-server.sh --project-dir /path/to/project
```
When calling this via the Bash tool, set `run_in_background: true`. Then read `$SCREEN_DIR/.server-info` on the next turn to get the URL and port.
**Codex:**
```bash
# Codex reaps background processes. The script auto-detects CODEX_CI and
# switches to foreground mode. Run it normally — no extra flags needed.
scripts/start-server.sh --project-dir /path/to/project
```
**Gemini CLI:**
```bash
# Use --foreground and set is_background: true on your shell tool call
# so the process survives across turns
scripts/start-server.sh --project-dir /path/to/project --foreground
```
**Other environments:** The server must keep running in the background across conversation turns. If your environment reaps detached processes, use `--foreground` and launch the command with your platform's background execution mechanism.
If the URL is unreachable from your browser (common in remote/containerized setups), bind a non-loopback host:
```bash
scripts/start-server.sh \
--project-dir /path/to/project \
--host 0.0.0.0 \
--url-host localhost
```
Use `--url-host` to control what hostname is printed in the returned URL JSON.
## The Loop
1. **Check server is alive**, then **write HTML** to a new file in `screen_dir`:
- Before each write, check that `$SCREEN_DIR/.server-info` exists. If it doesn't (or `.server-stopped` exists), the server has shut down — restart it with `start-server.sh` before continuing. The server auto-exits after 30 minutes of inactivity.
- Use semantic filenames: `platform.html`, `visual-style.html`, `layout.html`
- **Never reuse filenames** — each screen gets a fresh file
- Use Write tool — **never use cat/heredoc** (dumps noise into terminal)
- Server automatically serves the newest file
2. **Tell user what to expect and end your turn:**
- Remind them of the URL (every step, not just first)
- Give a brief text summary of what's on screen (e.g., "Showing 3 layout options for the homepage")
- Ask them to respond in the terminal: "Take a look and let me know what you think. Click to select an option if you'd like."
3. **On your next turn** — after the user responds in the terminal:
- Read `$SCREEN_DIR/.events` if it exists — this contains the user's browser interactions (clicks, selections) as JSON lines
- Merge with the user's terminal text to get the full picture
- The terminal message is the primary feedback; `.events` provides structured interaction data
4. **Iterate or advance** — if feedback changes current screen, write a new file (e.g., `layout-v2.html`). Only move to the next question when the current step is validated.
5. **Unload when returning to terminal** — when the next step doesn't need the browser (e.g., a clarifying question, a tradeoff discussion), push a waiting screen to clear the stale content:
```html
<!-- filename: waiting.html (or waiting-2.html, etc.) -->
<div style="display:flex;align-items:center;justify-content:center;min-height:60vh">
<p class="subtitle">Continuing in terminal...</p>
</div>
```
This prevents the user from staring at a resolved choice while the conversation has moved on. When the next visual question comes up, push a new content file as usual.
6. Repeat until done.
## Writing Content Fragments
Write just the content that goes inside the page. The server wraps it in the frame template automatically (header, theme CSS, selection indicator, and all interactive infrastructure).
**Minimal example:**
```html
<h2>Which layout works better?</h2>
<p class="subtitle">Consider readability and visual hierarchy</p>
<div class="options">
<div class="option" data-choice="a" onclick="toggleSelect(this)">
<div class="letter">A</div>
<div class="content">
<h3>Single Column</h3>
<p>Clean, focused reading experience</p>
</div>
</div>
<div class="option" data-choice="b" onclick="toggleSelect(this)">
<div class="letter">B</div>
<div class="content">
<h3>Two Column</h3>
<p>Sidebar navigation with main content</p>
</div>
</div>
</div>
```
That's it. No `<html>`, no CSS, no `<script>` tags needed. The server provides all of that.
## CSS Classes Available
The frame template provides these CSS classes for your content:
### Options (A/B/C choices)
```html
<div class="options">
<div class="option" data-choice="a" onclick="toggleSelect(this)">
<div class="letter">A</div>
<div class="content">
<h3>Title</h3>
<p>Description</p>
</div>
</div>
</div>
```
**Multi-select:** Add `data-multiselect` to the container to let users select multiple options. Each click toggles the item. The indicator bar shows the count.
```html
<div class="options" data-multiselect>
<!-- same option markup — users can select/deselect multiple -->
</div>
```
### Cards (visual designs)
```html
<div class="cards">
<div class="card" data-choice="design1" onclick="toggleSelect(this)">
<div class="card-image"><!-- mockup content --></div>
<div class="card-body">
<h3>Name</h3>
<p>Description</p>
</div>
</div>
</div>
```
### Mockup container
```html
<div class="mockup">
<div class="mockup-header">Preview: Dashboard Layout</div>
<div class="mockup-body"><!-- your mockup HTML --></div>
</div>
```
### Split view (side-by-side)
```html
<div class="split">
<div class="mockup"><!-- left --></div>
<div class="mockup"><!-- right --></div>
</div>
```
### Pros/Cons
```html
<div class="pros-cons">
<div class="pros"><h4>Pros</h4><ul><li>Benefit</li></ul></div>
<div class="cons"><h4>Cons</h4><ul><li>Drawback</li></ul></div>
</div>
```
### Mock elements (wireframe building blocks)
```html
<div class="mock-nav">Logo | Home | About | Contact</div>
<div style="display: flex;">
<div class="mock-sidebar">Navigation</div>
<div class="mock-content">Main content area</div>
</div>
<button class="mock-button">Action Button</button>
<input class="mock-input" placeholder="Input field">
<div class="placeholder">Placeholder area</div>
```
### Typography and sections
- `h2` — page title
- `h3` — section heading
- `.subtitle` — secondary text below title
- `.section` — content block with bottom margin
- `.label` — small uppercase label text
## Browser Events Format
When the user clicks options in the browser, their interactions are recorded to `$SCREEN_DIR/.events` (one JSON object per line). The file is cleared automatically when you push a new screen.
```jsonl
{"type":"click","choice":"a","text":"Option A - Simple Layout","timestamp":1706000101}
{"type":"click","choice":"c","text":"Option C - Complex Grid","timestamp":1706000108}
{"type":"click","choice":"b","text":"Option B - Hybrid","timestamp":1706000115}
```
The full event stream shows the user's exploration path — they may click multiple options before settling. The last `choice` event is typically the final selection, but the pattern of clicks can reveal hesitation or preferences worth asking about.
If `.events` doesn't exist, the user didn't interact with the browser — use only their terminal text.
## Design Tips
- **Scale fidelity to the question** — wireframes for layout, polish for polish questions
- **Explain the question on each page** — "Which layout feels more professional?" not just "Pick one"
- **Iterate before advancing** — if feedback changes current screen, write a new version
- **2-4 options max** per screen
- **Use real content when it matters** — for a photography portfolio, use actual images (Unsplash). Placeholder content obscures design issues.
- **Keep mockups simple** — focus on layout and structure, not pixel-perfect design
## File Naming
- Use semantic names: `platform.html`, `visual-style.html`, `layout.html`
- Never reuse filenames — each screen must be a new file
- For iterations: append version suffix like `layout-v2.html`, `layout-v3.html`
- Server serves newest file by modification time
## Cleaning Up
```bash
scripts/stop-server.sh $SCREEN_DIR
```
If the session used `--project-dir`, mockup files persist in `.superpowers/brainstorm/` for later reference. Only `/tmp` sessions get deleted on stop.
## Reference
- Frame template (CSS reference): `scripts/frame-template.html`
- Helper script (client-side): `scripts/helper.js`

546
.config/opencode/skills/browser-use/SKILL.md Normal file
View File

@@ -0,0 +1,546 @@
---
name: browser-use
description: Automates browser interactions for web testing, form filling, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, or extract information from web pages.
allowed-tools: Bash(browser-use:*)
---
# Browser Automation with browser-use CLI
The `browser-use` command provides fast, persistent browser automation. It maintains browser sessions across commands, enabling complex multi-step workflows.
## Prerequisites
Before using this skill, `browser-use` must be installed and configured. Run diagnostics to verify:
```bash
browser-use doctor
```
For more information, see https://github.com/browser-use/browser-use/blob/main/browser_use/skill_cli/README.md
## Core Workflow
1. **Navigate**: `browser-use open <url>` - Opens URL (starts browser if needed)
2. **Inspect**: `browser-use state` - Returns clickable elements with indices
3. **Interact**: Use indices from state to interact (`browser-use click 5`, `browser-use input 3 "text"`)
4. **Verify**: `browser-use state` or `browser-use screenshot` to confirm actions
5. **Repeat**: Browser stays open between commands
## Browser Modes
```bash
browser-use --browser chromium open <url> # Default: headless Chromium
browser-use --browser chromium --headed open <url> # Visible Chromium window
browser-use --browser real open <url> # Real Chrome (no profile = fresh)
browser-use --browser real --profile "Default" open <url> # Real Chrome with your login sessions
browser-use --browser remote open <url> # Cloud browser
```
- **chromium**: Fast, isolated, headless by default
- **real**: Uses a real Chrome binary. Without `--profile`, uses a persistent but empty CLI profile at `~/.config/browseruse/profiles/cli/`. With `--profile "ProfileName"`, copies your actual Chrome profile (cookies, logins, extensions)
- **remote**: Cloud-hosted browser with proxy support
## Essential Commands
```bash
# Navigation
browser-use open <url> # Navigate to URL
browser-use back # Go back
browser-use scroll down # Scroll down (--amount N for pixels)
# Page State (always run state first to get element indices)
browser-use state # Get URL, title, clickable elements
browser-use screenshot # Take screenshot (base64)
browser-use screenshot path.png # Save screenshot to file
# Interactions (use indices from state)
browser-use click <index> # Click element
browser-use type "text" # Type into focused element
browser-use input <index> "text" # Click element, then type
browser-use keys "Enter" # Send keyboard keys
browser-use select <index> "option" # Select dropdown option
# Data Extraction
browser-use eval "document.title" # Execute JavaScript
browser-use get text <index> # Get element text
browser-use get html --selector "h1" # Get scoped HTML
# Wait
browser-use wait selector "h1" # Wait for element
browser-use wait text "Success" # Wait for text
# Session
browser-use sessions # List active sessions
browser-use close # Close current session
browser-use close --all # Close all sessions
# AI Agent
browser-use -b remote run "task" # Run agent in cloud (async by default)
browser-use task status <id> # Check cloud task progress
```
## Commands
### Navigation & Tabs
```bash
browser-use open <url> # Navigate to URL
browser-use back # Go back in history
browser-use scroll down # Scroll down
browser-use scroll up # Scroll up
browser-use scroll down --amount 1000 # Scroll by specific pixels (default: 500)
browser-use switch <tab> # Switch to tab by index
browser-use close-tab # Close current tab
browser-use close-tab <tab> # Close specific tab
```
### Page State
```bash
browser-use state # Get URL, title, and clickable elements
browser-use screenshot # Take screenshot (outputs base64)
browser-use screenshot path.png # Save screenshot to file
browser-use screenshot --full path.png # Full page screenshot
```
### Interactions
```bash
browser-use click <index> # Click element
browser-use type "text" # Type text into focused element
browser-use input <index> "text" # Click element, then type text
browser-use keys "Enter" # Send keyboard keys
browser-use keys "Control+a" # Send key combination
browser-use select <index> "option" # Select dropdown option
browser-use hover <index> # Hover over element (triggers CSS :hover)
browser-use dblclick <index> # Double-click element
browser-use rightclick <index> # Right-click element (context menu)
```
Use indices from `browser-use state`.
### JavaScript & Data
```bash
browser-use eval "document.title" # Execute JavaScript, return result
browser-use get title # Get page title
browser-use get html # Get full page HTML
browser-use get html --selector "h1" # Get HTML of specific element
browser-use get text <index> # Get text content of element
browser-use get value <index> # Get value of input/textarea
browser-use get attributes <index> # Get all attributes of element
browser-use get bbox <index> # Get bounding box (x, y, width, height)
```
### Cookies
```bash
browser-use cookies get # Get all cookies
browser-use cookies get --url <url> # Get cookies for specific URL
browser-use cookies set <name> <value> # Set a cookie
browser-use cookies set name val --domain .example.com --secure --http-only
browser-use cookies set name val --same-site Strict # SameSite: Strict, Lax, or None
browser-use cookies set name val --expires 1735689600 # Expiration timestamp
browser-use cookies clear # Clear all cookies
browser-use cookies clear --url <url> # Clear cookies for specific URL
browser-use cookies export <file> # Export all cookies to JSON file
browser-use cookies export <file> --url <url> # Export cookies for specific URL
browser-use cookies import <file> # Import cookies from JSON file
```
### Wait Conditions
```bash
browser-use wait selector "h1" # Wait for element to be visible
browser-use wait selector ".loading" --state hidden # Wait for element to disappear
browser-use wait selector "#btn" --state attached # Wait for element in DOM
browser-use wait text "Success" # Wait for text to appear
browser-use wait selector "h1" --timeout 5000 # Custom timeout in ms
```
### Python Execution
```bash
browser-use python "x = 42" # Set variable
browser-use python "print(x)" # Access variable (outputs: 42)
browser-use python "print(browser.url)" # Access browser object
browser-use python --vars # Show defined variables
browser-use python --reset # Clear Python namespace
browser-use python --file script.py # Execute Python file
```
The Python session maintains state across commands. The `browser` object provides:
- `browser.url`, `browser.title`, `browser.html` — page info
- `browser.goto(url)`, `browser.back()` — navigation
- `browser.click(index)`, `browser.type(text)`, `browser.input(index, text)`, `browser.keys(keys)` — interactions
- `browser.screenshot(path)`, `browser.scroll(direction, amount)` — visual
- `browser.wait(seconds)`, `browser.extract(query)` — utilities
### Agent Tasks
#### Remote Mode Options
When using `--browser remote`, additional options are available:
```bash
# Specify LLM model
browser-use -b remote run "task" --llm gpt-4o
browser-use -b remote run "task" --llm claude-sonnet-4-20250514
# Proxy configuration (default: us)
browser-use -b remote run "task" --proxy-country uk
# Session reuse
browser-use -b remote run "task 1" --keep-alive # Keep session alive after task
browser-use -b remote run "task 2" --session-id abc-123 # Reuse existing session
# Execution modes
browser-use -b remote run "task" --flash # Fast execution mode
browser-use -b remote run "task" --wait # Wait for completion (default: async)
# Advanced options
browser-use -b remote run "task" --thinking # Extended reasoning mode
browser-use -b remote run "task" --no-vision # Disable vision (enabled by default)
# Using a cloud profile (create session first, then run with --session-id)
browser-use session create --profile <cloud-profile-id> --keep-alive
# → returns session_id
browser-use -b remote run "task" --session-id <session-id>
# Task configuration
browser-use -b remote run "task" --start-url https://example.com # Start from specific URL
browser-use -b remote run "task" --allowed-domain example.com # Restrict navigation (repeatable)
browser-use -b remote run "task" --metadata key=value # Task metadata (repeatable)
browser-use -b remote run "task" --skill-id skill-123 # Enable skills (repeatable)
browser-use -b remote run "task" --secret key=value # Secret metadata (repeatable)
# Structured output and evaluation
browser-use -b remote run "task" --structured-output '{"type":"object"}' # JSON schema for output
browser-use -b remote run "task" --judge # Enable judge mode
browser-use -b remote run "task" --judge-ground-truth "expected answer"
```
### Task Management
```bash
browser-use task list # List recent tasks
browser-use task list --limit 20 # Show more tasks
browser-use task list --status finished # Filter by status (finished, stopped)
browser-use task list --session <id> # Filter by session ID
browser-use task list --json # JSON output
browser-use task status <task-id> # Get task status (latest step only)
browser-use task status <task-id> -c # All steps with reasoning
browser-use task status <task-id> -v # All steps with URLs + actions
browser-use task status <task-id> --last 5 # Last N steps only
browser-use task status <task-id> --step 3 # Specific step number
browser-use task status <task-id> --reverse # Newest first
browser-use task stop <task-id> # Stop a running task
browser-use task logs <task-id> # Get task execution logs
```
### Cloud Session Management
```bash
browser-use session list # List cloud sessions
browser-use session list --limit 20 # Show more sessions
browser-use session list --status active # Filter by status
browser-use session list --json # JSON output
browser-use session get <session-id> # Get session details + live URL
browser-use session get <session-id> --json
browser-use session stop <session-id> # Stop a session
browser-use session stop --all # Stop all active sessions
browser-use session create # Create with defaults
browser-use session create --profile <id> # With cloud profile
browser-use session create --proxy-country uk # With geographic proxy
browser-use session create --start-url https://example.com
browser-use session create --screen-size 1920x1080
browser-use session create --keep-alive
browser-use session create --persist-memory
browser-use session share <session-id> # Create public share URL
browser-use session share <session-id> --delete # Delete public share
```
### Tunnels
```bash
browser-use tunnel <port> # Start tunnel (returns URL)
browser-use tunnel <port> # Idempotent - returns existing URL
browser-use tunnel list # Show active tunnels
browser-use tunnel stop <port> # Stop tunnel
browser-use tunnel stop --all # Stop all tunnels
```
### Session Management
```bash
browser-use sessions # List active sessions
browser-use close # Close current session
browser-use close --all # Close all sessions
```
### Profile Management
#### Local Chrome Profiles (`--browser real`)
```bash
browser-use -b real profile list # List local Chrome profiles
browser-use -b real profile cookies "Default" # Show cookie domains in profile
```
#### Cloud Profiles (`--browser remote`)
```bash
browser-use -b remote profile list # List cloud profiles
browser-use -b remote profile list --page 2 --page-size 50
browser-use -b remote profile get <id> # Get profile details
browser-use -b remote profile create # Create new cloud profile
browser-use -b remote profile create --name "My Profile"
browser-use -b remote profile update <id> --name "New"
browser-use -b remote profile delete <id>
```
#### Syncing
```bash
browser-use profile sync --from "Default" --domain github.com # Domain-specific
browser-use profile sync --from "Default" # Full profile
browser-use profile sync --from "Default" --name "Custom Name" # With custom name
```
### Server Control
```bash
browser-use server logs # View server logs
```
## Common Workflows
### Exposing Local Dev Servers
Use when you have a local dev server and need a cloud browser to reach it.
**Core workflow:** Start dev server → create tunnel → browse the tunnel URL remotely.
```bash
# 1. Start your dev server
npm run dev & # localhost:3000
# 2. Expose it via Cloudflare tunnel
browser-use tunnel 3000
# → url: https://abc.trycloudflare.com
# 3. Now the cloud browser can reach your local server
browser-use --browser remote open https://abc.trycloudflare.com
browser-use state
browser-use screenshot
```
**Note:** Tunnels are independent of browser sessions. They persist across `browser-use close` and can be managed separately. Cloudflared must be installed — run `browser-use doctor` to check.
### Authenticated Browsing with Profiles
Use when a task requires browsing a site the user is already logged into (e.g. Gmail, GitHub, internal tools).
**Core workflow:** Check existing profiles → ask user which profile and browser mode → browse with that profile. Only sync cookies if no suitable profile exists.
**Before browsing an authenticated site, the agent MUST:**
1. Ask the user whether to use **real** (local Chrome) or **remote** (cloud) browser
2. List available profiles for that mode
3. Ask which profile to use
4. If no profile has the right cookies, offer to sync (see below)
#### Step 1: Check existing profiles
```bash
# Option A: Local Chrome profiles (--browser real)
browser-use -b real profile list
# → Default: Person 1 (user@gmail.com)
# → Profile 1: Work (work@company.com)
# Option B: Cloud profiles (--browser remote)
browser-use -b remote profile list
# → abc-123: "Chrome - Default (github.com)"
# → def-456: "Work profile"
```
#### Step 2: Browse with the chosen profile
```bash
# Real browser — uses local Chrome with existing login sessions
browser-use --browser real --profile "Default" open https://github.com
# Cloud browser — uses cloud profile with synced cookies
browser-use --browser remote --profile abc-123 open https://github.com
```
The user is already authenticated — no login needed.
**Note:** Cloud profile cookies can expire over time. If authentication fails, re-sync cookies from the local Chrome profile.
#### Step 3: Syncing cookies (only if needed)
If the user wants to use a cloud browser but no cloud profile has the right cookies, sync them from a local Chrome profile.
**Before syncing, the agent MUST:**
1. Ask which local Chrome profile to use
2. Ask which domain(s) to sync — do NOT default to syncing the full profile
3. Confirm before proceeding
**Check what cookies a local profile has:**
```bash
browser-use -b real profile cookies "Default"
# → youtube.com: 23
# → google.com: 18
# → github.com: 2
```
**Domain-specific sync (recommended):**
```bash
browser-use profile sync --from "Default" --domain github.com
# Creates new cloud profile: "Chrome - Default (github.com)"
# Only syncs github.com cookies
```
**Full profile sync (use with caution):**
```bash
browser-use profile sync --from "Default"
# Syncs ALL cookies — includes sensitive data, tracking cookies, every session token
```
Only use when the user explicitly needs their entire browser state.
**Fine-grained control (advanced):**
```bash
# Export cookies to file, manually edit, then import
browser-use --browser real --profile "Default" cookies export /tmp/cookies.json
browser-use --browser remote --profile <id> cookies import /tmp/cookies.json
```
**Use the synced profile:**
```bash
browser-use --browser remote --profile <id> open https://github.com
```
### Running Subagents
Use cloud sessions to run autonomous browser agents in parallel.
**Core workflow:** Launch task(s) with `run` → poll with `task status` → collect results → clean up sessions.
- **Session = Agent**: Each cloud session is a browser agent with its own state
- **Task = Work**: Jobs given to an agent; an agent can run multiple tasks sequentially
- **Session lifecycle**: Once stopped, a session cannot be revived — start a new one
#### Launching Tasks
```bash
# Single task (async by default — returns immediately)
browser-use -b remote run "Search for AI news and summarize top 3 articles"
# → task_id: task-abc, session_id: sess-123
# Parallel tasks — each gets its own session
browser-use -b remote run "Research competitor A pricing"
# → task_id: task-1, session_id: sess-a
browser-use -b remote run "Research competitor B pricing"
# → task_id: task-2, session_id: sess-b
browser-use -b remote run "Research competitor C pricing"
# → task_id: task-3, session_id: sess-c
# Sequential tasks in same session (reuses cookies, login state, etc.)
browser-use -b remote run "Log into example.com" --keep-alive
# → task_id: task-1, session_id: sess-123
browser-use task status task-1 # Wait for completion
browser-use -b remote run "Export settings" --session-id sess-123
# → task_id: task-2, session_id: sess-123 (same session)
```
#### Managing & Stopping
```bash
browser-use task list --status finished # See completed tasks
browser-use task stop task-abc # Stop a task (session may continue if --keep-alive)
browser-use session stop sess-123 # Stop an entire session (terminates its tasks)
browser-use session stop --all # Stop all sessions
```
#### Monitoring
**Task status is designed for token efficiency.** Default output is minimal — only expand when needed:
| Mode | Flag | Tokens | Use When |
|------|------|--------|----------|
| Default | (none) | Low | Polling progress |
| Compact | `-c` | Medium | Need full reasoning |
| Verbose | `-v` | High | Debugging actions |
```bash
# For long tasks (50+ steps)
browser-use task status <id> -c --last 5 # Last 5 steps only
browser-use task status <id> -v --step 10 # Inspect specific step
```
**Live view**: `browser-use session get <session-id>` returns a live URL to watch the agent.
**Detect stuck tasks**: If cost/duration in `task status` stops increasing, the task is stuck — stop it and start a new agent.
**Logs**: `browser-use task logs <task-id>` — only available after task completes.
## Global Options
| Option | Description |
|--------|-------------|
| `--session NAME` | Use named session (default: "default") |
| `--browser MODE` | Browser mode: chromium, real, remote |
| `--headed` | Show browser window (chromium mode) |
| `--profile NAME` | Browser profile (local name or cloud ID). Works with `open`, `session create`, etc. — does NOT work with `run` (use `--session-id` instead) |
| `--json` | Output as JSON |
| `--mcp` | Run as MCP server via stdin/stdout |
**Session behavior**: All commands without `--session` use the same "default" session. The browser stays open and is reused across commands. Use `--session NAME` to run multiple browsers in parallel.
## Tips
1. **Always run `browser-use state` first** to see available elements and their indices
2. **Use `--headed` for debugging** to see what the browser is doing
3. **Sessions persist** — the browser stays open between commands
4. **Use `--json`** for programmatic parsing
5. **Python variables persist** across `browser-use python` commands within a session
6. **CLI aliases**: `bu`, `browser`, and `browseruse` all work identically to `browser-use`
## Troubleshooting
**Run diagnostics first:**
```bash
browser-use doctor
```
**Browser won't start?**
```bash
browser-use close --all # Close all sessions
browser-use --headed open <url> # Try with visible window
```
**Element not found?**
```bash
browser-use state # Check current elements
browser-use scroll down # Element might be below fold
browser-use state # Check again
```
**Session issues?**
```bash
browser-use sessions # Check active sessions
browser-use close --all # Clean slate
browser-use open <url> # Fresh start
```
**Session reuse fails after `task stop`**:
If you stop a task and try to reuse its session, the new task may get stuck at "created" status. Create a new session instead:
```bash
browser-use session create --profile <profile-id> --keep-alive
browser-use -b remote run "new task" --session-id <new-session-id>
```
**Task stuck at "started"**: Check cost with `task status` — if not increasing, the task is stuck. View live URL with `session get`, then stop and start a new agent.
**Sessions persist after tasks complete**: Tasks finishing doesn't auto-stop sessions. Run `browser-use session stop --all` to clean up.
## Cleanup
**Always close the browser when done:**
```bash
browser-use close # Close browser session
browser-use session stop --all # Stop cloud sessions (if any)
browser-use tunnel stop --all # Stop tunnels (if any)
```

66
.config/opencode/skills/context7-cli/SKILL.md Normal file
View File

@@ -0,0 +1,66 @@
---
name: context7-cli
description: Use the ctx7 CLI to fetch library documentation, manage AI coding skills, and configure Context7 MCP. Activate when the user mentions "ctx7" or "context7", needs current docs for any library, wants to install/search/generate skills, or needs to set up Context7 for their AI coding agent.
---
# ctx7 CLI
The Context7 CLI does three things: fetches up-to-date library documentation, manages AI coding skills, and sets up Context7 MCP for your editor.
Make sure the CLI is up to date before running commands:
```bash
npm install -g ctx7@latest
```
## What this skill covers
- **[Documentation](references/docs.md)** — Fetch current docs for any library. Use when writing code, verifying API signatures, or when training data may be outdated.
- **[Skills management](references/skills.md)** — Install, search, suggest, list, remove, and generate AI coding skills.
- **[Setup](references/setup.md)** — Configure Context7 MCP for Claude Code / Cursor / OpenCode.
## Quick Reference
```bash
# Documentation
ctx7 library <name> <query> # Step 1: resolve library ID
ctx7 docs <libraryId> <query> # Step 2: fetch docs
# Skills
ctx7 skills install /owner/repo # Install from a repo (interactive)
ctx7 skills install /owner/repo name # Install a specific skill
ctx7 skills search <keywords> # Search the registry
ctx7 skills suggest # Auto-suggest based on project deps
ctx7 skills list # List installed skills
ctx7 skills remove <name> # Uninstall a skill
ctx7 skills generate # Generate a custom skill with AI (requires login)
# Setup
ctx7 setup # Configure Context7 MCP (interactive)
ctx7 login # Log in for higher rate limits + skill generation
ctx7 whoami # Check current login status
```
## Authentication
```bash
ctx7 login # Opens browser for OAuth
ctx7 login --no-browser # Prints URL instead of opening browser
ctx7 logout # Clear stored tokens
ctx7 whoami # Show current login status (name + email)
```
Most commands work without login. Exceptions: `skills generate` always requires it; `ctx7 setup` requires it unless `--api-key` or `--oauth` is passed. Login also unlocks higher rate limits on docs commands.
Set an API key via environment variable to skip interactive login entirely:
```bash
export CONTEXT7_API_KEY=your_key
```
## Common Mistakes
- Library IDs require a `/` prefix — `/facebook/react` not `facebook/react`
- Always run `ctx7 library` first — `ctx7 docs react "hooks"` will fail without a valid ID
- Repository format for skills is `/owner/repo` — e.g., `ctx7 skills install /anthropics/skills`
- `skills generate` requires login — run `ctx7 login` first

113
.config/opencode/skills/context7-cli/references/docs.md Normal file
View File

@@ -0,0 +1,113 @@
# Documentation Commands
Retrieves and queries up-to-date documentation and code examples from Context7 for any programming library or framework. Two-step workflow: resolve the library name to get its ID, then query docs using that ID.
If the user already provided a library ID in `/org/project` or `/org/project/version` format, pass it directly to `ctx7 docs`.
## Step 1: Resolve a Library
Resolves a package/product name to a Context7-compatible library ID and returns matching libraries.
```bash
ctx7 library react "How to clean up useEffect with async operations"
ctx7 library nextjs "How to set up app router with middleware"
ctx7 library prisma "How to define one-to-many relations with cascade delete"
```
Always pass a `query` argument — it is required and directly affects result ranking. Use the user's intent to form the query, which helps disambiguate when multiple libraries share a similar name. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query.
### Result fields
Each result includes:
- **Library ID** — Context7-compatible identifier (format: `/org/project`)
- **Name** — Library or package name
- **Description** — Short summary
- **Code Snippets** — Number of available code examples
- **Source Reputation** — Authority indicator (High, Medium, Low, or Unknown)
- **Benchmark Score** — Quality indicator (100 is the highest score)
- **Versions** — List of versions if available. Use one of those versions if the user provides a version in their query. The format is `/org/project/version`.
### Selection process
1. Analyze the query to understand what library/package the user is looking for
2. Select the most relevant match based on:
- Name similarity to the query (exact matches prioritized)
- Description relevance to the query's intent
- Documentation coverage (prioritize libraries with higher Code Snippet counts)
- Source reputation (consider libraries with High or Medium reputation more authoritative)
- Benchmark score (higher is better, 100 is the maximum)
3. If multiple good matches exist, acknowledge this but proceed with the most relevant one
4. If no good matches exist, clearly state this and suggest query refinements
5. For ambiguous queries, request clarification before proceeding with a best-guess match
IMPORTANT: Do not call `ctx7 library` more than 3 times per question. If you cannot find what you need after 3 calls, use the best result you have.
### Version-specific IDs
If the user mentions a specific version, use a version-specific library ID:
```bash
# General (latest indexed)
ctx7 docs /vercel/next.js "How to set up app router"
# Version-specific
ctx7 docs /vercel/next.js/v14.3.0-canary.87 "How to set up app router"
```
The available versions are listed in the `ctx7 library` output. Use the closest match to what the user specified.
```bash
# Output as JSON for scripting
ctx7 library react "How to use hooks for state management" --json | jq '.[0].id'
```
## Step 2: Query Documentation
Retrieves up-to-date documentation and code examples for the resolved library.
You must call `ctx7 library` first to obtain the exact Context7-compatible library ID required to use this command, UNLESS the user explicitly provides a library ID in the format `/org/project` or `/org/project/version`.
```bash
ctx7 docs /facebook/react "How to clean up useEffect with async operations"
ctx7 docs /vercel/next.js "How to add authentication middleware to app router"
ctx7 docs /prisma/prisma "How to define one-to-many relations with cascade delete"
```
IMPORTANT: Do not call `ctx7 docs` more than 3 times per question. If you cannot find what you need after 3 calls, use the best information you have.
### Writing good queries
The query directly affects the quality of results. Be specific and include relevant details. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query.
| Quality | Example |
|---------|---------|
| Good | `"How to set up authentication with JWT in Express.js"` |
| Good | `"React useEffect cleanup function with async operations"` |
| Bad | `"auth"` |
| Bad | `"hooks"` |
Use the user's full question as the query when possible — vague one-word queries return generic results.
The output contains two types of content: **code snippets** (titled, with language-tagged blocks) and **info snippets** (prose explanations with breadcrumb context).
```bash
# Output as structured JSON
ctx7 docs /facebook/react "How to use hooks for state management" --json
# Pipe to other tools — output is clean when not in a TTY (no spinners or colors)
ctx7 docs /facebook/react "How to use hooks for state management" | head -50
ctx7 docs /vercel/next.js "How to add middleware for route protection" | grep -A5 "middleware"
```
## Authentication
Works without authentication. For higher rate limits:
```bash
# Option A: environment variable
export CONTEXT7_API_KEY=your_key
# Option B: OAuth login
ctx7 login
```

43
.config/opencode/skills/context7-cli/references/setup.md Normal file
View File

@@ -0,0 +1,43 @@
# Setup
## ctx7 setup
One-time command to configure Context7 for your AI coding agent. Prompts for mode on first run:
- **MCP server** — registers the Context7 MCP server so the agent can call tools natively
- **CLI + Skills** — installs a `find-docs` skill that guides the agent to use `ctx7` CLI commands (no MCP required)
```bash
ctx7 setup # Interactive — prompts for mode, then agent/install target
ctx7 setup --mcp # Skip prompt, use MCP server mode
ctx7 setup --cli # Skip prompt, use CLI + Skills mode
# MCP mode — target a specific agent
ctx7 setup --claude # Claude Code only
ctx7 setup --cursor # Cursor only
ctx7 setup --opencode # OpenCode only
# CLI + Skills mode — target a specific install location
ctx7 setup --cli --claude # Claude Code (~/.claude/skills)
ctx7 setup --cli --cursor # Cursor (~/.cursor/skills)
ctx7 setup --cli --universal # Universal (~/.agents/skills)
ctx7 setup --cli --antigravity # Antigravity (~/.config/agent/skills)
ctx7 setup --project # Configure current project instead of globally
ctx7 setup --yes # Skip confirmation prompts
```
**Authentication options:**
```bash
ctx7 setup --api-key YOUR_KEY # Use an existing API key (both MCP and CLI + Skills mode)
ctx7 setup --oauth # OAuth endpoint — MCP mode only (IDE handles the auth flow)
```
Without `--api-key` or `--oauth`, setup opens a browser for OAuth login. MCP mode additionally generates a new API key after login. `--oauth` is MCP-only.
**What gets written — MCP mode:**
- MCP server entry in the agent's config file (`.mcp.json` for Claude, `.cursor/mcp.json` for Cursor, `.opencode.json` for OpenCode)
- A Context7 rule file instructing the agent to use Context7 for library docs
- A `context7-mcp` skill in the agent's skills directory
**What gets written — CLI + Skills mode:**
- A `find-docs` skill in the chosen agent's skills directory, guiding the agent to use `ctx7 library` and `ctx7 docs` commands

118
.config/opencode/skills/context7-cli/references/skills.md Normal file
View File

@@ -0,0 +1,118 @@
# Skills Commands
Manage AI coding skills from the Context7 registry. Skills are Markdown files that teach AI coding agents best practices, patterns, and workflows for specific libraries or tasks.
## Install
Install skills from any GitHub repository. Repository format is always `/owner/repo`.
```bash
ctx7 skills install /anthropics/skills # Interactive — pick from a list
ctx7 skills install /anthropics/skills pdf # Install a specific skill by name
ctx7 skills install /anthropics/skills --all # Install everything without prompting
```
Target a specific IDE with a flag:
```bash
ctx7 skills install /anthropics/skills pdf --claude # Claude Code only
ctx7 skills install /anthropics/skills pdf --cursor # Cursor only
ctx7 skills install /anthropics/skills pdf --universal # Universal (.agents/skills/)
ctx7 skills install /anthropics/skills --all --global # All skills, global install
```
Alias: `ctx7 si /anthropics/skills pdf`
## Search
Find skills across the entire registry by keyword. Shows an interactive list with install counts and trust scores. Select to install.
```bash
ctx7 skills search pdf
ctx7 skills search typescript testing
ctx7 skills search react nextjs
```
Alias: `ctx7 ss pdf`
## Suggest
Auto-detects your project dependencies and recommends relevant skills from the registry.
```bash
ctx7 skills suggest # Scan current project, install to project
ctx7 skills suggest --global # Install suggestions globally
ctx7 skills suggest --claude # Target Claude Code only
```
Reads `package.json`, `requirements.txt`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `Gemfile`. Falls back to suggesting `ctx7 skills search` if no dependencies are detected.
Alias: `ctx7 ssg`
## Generate (AI-powered)
Generate a custom skill tailored to your stack using AI. **Requires login.**
```bash
ctx7 skills generate
ctx7 skills generate --claude # Install directly to Claude Code
ctx7 skills generate --global # Install to global skills
```
Interactive flow:
1. Describe the expertise you want (e.g., "OAuth authentication with NextAuth.js")
2. Select relevant libraries from search results
3. Answer 3 clarifying questions to focus the skill
4. Review the generated skill, request changes if needed
5. Choose where to install it
**Limits:** Free accounts get 6 generations/week, Pro accounts get 10.
Aliases: `ctx7 skills gen`, `ctx7 skills g`
## List
Show all installed skills for the current project or globally.
```bash
ctx7 skills list # Current project (all detected IDEs)
ctx7 skills list --claude # Claude Code only
ctx7 skills list --global # Global skills
ctx7 skills list --global --claude # Global Claude Code skills
```
## Remove
Uninstall a skill by name.
```bash
ctx7 skills remove pdf
ctx7 skills remove pdf --claude # From Claude Code only
ctx7 skills remove pdf --global # From global skills
```
Aliases: `ctx7 skills rm`, `ctx7 skills delete`
## Info
Browse all skills in a repository without installing — useful for previewing what's available.
```bash
ctx7 skills info /anthropics/skills
```
Output shows each skill name, description, and URL, plus quick install commands.
## IDE Flags
All skills commands accept these flags to target a specific AI coding assistant:
| Flag | Directory | Used by |
|------|-----------|---------|
| `--universal` | `.agents/skills/` | Amp, Codex, Gemini CLI, OpenCode, GitHub Copilot |
| `--claude` | `.claude/skills/` | Claude Code |
| `--cursor` | `.cursor/skills/` | Cursor |
| `--antigravity` | `.agent/skills/` | Antigravity |
Without a flag, the CLI prompts you to select one or more targets interactively.
Add `--global` to any flag to install in your home directory instead of the current project.

182
.config/opencode/skills/dispatching-parallel-agents/SKILL.md Normal file
View File

@@ -0,0 +1,182 @@
---
name: dispatching-parallel-agents
description: Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
---
# Dispatching Parallel Agents
## Overview
You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.
When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.
**Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently.
## When to Use
```dot
digraph when_to_use {
"Multiple failures?" [shape=diamond];
"Are they independent?" [shape=diamond];
"Single agent investigates all" [shape=box];
"One agent per problem domain" [shape=box];
"Can they work in parallel?" [shape=diamond];
"Sequential agents" [shape=box];
"Parallel dispatch" [shape=box];
"Multiple failures?" -> "Are they independent?" [label="yes"];
"Are they independent?" -> "Single agent investigates all" [label="no - related"];
"Are they independent?" -> "Can they work in parallel?" [label="yes"];
"Can they work in parallel?" -> "Parallel dispatch" [label="yes"];
"Can they work in parallel?" -> "Sequential agents" [label="no - shared state"];
}
```
**Use when:**
- 3+ test files failing with different root causes
- Multiple subsystems broken independently
- Each problem can be understood without context from others
- No shared state between investigations
**Don't use when:**
- Failures are related (fix one might fix others)
- Need to understand full system state
- Agents would interfere with each other
## The Pattern
### 1. Identify Independent Domains
Group failures by what's broken:
- File A tests: Tool approval flow
- File B tests: Batch completion behavior
- File C tests: Abort functionality
Each domain is independent - fixing tool approval doesn't affect abort tests.
### 2. Create Focused Agent Tasks
Each agent gets:
- **Specific scope:** One test file or subsystem
- **Clear goal:** Make these tests pass
- **Constraints:** Don't change other code
- **Expected output:** Summary of what you found and fixed
### 3. Dispatch in Parallel
```typescript
// In Claude Code / AI environment
Task("Fix agent-tool-abort.test.ts failures")
Task("Fix batch-completion-behavior.test.ts failures")
Task("Fix tool-approval-race-conditions.test.ts failures")
// All three run concurrently
```
### 4. Review and Integrate
When agents return:
- Read each summary
- Verify fixes don't conflict
- Run full test suite
- Integrate all changes
## Agent Prompt Structure
Good agent prompts are:
1. **Focused** - One clear problem domain
2. **Self-contained** - All context needed to understand the problem
3. **Specific about output** - What should the agent return?
```markdown
Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:
1. "should abort tool with partial output capture" - expects 'interrupted at' in message
2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
3. "should properly track pendingToolCount" - expects 3 results but gets 0
These are timing/race condition issues. Your task:
1. Read the test file and understand what each test verifies
2. Identify root cause - timing issues or actual bugs?
3. Fix by:
- Replacing arbitrary timeouts with event-based waiting
- Fixing bugs in abort implementation if found
- Adjusting test expectations if testing changed behavior
Do NOT just increase timeouts - find the real issue.
Return: Summary of what you found and what you fixed.
```
## Common Mistakes
**❌ Too broad:** "Fix all the tests" - agent gets lost
**✅ Specific:** "Fix agent-tool-abort.test.ts" - focused scope
**❌ No context:** "Fix the race condition" - agent doesn't know where
**✅ Context:** Paste the error messages and test names
**❌ No constraints:** Agent might refactor everything
**✅ Constraints:** "Do NOT change production code" or "Fix tests only"
**❌ Vague output:** "Fix it" - you don't know what changed
**✅ Specific:** "Return summary of root cause and changes"
## When NOT to Use
**Related failures:** Fixing one might fix others - investigate together first
**Need full context:** Understanding requires seeing entire system
**Exploratory debugging:** You don't know what's broken yet
**Shared state:** Agents would interfere (editing same files, using same resources)
## Real Example from Session
**Scenario:** 6 test failures across 3 files after major refactoring
**Failures:**
- agent-tool-abort.test.ts: 3 failures (timing issues)
- batch-completion-behavior.test.ts: 2 failures (tools not executing)
- tool-approval-race-conditions.test.ts: 1 failure (execution count = 0)
**Decision:** Independent domains - abort logic separate from batch completion separate from race conditions
**Dispatch:**
```
Agent 1 → Fix agent-tool-abort.test.ts
Agent 2 → Fix batch-completion-behavior.test.ts
Agent 3 → Fix tool-approval-race-conditions.test.ts
```
**Results:**
- Agent 1: Replaced timeouts with event-based waiting
- Agent 2: Fixed event structure bug (threadId in wrong place)
- Agent 3: Added wait for async tool execution to complete
**Integration:** All fixes independent, no conflicts, full suite green
**Time saved:** 3 problems solved in parallel vs sequentially
## Key Benefits
1. **Parallelization** - Multiple investigations happen simultaneously
2. **Focus** - Each agent has narrow scope, less context to track
3. **Independence** - Agents don't interfere with each other
4. **Speed** - 3 problems solved in time of 1
## Verification
After agents return:
1. **Review each summary** - Understand what changed
2. **Check for conflicts** - Did agents edit same code?
3. **Run full suite** - Verify all fixes work together
4. **Spot check** - Agents can make systematic errors
## Real-World Impact
From debugging session (2025-10-03):
- 6 failures across 3 files
- 3 agents dispatched in parallel
- All investigations completed concurrently
- All fixes integrated successfully
- Zero conflicts between agent changes

69
.config/opencode/skills/docker-helper/SKILL.md Normal file
View File

@@ -0,0 +1,69 @@
---
name: docker-helper
description: This skill should be used when the user asks to "DESCRIPTION_HERE". Add specific trigger phrases that would activate this skill.
license: MIT
compatibility: opencode
metadata:
category: general
version: "1.0.0"
---
# docker-helper
Brief description of what this skill does and its purpose.
## What This Skill Provides
1. **Feature 1** - Brief description
2. **Feature 2** - Brief description
3. **Feature 3** - Brief description
## Quick Start
Basic usage example:
```bash
# Example command
some-tool --option value
```
## Common Tasks
### Task 1: Description
Step-by-step instructions:
1. First step
2. Second step
3. Third step
### Task 2: Description
Step-by-step instructions:
1. First step
2. Second step
## Important Notes
- Keep this section brief
- Use bullet points for clarity
- Reference supporting files if available
## Resources
### Reference Files
- `references/detailed-guide.md` - Detailed documentation
### Scripts
- `scripts/helper.sh` - Utility script
### Assets
- `assets/template.txt` - Template file

4
.config/opencode/skills/docker-helper/assets/template.txt Normal file
View File

@@ -0,0 +1,4 @@
# Template file for docker-helper
This is a template file that can be used as a starting point.
Modify it according to your needs.

15
.config/opencode/skills/docker-helper/references/detailed-guide.md Normal file
View File

@@ -0,0 +1,15 @@
# Detailed Guide for docker-helper
This file contains detailed documentation that can be referenced on-demand.
## Advanced Usage
Detailed instructions go here...
## Configuration
Configuration options and examples...
## Troubleshooting
Common issues and solutions...

9
.config/opencode/skills/docker-helper/scripts/helper.sh Executable file
View File

@@ -0,0 +1,9 @@
#!/bin/bash
#
# Helper script for docker-helper
#
set -euo pipefail
echo "Helper script for docker-helper"
echo "Modify this script for your needs"

42
.config/opencode/skills/dotfiles-manager/config/dotfiles-registry.json Normal file
View File

@@ -0,0 +1,42 @@
{
"version": "1.0.0",
"dotfiles_repo": "~/.dotfiles",
"backup_dir": "~/.dotfiles-backup",
"configs": {
"bash": {
"description": "Bash shell configuration",
"files": [
{"system": "~/.bashrc", "repo": "home/.bashrc"},
{"system": "~/.bash_aliases", "repo": "home/.bash_aliases"},
{"system": "~/.bash_completion", "repo": "home/.bash_completion"},
{"system": "~/.bash_logout", "repo": "home/.bash_logout"},
{"system": "~/.profile", "repo": "home/.profile"}
]
},
"fish": {
"description": "Fish shell configuration",
"directories": [
{"system": "~/.config/fish", "repo": "config/fish"}
]
},
"git": {
"description": "Git configuration",
"files": [
{"system": "~/.gitconfig", "repo": "home/.gitconfig"}
]
},
"tmux": {
"description": "Tmux configuration",
"files": [
{"system": "~/.tmux.conf", "repo": "home/.tmux.conf"}
]
},
"opencode": {
"description": "Opencode AI configuration",
"directories": [
{"system": "~/.config/opencode", "repo": "config/opencode"}
],
"exclude_patterns": [".gitignore", "node_modules"]
}
}
}

70
.config/opencode/skills/executing-plans/SKILL.md Normal file
View File

@@ -0,0 +1,70 @@
---
name: executing-plans
description: Use when you have a written implementation plan to execute in a separate session with review checkpoints
---
# Executing Plans
## Overview
Load plan, review critically, execute all tasks, report when complete.
**Announce at start:** "I'm using the executing-plans skill to implement this plan."
**Note:** Tell your human partner that Superpowers works much better with access to subagents. The quality of its work will be significantly higher if run on a platform with subagent support (such as Claude Code or Codex). If subagents are available, use superpowers:subagent-driven-development instead of this skill.
## The Process
### Step 1: Load and Review Plan
1. Read plan file
2. Review critically - identify any questions or concerns about the plan
3. If concerns: Raise them with your human partner before starting
4. If no concerns: Create TodoWrite and proceed
### Step 2: Execute Tasks
For each task:
1. Mark as in_progress
2. Follow each step exactly (plan has bite-sized steps)
3. Run verifications as specified
4. Mark as completed
### Step 3: Complete Development
After all tasks complete and verified:
- Announce: "I'm using the finishing-a-development-branch skill to complete this work."
- **REQUIRED SUB-SKILL:** Use superpowers:finishing-a-development-branch
- Follow that skill to verify tests, present options, execute choice
## When to Stop and Ask for Help
**STOP executing immediately when:**
- Hit a blocker (missing dependency, test fails, instruction unclear)
- Plan has critical gaps preventing starting
- You don't understand an instruction
- Verification fails repeatedly
**Ask for clarification rather than guessing.**
## When to Revisit Earlier Steps
**Return to Review (Step 1) when:**
- Partner updates the plan based on your feedback
- Fundamental approach needs rethinking
**Don't force through blockers** - stop and ask.
## Remember
- Review plan critically first
- Follow plan steps exactly
- Don't skip verifications
- Reference skills when plan says to
- Stop when blocked, don't guess
- Never start implementation on main/master branch without explicit user consent
## Integration
**Required workflow skills:**
- **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting
- **superpowers:writing-plans** - Creates the plan this skill executes
- **superpowers:finishing-a-development-branch** - Complete development after all tasks

159
.config/opencode/skills/find-docs/SKILL.md Normal file
View File

@@ -0,0 +1,159 @@
---
name: find-docs
description: >-
Retrieves authoritative, up-to-date technical documentation, API references,
configuration details, and code examples for any developer technology.
Use this skill whenever answering technical questions or writing code that
interacts with external technologies. This includes libraries, frameworks,
programming languages, SDKs, APIs, CLI tools, cloud services, infrastructure
tools, and developer platforms.
Common scenarios:
- looking up API endpoints, classes, functions, or method parameters
- checking configuration options or CLI commands
- answering "how do I" technical questions
- generating code that uses a specific library or service
- debugging issues related to frameworks, SDKs, or APIs
- retrieving setup instructions, examples, or migration guides
- verifying version-specific behavior or breaking changes
Prefer this skill whenever documentation accuracy matters or when model
knowledge may be outdated.
---
# Documentation Lookup
Retrieve current documentation and code examples for any library using the Context7 CLI.
Make sure the CLI is up to date before running commands:
```bash
npm install -g ctx7@latest
```
Or run directly without installing:
```bash
npx ctx7@latest <command>
```
## Workflow
Two-step process: resolve the library name to an ID, then query docs with that ID.
```bash
# Step 1: Resolve library ID
ctx7 library <name> <query>
# Step 2: Query documentation
ctx7 docs <libraryId> <query>
```
You MUST call `ctx7 library` first to obtain a valid library ID UNLESS the user explicitly provides a library ID in the format `/org/project` or `/org/project/version`.
IMPORTANT: Do not run these commands more than 3 times per question. If you cannot find what you need after 3 attempts, use the best result you have.
## Step 1: Resolve a Library
Resolves a package/product name to a Context7-compatible library ID and returns matching libraries.
```bash
ctx7 library react "How to clean up useEffect with async operations"
ctx7 library nextjs "How to set up app router with middleware"
ctx7 library prisma "How to define one-to-many relations with cascade delete"
```
Always pass a `query` argument — it is required and directly affects result ranking. Use the user's intent to form the query, which helps disambiguate when multiple libraries share a similar name. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query.
### Result fields
Each result includes:
- **Library ID** — Context7-compatible identifier (format: `/org/project`)
- **Name** — Library or package name
- **Description** — Short summary
- **Code Snippets** — Number of available code examples
- **Source Reputation** — Authority indicator (High, Medium, Low, or Unknown)
- **Benchmark Score** — Quality indicator (100 is the highest score)
- **Versions** — List of versions if available. Use one of those versions if the user provides a version in their query. The format is `/org/project/version`.
### Selection process
1. Analyze the query to understand what library/package the user is looking for
2. Select the most relevant match based on:
- Name similarity to the query (exact matches prioritized)
- Description relevance to the query's intent
- Documentation coverage (prioritize libraries with higher Code Snippet counts)
- Source reputation (consider libraries with High or Medium reputation more authoritative)
- Benchmark score (higher is better, 100 is the maximum)
3. If multiple good matches exist, acknowledge this but proceed with the most relevant one
4. If no good matches exist, clearly state this and suggest query refinements
5. For ambiguous queries, request clarification before proceeding with a best-guess match
### Version-specific IDs
If the user mentions a specific version, use a version-specific library ID:
```bash
# General (latest indexed)
ctx7 docs /vercel/next.js "How to set up app router"
# Version-specific
ctx7 docs /vercel/next.js/v14.3.0-canary.87 "How to set up app router"
```
The available versions are listed in the `ctx7 library` output. Use the closest match to what the user specified.
## Step 2: Query Documentation
Retrieves up-to-date documentation and code examples for the resolved library.
```bash
ctx7 docs /facebook/react "How to clean up useEffect with async operations"
ctx7 docs /vercel/next.js "How to add authentication middleware to app router"
ctx7 docs /prisma/prisma "How to define one-to-many relations with cascade delete"
```
### Writing good queries
The query directly affects the quality of results. Be specific and include relevant details. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query.
| Quality | Example |
|---------|---------|
| Good | `"How to set up authentication with JWT in Express.js"` |
| Good | `"React useEffect cleanup function with async operations"` |
| Bad | `"auth"` |
| Bad | `"hooks"` |
Use the user's full question as the query when possible, vague one-word queries return generic results.
The output contains two types of content: **code snippets** (titled, with language-tagged blocks) and **info snippets** (prose explanations with breadcrumb context).
## Authentication
Works without authentication. For higher rate limits:
```bash
# Option A: environment variable
export CONTEXT7_API_KEY=your_key
# Option B: OAuth login
ctx7 login
```
## Error Handling
If a command fails with a quota error ("Monthly quota reached" or "quota exceeded"):
1. Inform the user their Context7 quota is exhausted
2. Suggest they authenticate for higher limits: `ctx7 login`
3. If they cannot or choose not to authenticate, answer from training knowledge and clearly note it may be outdated
Do not silently fall back to training data — always tell the user why Context7 was not used.
## Common Mistakes
- Library IDs require a `/` prefix — `/facebook/react` not `facebook/react`
- Always run `ctx7 library` first — `ctx7 docs react "hooks"` will fail without a valid ID
- Use descriptive queries, not single words — `"React useEffect cleanup function"` not `"hooks"`
- Do not include sensitive information (API keys, passwords, credentials) in queries

142
.config/opencode/skills/find-skills/SKILL.md Normal file
View File

@@ -0,0 +1,142 @@
---
name: find-skills
description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
---
# Find Skills
This skill helps you discover and install skills from the open agent skills ecosystem.
## When to Use This Skill
Use this skill when the user:
- Asks "how do I do X" where X might be a common task with an existing skill
- Says "find a skill for X" or "is there a skill for X"
- Asks "can you do X" where X is a specialized capability
- Expresses interest in extending agent capabilities
- Wants to search for tools, templates, or workflows
- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
## What is the Skills CLI?
The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
**Key commands:**
- `npx skills find [query]` - Search for skills interactively or by keyword
- `npx skills add <package>` - Install a skill from GitHub or other sources
- `npx skills check` - Check for skill updates
- `npx skills update` - Update all installed skills
**Browse skills at:** https://skills.sh/
## How to Help Users Find Skills
### Step 1: Understand What They Need
When a user asks for help with something, identify:
1. The domain (e.g., React, testing, design, deployment)
2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
3. Whether this is a common enough task that a skill likely exists
### Step 2: Check the Leaderboard First
Before running a CLI search, check the [skills.sh leaderboard](https://skills.sh/) to see if a well-known skill already exists for the domain. The leaderboard ranks skills by total installs, surfacing the most popular and battle-tested options.
For example, top skills for web development include:
- `vercel-labs/agent-skills` — React, Next.js, web design (100K+ installs each)
- `anthropics/skills` — Frontend design, document processing (100K+ installs)
### Step 3: Search for Skills
If the leaderboard doesn't cover the user's need, run the find command:
```bash
npx skills find [query]
```
For example:
- User asks "how do I make my React app faster?" → `npx skills find react performance`
- User asks "can you help me with PR reviews?" → `npx skills find pr review`
- User asks "I need to create a changelog" → `npx skills find changelog`
### Step 4: Verify Quality Before Recommending
**Do not recommend a skill based solely on search results.** Always verify:
1. **Install count** — Prefer skills with 1K+ installs. Be cautious with anything under 100.
2. **Source reputation** — Official sources (`vercel-labs`, `anthropics`, `microsoft`) are more trustworthy than unknown authors.
3. **GitHub stars** — Check the source repository. A skill from a repo with <100 stars should be treated with skepticism.
### Step 5: Present Options to the User
When you find relevant skills, present them to the user with:
1. The skill name and what it does
2. The install count and source
3. The install command they can run
4. A link to learn more at skills.sh
Example response:
```
I found a skill that might help! The "react-best-practices" skill provides
React and Next.js performance optimization guidelines from Vercel Engineering.
(185K installs)
To install it:
npx skills add vercel-labs/agent-skills@react-best-practices
Learn more: https://skills.sh/vercel-labs/agent-skills/react-best-practices
```
### Step 6: Offer to Install
If the user wants to proceed, you can install the skill for them:
```bash
npx skills add <owner/repo@skill> -g -y
```
The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
## Common Skill Categories
When searching, consider these common categories:
| Category | Example Queries |
| --------------- | ---------------------------------------- |
| Web Development | react, nextjs, typescript, css, tailwind |
| Testing | testing, jest, playwright, e2e |
| DevOps | deploy, docker, kubernetes, ci-cd |
| Documentation | docs, readme, changelog, api-docs |
| Code Quality | review, lint, refactor, best-practices |
| Design | ui, ux, design-system, accessibility |
| Productivity | workflow, automation, git |
## Tips for Effective Searches
1. **Use specific keywords**: "react testing" is better than just "testing"
2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
## When No Skills Are Found
If no relevant skills exist:
1. Acknowledge that no existing skill was found
2. Offer to help with the task directly using your general capabilities
3. Suggest the user could create their own skill with `npx skills init`
Example:
```
I searched for skills related to "xyz" but didn't find any matches.
I can still help you with this task directly! Would you like me to proceed?
If this is something you do often, you could create your own skill:
npx skills init my-xyz-skill
```

200
.config/opencode/skills/finishing-a-development-branch/SKILL.md Normal file
View File

@@ -0,0 +1,200 @@
---
name: finishing-a-development-branch
description: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup
---
# Finishing a Development Branch
## Overview
Guide completion of development work by presenting clear options and handling chosen workflow.
**Core principle:** Verify tests → Present options → Execute choice → Clean up.
**Announce at start:** "I'm using the finishing-a-development-branch skill to complete this work."
## The Process
### Step 1: Verify Tests
**Before presenting options, verify tests pass:**
```bash
# Run project's test suite
npm test / cargo test / pytest / go test ./...
```
**If tests fail:**
```
Tests failing (<N> failures). Must fix before completing:
[Show failures]
Cannot proceed with merge/PR until tests pass.
```
Stop. Don't proceed to Step 2.
**If tests pass:** Continue to Step 2.
### Step 2: Determine Base Branch
```bash
# Try common base branches
git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
```
Or ask: "This branch split from main - is that correct?"
### Step 3: Present Options
Present exactly these 4 options:
```
Implementation complete. What would you like to do?
1. Merge back to <base-branch> locally
2. Push and create a Pull Request
3. Keep the branch as-is (I'll handle it later)
4. Discard this work
Which option?
```
**Don't add explanation** - keep options concise.
### Step 4: Execute Choice
#### Option 1: Merge Locally
```bash
# Switch to base branch
git checkout <base-branch>
# Pull latest
git pull
# Merge feature branch
git merge <feature-branch>
# Verify tests on merged result
<test command>
# If tests pass
git branch -d <feature-branch>
```
Then: Cleanup worktree (Step 5)
#### Option 2: Push and Create PR
```bash
# Push branch
git push -u origin <feature-branch>
# Create PR
gh pr create --title "<title>" --body "$(cat <<'EOF'
## Summary
<2-3 bullets of what changed>
## Test Plan
- [ ] <verification steps>
EOF
)"
```
Then: Cleanup worktree (Step 5)
#### Option 3: Keep As-Is
Report: "Keeping branch <name>. Worktree preserved at <path>."
**Don't cleanup worktree.**
#### Option 4: Discard
**Confirm first:**
```
This will permanently delete:
- Branch <name>
- All commits: <commit-list>
- Worktree at <path>
Type 'discard' to confirm.
```
Wait for exact confirmation.
If confirmed:
```bash
git checkout <base-branch>
git branch -D <feature-branch>
```
Then: Cleanup worktree (Step 5)
### Step 5: Cleanup Worktree
**For Options 1, 2, 4:**
Check if in worktree:
```bash
git worktree list | grep $(git branch --show-current)
```
If yes:
```bash
git worktree remove <worktree-path>
```
**For Option 3:** Keep worktree.
## Quick Reference
| Option | Merge | Push | Keep Worktree | Cleanup Branch |
|--------|-------|------|---------------|----------------|
| 1. Merge locally | ✓ | - | - | ✓ |
| 2. Create PR | - | ✓ | ✓ | - |
| 3. Keep as-is | - | - | ✓ | - |
| 4. Discard | - | - | - | ✓ (force) |
## Common Mistakes
**Skipping test verification**
- **Problem:** Merge broken code, create failing PR
- **Fix:** Always verify tests before offering options
**Open-ended questions**
- **Problem:** "What should I do next?" → ambiguous
- **Fix:** Present exactly 4 structured options
**Automatic worktree cleanup**
- **Problem:** Remove worktree when might need it (Option 2, 3)
- **Fix:** Only cleanup for Options 1 and 4
**No confirmation for discard**
- **Problem:** Accidentally delete work
- **Fix:** Require typed "discard" confirmation
## Red Flags
**Never:**
- Proceed with failing tests
- Merge without verifying tests on result
- Delete work without confirmation
- Force-push without explicit request
**Always:**
- Verify tests before offering options
- Present exactly 4 options
- Get typed confirmation for Option 4
- Clean up worktree for Options 1 & 4 only
## Integration
**Called by:**
- **subagent-driven-development** (Step 7) - After all tasks complete
- **executing-plans** (Step 5) - After all batches complete
**Pairs with:**
- **using-git-worktrees** - Cleans up worktree created by that skill

2187
.config/opencode/skills/gh-cli/SKILL.md Normal file
View File

File diff suppressed because it is too large Load Diff

124
.config/opencode/skills/git-commit/SKILL.md Normal file
View File

@@ -0,0 +1,124 @@
---
name: git-commit
description: 'Execute git commit with conventional commit message analysis, intelligent staging, and message generation. Use when user asks to commit changes, create a git commit, or mentions "/commit". Supports: (1) Auto-detecting type and scope from changes, (2) Generating conventional commit messages from diff, (3) Interactive commit with optional type/scope/description overrides, (4) Intelligent file staging for logical grouping'
license: MIT
allowed-tools: Bash
---
# Git Commit with Conventional Commits
## Overview
Create standardized, semantic git commits using the Conventional Commits specification. Analyze the actual diff to determine appropriate type, scope, and message.
## Conventional Commit Format
```
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
```
## Commit Types
| Type | Purpose |
| ---------- | ------------------------------ |
| `feat` | New feature |
| `fix` | Bug fix |
| `docs` | Documentation only |
| `style` | Formatting/style (no logic) |
| `refactor` | Code refactor (no feature/fix) |
| `perf` | Performance improvement |
| `test` | Add/update tests |
| `build` | Build system/dependencies |
| `ci` | CI/config changes |
| `chore` | Maintenance/misc |
| `revert` | Revert commit |
## Breaking Changes
```
# Exclamation mark after type/scope
feat!: remove deprecated endpoint
# BREAKING CHANGE footer
feat: allow config to extend other configs
BREAKING CHANGE: `extends` key behavior changed
```
## Workflow
### 1. Analyze Diff
```bash
# If files are staged, use staged diff
git diff --staged
# If nothing staged, use working tree diff
git diff
# Also check status
git status --porcelain
```
### 2. Stage Files (if needed)
If nothing is staged or you want to group changes differently:
```bash
# Stage specific files
git add path/to/file1 path/to/file2
# Stage by pattern
git add *.test.*
git add src/components/*
# Interactive staging
git add -p
```
**Never commit secrets** (.env, credentials.json, private keys).
### 3. Generate Commit Message
Analyze the diff to determine:
- **Type**: What kind of change is this?
- **Scope**: What area/module is affected?
- **Description**: One-line summary of what changed (present tense, imperative mood, <72 chars)
### 4. Execute Commit
```bash
# Single line
git commit -m "<type>[scope]: <description>"
# Multi-line with body/footer
git commit -m "$(cat <<'EOF'
<type>[scope]: <description>
<optional body>
<optional footer>
EOF
)"
```
## Best Practices
- One logical change per commit
- Present tense: "add" not "added"
- Imperative mood: "fix bug" not "fixes bug"
- Reference issues: `Closes #123`, `Refs #456`
- Keep description under 72 characters
## Git Safety Protocol
- NEVER update git config
- NEVER run destructive commands (--force, hard reset) without explicit request
- NEVER skip hooks (--no-verify) unless user asks
- NEVER force push to main/master
- If commit fails due to hooks, fix and create NEW commit (don't amend)

213
.config/opencode/skills/receiving-code-review/SKILL.md Normal file
View File

@@ -0,0 +1,213 @@
---
name: receiving-code-review
description: Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation
---
# Code Review Reception
## Overview
Code review requires technical evaluation, not emotional performance.
**Core principle:** Verify before implementing. Ask before assuming. Technical correctness over social comfort.
## The Response Pattern
```
WHEN receiving code review feedback:
1. READ: Complete feedback without reacting
2. UNDERSTAND: Restate requirement in own words (or ask)
3. VERIFY: Check against codebase reality
4. EVALUATE: Technically sound for THIS codebase?
5. RESPOND: Technical acknowledgment or reasoned pushback
6. IMPLEMENT: One item at a time, test each
```
## Forbidden Responses
**NEVER:**
- "You're absolutely right!" (explicit CLAUDE.md violation)
- "Great point!" / "Excellent feedback!" (performative)
- "Let me implement that now" (before verification)
**INSTEAD:**
- Restate the technical requirement
- Ask clarifying questions
- Push back with technical reasoning if wrong
- Just start working (actions > words)
## Handling Unclear Feedback
```
IF any item is unclear:
STOP - do not implement anything yet
ASK for clarification on unclear items
WHY: Items may be related. Partial understanding = wrong implementation.
```
**Example:**
```
your human partner: "Fix 1-6"
You understand 1,2,3,6. Unclear on 4,5.
❌ WRONG: Implement 1,2,3,6 now, ask about 4,5 later
✅ RIGHT: "I understand items 1,2,3,6. Need clarification on 4 and 5 before proceeding."
```
## Source-Specific Handling
### From your human partner
- **Trusted** - implement after understanding
- **Still ask** if scope unclear
- **No performative agreement**
- **Skip to action** or technical acknowledgment
### From External Reviewers
```
BEFORE implementing:
1. Check: Technically correct for THIS codebase?
2. Check: Breaks existing functionality?
3. Check: Reason for current implementation?
4. Check: Works on all platforms/versions?
5. Check: Does reviewer understand full context?
IF suggestion seems wrong:
Push back with technical reasoning
IF can't easily verify:
Say so: "I can't verify this without [X]. Should I [investigate/ask/proceed]?"
IF conflicts with your human partner's prior decisions:
Stop and discuss with your human partner first
```
**your human partner's rule:** "External feedback - be skeptical, but check carefully"
## YAGNI Check for "Professional" Features
```
IF reviewer suggests "implementing properly":
grep codebase for actual usage
IF unused: "This endpoint isn't called. Remove it (YAGNI)?"
IF used: Then implement properly
```
**your human partner's rule:** "You and reviewer both report to me. If we don't need this feature, don't add it."
## Implementation Order
```
FOR multi-item feedback:
1. Clarify anything unclear FIRST
2. Then implement in this order:
- Blocking issues (breaks, security)
- Simple fixes (typos, imports)
- Complex fixes (refactoring, logic)
3. Test each fix individually
4. Verify no regressions
```
## When To Push Back
Push back when:
- Suggestion breaks existing functionality
- Reviewer lacks full context
- Violates YAGNI (unused feature)
- Technically incorrect for this stack
- Legacy/compatibility reasons exist
- Conflicts with your human partner's architectural decisions
**How to push back:**
- Use technical reasoning, not defensiveness
- Ask specific questions
- Reference working tests/code
- Involve your human partner if architectural
**Signal if uncomfortable pushing back out loud:** "Strange things are afoot at the Circle K"
## Acknowledging Correct Feedback
When feedback IS correct:
```
✅ "Fixed. [Brief description of what changed]"
✅ "Good catch - [specific issue]. Fixed in [location]."
✅ [Just fix it and show in the code]
❌ "You're absolutely right!"
❌ "Great point!"
❌ "Thanks for catching that!"
❌ "Thanks for [anything]"
❌ ANY gratitude expression
```
**Why no thanks:** Actions speak. Just fix it. The code itself shows you heard the feedback.
**If you catch yourself about to write "Thanks":** DELETE IT. State the fix instead.
## Gracefully Correcting Your Pushback
If you pushed back and were wrong:
```
✅ "You were right - I checked [X] and it does [Y]. Implementing now."
✅ "Verified this and you're correct. My initial understanding was wrong because [reason]. Fixing."
❌ Long apology
❌ Defending why you pushed back
❌ Over-explaining
```
State the correction factually and move on.
## Common Mistakes
| Mistake | Fix |
|---------|-----|
| Performative agreement | State requirement or just act |
| Blind implementation | Verify against codebase first |
| Batch without testing | One at a time, test each |
| Assuming reviewer is right | Check if breaks things |
| Avoiding pushback | Technical correctness > comfort |
| Partial implementation | Clarify all items first |
| Can't verify, proceed anyway | State limitation, ask for direction |
## Real Examples
**Performative Agreement (Bad):**
```
Reviewer: "Remove legacy code"
❌ "You're absolutely right! Let me remove that..."
```
**Technical Verification (Good):**
```
Reviewer: "Remove legacy code"
✅ "Checking... build target is 10.15+, this API needs 13+. Need legacy for backward compat. Current impl has wrong bundle ID - fix it or drop pre-13 support?"
```
**YAGNI (Good):**
```
Reviewer: "Implement proper metrics tracking with database, date filters, CSV export"
✅ "Grepped codebase - nothing calls this endpoint. Remove it (YAGNI)? Or is there usage I'm missing?"
```
**Unclear Item (Good):**
```
your human partner: "Fix items 1-6"
You understand 1,2,3,6. Unclear on 4,5.
✅ "Understand 1,2,3,6. Need clarification on 4 and 5 before implementing."
```
## GitHub Thread Replies
When replying to inline review comments on GitHub, reply in the comment thread (`gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`), not as a top-level PR comment.
## The Bottom Line
**External feedback = suggestions to evaluate, not orders to follow.**
Verify. Question. Then implement.
No performative agreement. Technical rigor always.

105
.config/opencode/skills/requesting-code-review/SKILL.md Normal file
View File

@@ -0,0 +1,105 @@
---
name: requesting-code-review
description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements
---
# Requesting Code Review
Dispatch superpowers:code-reviewer subagent to catch issues before they cascade. The reviewer gets precisely crafted context for evaluation — never your session's history. This keeps the reviewer focused on the work product, not your thought process, and preserves your own context for continued work.
**Core principle:** Review early, review often.
## When to Request Review
**Mandatory:**
- After each task in subagent-driven development
- After completing major feature
- Before merge to main
**Optional but valuable:**
- When stuck (fresh perspective)
- Before refactoring (baseline check)
- After fixing complex bug
## How to Request
**1. Get git SHAs:**
```bash
BASE_SHA=$(git rev-parse HEAD~1) # or origin/main
HEAD_SHA=$(git rev-parse HEAD)
```
**2. Dispatch code-reviewer subagent:**
Use Task tool with superpowers:code-reviewer type, fill template at `code-reviewer.md`
**Placeholders:**
- `{WHAT_WAS_IMPLEMENTED}` - What you just built
- `{PLAN_OR_REQUIREMENTS}` - What it should do
- `{BASE_SHA}` - Starting commit
- `{HEAD_SHA}` - Ending commit
- `{DESCRIPTION}` - Brief summary
**3. Act on feedback:**
- Fix Critical issues immediately
- Fix Important issues before proceeding
- Note Minor issues for later
- Push back if reviewer is wrong (with reasoning)
## Example
```
[Just completed Task 2: Add verification function]
You: Let me request code review before proceeding.
BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
HEAD_SHA=$(git rev-parse HEAD)
[Dispatch superpowers:code-reviewer subagent]
WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index
PLAN_OR_REQUIREMENTS: Task 2 from docs/superpowers/plans/deployment-plan.md
BASE_SHA: a7981ec
HEAD_SHA: 3df7661
DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
[Subagent returns]:
Strengths: Clean architecture, real tests
Issues:
Important: Missing progress indicators
Minor: Magic number (100) for reporting interval
Assessment: Ready to proceed
You: [Fix progress indicators]
[Continue to Task 3]
```
## Integration with Workflows
**Subagent-Driven Development:**
- Review after EACH task
- Catch issues before they compound
- Fix before moving to next task
**Executing Plans:**
- Review after each batch (3 tasks)
- Get feedback, apply, continue
**Ad-Hoc Development:**
- Review before merge
- Review when stuck
## Red Flags
**Never:**
- Skip review because "it's simple"
- Ignore Critical issues
- Proceed with unfixed Important issues
- Argue with valid technical feedback
**If reviewer wrong:**
- Push back with technical reasoning
- Show code/tests that prove it works
- Request clarification
See template at: requesting-code-review/code-reviewer.md

146
.config/opencode/skills/requesting-code-review/code-reviewer.md Normal file
View File

@@ -0,0 +1,146 @@
# Code Review Agent
You are reviewing code changes for production readiness.
**Your task:**
1. Review {WHAT_WAS_IMPLEMENTED}
2. Compare against {PLAN_OR_REQUIREMENTS}
3. Check code quality, architecture, testing
4. Categorize issues by severity
5. Assess production readiness
## What Was Implemented
{DESCRIPTION}
## Requirements/Plan
{PLAN_REFERENCE}
## Git Range to Review
**Base:** {BASE_SHA}
**Head:** {HEAD_SHA}
```bash
git diff --stat {BASE_SHA}..{HEAD_SHA}
git diff {BASE_SHA}..{HEAD_SHA}
```
## Review Checklist
**Code Quality:**
- Clean separation of concerns?
- Proper error handling?
- Type safety (if applicable)?
- DRY principle followed?
- Edge cases handled?
**Architecture:**
- Sound design decisions?
- Scalability considerations?
- Performance implications?
- Security concerns?
**Testing:**
- Tests actually test logic (not mocks)?
- Edge cases covered?
- Integration tests where needed?
- All tests passing?
**Requirements:**
- All plan requirements met?
- Implementation matches spec?
- No scope creep?
- Breaking changes documented?
**Production Readiness:**
- Migration strategy (if schema changes)?
- Backward compatibility considered?
- Documentation complete?
- No obvious bugs?
## Output Format
### Strengths
[What's well done? Be specific.]
### Issues
#### Critical (Must Fix)
[Bugs, security issues, data loss risks, broken functionality]
#### Important (Should Fix)
[Architecture problems, missing features, poor error handling, test gaps]
#### Minor (Nice to Have)
[Code style, optimization opportunities, documentation improvements]
**For each issue:**
- File:line reference
- What's wrong
- Why it matters
- How to fix (if not obvious)
### Recommendations
[Improvements for code quality, architecture, or process]
### Assessment
**Ready to merge?** [Yes/No/With fixes]
**Reasoning:** [Technical assessment in 1-2 sentences]
## Critical Rules
**DO:**
- Categorize by actual severity (not everything is Critical)
- Be specific (file:line, not vague)
- Explain WHY issues matter
- Acknowledge strengths
- Give clear verdict
**DON'T:**
- Say "looks good" without checking
- Mark nitpicks as Critical
- Give feedback on code you didn't review
- Be vague ("improve error handling")
- Avoid giving a clear verdict
## Example Output
```
### Strengths
- Clean database schema with proper migrations (db.ts:15-42)
- Comprehensive test coverage (18 tests, all edge cases)
- Good error handling with fallbacks (summarizer.ts:85-92)
### Issues
#### Important
1. **Missing help text in CLI wrapper**
- File: index-conversations:1-31
- Issue: No --help flag, users won't discover --concurrency
- Fix: Add --help case with usage examples
2. **Date validation missing**
- File: search.ts:25-27
- Issue: Invalid dates silently return no results
- Fix: Validate ISO format, throw error with example
#### Minor
1. **Progress indicators**
- File: indexer.ts:130
- Issue: No "X of Y" counter for long operations
- Impact: Users don't know how long to wait
### Recommendations
- Add progress reporting for user experience
- Consider config file for excluded projects (portability)
### Assessment
**Ready to merge: With fixes**
**Reasoning:** Core implementation is solid with good architecture and tests. Important issues (help text, date validation) are easily fixed and don't affect core functionality.
```

236
.config/opencode/skills/skill-migrator/SKILL.md Normal file
View File

@@ -0,0 +1,236 @@
---
name: skill-migrator
description: This skill should be used when the user asks to "migrate skills from a directory", "import tools to opencode", "move llm tools", "copy skills from a path", "transfer skills to opencode", "install skills from a directory", or migrate LLM tools between directories
license: MIT
compatibility: opencode
metadata:
category: tools
version: "1.0.0"
---
# Skill Migrator
Migrate LLM tools and skills from any directory to OpenCode's skills directory. Supports both global (`~/.config/opencode/skills/`) and local project (`.opencode/skills/`) installations.
## Overview
This skill provides a streamlined way to import skills from external sources or backup locations into OpenCode. It handles skill discovery, conflict resolution, and installation to the appropriate location.
## Common Use Cases
### Migrate Skills from a Directory
Import all skills from a source directory:
```bash
scripts/migrate.sh /path/to/source/skills
```
The script will:
1. Recursively discover all skills (directories containing `SKILL.md`)
2. List found skills and ask which to migrate
3. Handle conflicts interactively (overwrite/skip/backup)
4. Install to global skills directory by default
### Non-Interactive Mode (Automation-Friendly)
For use with opencode or automated workflows, use the non-interactive flags:
```bash
# Migrate all skills without prompts
scripts/migrate.sh /path/to/source/skills --all --yes
# Migrate all, skip existing skills (no overwrite)
scripts/migrate.sh /path/to/source/skills --all --yes --conflict-strategy skip
# Migrate all, overwrite existing skills
scripts/migrate.sh /path/to/source/skills --all --yes --conflict-strategy overwrite
# Migrate all, backup existing before overwriting
scripts/migrate.sh /path/to/source/skills --all --yes --conflict-strategy backup
```
### Install to Local Project
Migrate skills to the current project's local skills directory:
```bash
# Interactive mode
scripts/migrate.sh /path/to/source/skills --local
# Non-interactive mode
scripts/migrate.sh /path/to/source/skills --local --all --yes
```
### Dry Run (Preview)
See what would be migrated without making changes:
```bash
# Preview only
scripts/migrate.sh /path/to/source/skills --dry-run
# Preview with non-interactive flags
scripts/migrate.sh /path/to/source/skills --all --dry-run
```
### Migrate Specific Skills
After discovery, the script presents an interactive menu to select which skills to migrate. Choose specific skills or migrate all discovered skills.
## Migration Process
### Step 1: Discovery
The script searches the source directory recursively for skills:
- Looks for directories containing `SKILL.md`
- Lists all discovered skills with their paths
### Step 2: Selection
Interactive selection menu:
- View all discovered skills
- Select individual skills or all
- Confirm before proceeding
Use `--all` flag to skip selection and migrate all discovered skills.
### Step 3: Conflict Resolution
For each skill that already exists at the destination:
- **Overwrite**: Replace existing skill
- **Skip**: Keep existing skill, skip this one
- **Backup**: Create backup with timestamp, then overwrite
Use `--conflict-strategy <strategy>` to set a default strategy and avoid prompts.
### Step 4: Installation
Copies selected skills to destination:
- Preserves directory structure
- Maintains file permissions
- Copies all skill contents as-is
### Step 5: Report
Generates a migration report showing:
- Successfully migrated skills
- Skipped skills (with reason)
- Backed up skills (with backup location)
- Any errors encountered
## Scripts
Use the migration script:
- `scripts/migrate.sh` - Main migration script with interactive and non-interactive workflow
### Script Usage
```bash
scripts/migrate.sh [OPTIONS] <source-directory>
Options:
-a, --all Migrate all discovered skills without prompting
-c, --conflict-strategy Set conflict resolution: skip, overwrite, backup
-y, --yes Auto-confirm all prompts without interaction
-l, --local Install to local project (.opencode/skills/)
-g, --global Install to global directory (~/.config/opencode/skills/)
-d, --dry-run Preview changes without migrating
-h, --help Show help message
Interactive Mode (default):
The script will prompt for skill selection, conflict resolution, and confirmation.
Non-Interactive Mode:
Use -a/--all, -y/--yes, and -c/--conflict-strategy for automated usage.
Examples:
# Interactive mode
scripts/migrate.sh ~/my-skills
# Non-interactive: migrate all
scripts/migrate.sh ~/my-skills --all --yes
# Non-interactive: migrate all, skip existing
scripts/migrate.sh ~/my-skills --all --yes --conflict-strategy skip
# Non-interactive: migrate all, overwrite existing
scripts/migrate.sh ~/my-skills --all --yes --conflict-strategy overwrite
# Dry run
scripts/migrate.sh ~/my-skills --all --dry-run
# Local project installation
scripts/migrate.sh ~/my-skills --local --all --yes
```
## Target Locations
### Global Skills (Default)
Installed to: `~/.config/opencode/skills/`
- Available across all projects
- Shared OpenCode installation
- Best for commonly used skills
### Local Project Skills
Installed to: `./.opencode/skills/`
- Project-specific skills only
- Version controlled with project
- Team-shared within project
## Non-Interactive Mode
For use with opencode and coding agents, the script supports full automation:
### Flags for Automation
- `--all`: Skip skill selection and migrate all discovered skills
- `--yes`: Skip confirmation prompts and proceed automatically
- `--conflict-strategy <strategy>`: Set default conflict handling (skip/overwrite/backup)
### Example Automation Scenarios
**Migrate all skills, skip existing:**
```bash
scripts/migrate.sh ~/my-skills --all --yes --conflict-strategy skip
```
**Migrate all skills, overwrite existing:**
```bash
scripts/migrate.sh ~/my-skills --all --yes --conflict-strategy overwrite
```
**Migrate all skills, backup existing:**
```bash
scripts/migrate.sh ~/my-skills --all --yes --conflict-strategy backup
```
**Dry run to preview changes:**
```bash
scripts/migrate.sh ~/my-skills --all --dry-run
```
### Conflict Strategies
- `skip`: Keep existing skills, skip migrating those that already exist
- `overwrite`: Replace existing skills with the new versions
- `backup`: Create timestamped backups of existing skills before overwriting
## Important Notes
- Skills are copied as-is without validation
- File permissions are preserved during migration
- Backups are stored with timestamp: `skillname.backup.YYYYMMDD_HHMMSS`
- Empty directories and non-skill folders are ignored
- The script requires write permissions to the destination directory
- Use `--all`, `--yes`, and `--conflict-strategy` flags for non-interactive usage with opencode
- Non-interactive mode is ideal for automated workflows and CI/CD pipelines
## Troubleshooting
See `references/migration-guide.md` for detailed troubleshooting and advanced usage.

62
.config/opencode/skills/skill-migrator/evals/evals.json Normal file
View File

@@ -0,0 +1,62 @@
{
"skill_name": "skill-migrator",
"evals": [
{
"id": 1,
"name": "basic-non-interactive-migration",
"prompt": "Migrate all skills from ~/.agents to the global opencode skills directory without any interactive prompts. Use the skill-migrator skill.",
"expected_output": "The agent should use the migrate.sh script with --all and --yes flags to perform a non-interactive migration. No prompts should be displayed.",
"assertions": [
"Agent identifies the correct script path",
"Agent uses --all flag to select all skills",
"Agent uses --yes flag to auto-confirm",
"Migration completes without interactive prompts"
]
},
{
"id": 2,
"name": "migration-with-conflict-resolution",
"prompt": "Migrate skills from ~/.agents to the global skills directory. Some skills may already exist at the destination. Use the skill-migrator to handle conflicts by skipping existing skills automatically.",
"expected_output": "The agent should use --conflict-strategy skip to automatically handle conflicts without prompting.",
"assertions": [
"Agent uses --conflict-strategy skip flag",
"Agent includes --all and --yes for non-interactive mode",
"Existing skills are skipped without prompts"
]
},
{
"id": 3,
"name": "dry-run-preview",
"prompt": "Preview what would be migrated from ~/.agents without actually making any changes. Show what skills would be migrated and how conflicts would be handled.",
"expected_output": "The agent should use --dry-run flag to preview changes without making them.",
"assertions": [
"Agent uses --dry-run flag",
"Agent may also use --all to preview all skills",
"No actual file changes are made",
"Preview output shows discovered skills"
]
},
{
"id": 4,
"name": "local-project-installation",
"prompt": "Migrate skills from ~/.agents to the local project directory (.opencode/skills/) instead of the global directory. Make it non-interactive.",
"expected_output": "The agent should use --local flag along with non-interactive flags.",
"assertions": [
"Agent uses --local flag",
"Agent uses --all and --yes for non-interactive mode",
"Target directory is the local .opencode/skills/ directory"
]
},
{
"id": 5,
"name": "backup-conflict-strategy",
"prompt": "Migrate skills from ~/.agents. If any skills already exist, create backups of the existing ones before overwriting them. Do this without any prompts.",
"expected_output": "The agent should use --conflict-strategy backup to create backups before overwriting.",
"assertions": [
"Agent uses --conflict-strategy backup",
"Agent includes --all and --yes",
"Existing skills are backed up with timestamps"
]
}
]
}

231
.config/opencode/skills/skill-migrator/evals/run-tests.sh Executable file
View File

@@ -0,0 +1,231 @@
#!/bin/bash
#
# Skill Migrator Test Script
# Tests the non-interactive mode functionality
set -e
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
MIGRATE_SCRIPT="$HOME/.config/opencode/skills/skill-migrator/scripts/migrate.sh"
TEST_DIR="$HOME/.agents-test"
echo "========================================"
echo " SKILL MIGRATOR TEST SUITE"
echo "========================================"
echo ""
# Setup: Create test skills
setup_test_env() {
echo "Setting up test environment..."
rm -rf "$TEST_DIR"
mkdir -p "$TEST_DIR"
# Create a test skill
mkdir -p "$TEST_DIR/test-skill-1"
cat > "$TEST_DIR/test-skill-1/SKILL.md" << 'EOF'
---
name: test-skill-1
description: Test skill 1 for migration testing
---
# Test Skill 1
This is a test skill.
EOF
# Create another test skill
mkdir -p "$TEST_DIR/test-skill-2"
cat > "$TEST_DIR/test-skill-2/SKILL.md" << 'EOF'
---
name: test-skill-2
description: Test skill 2 for migration testing
---
# Test Skill 2
This is another test skill.
EOF
echo "✓ Test environment created"
echo ""
}
# Test 1: Basic non-interactive migration
test_basic_migration() {
echo "Test 1: Basic Non-Interactive Migration"
echo "----------------------------------------"
# Clean target
rm -rf "$HOME/.config/opencode/skills/test-skill-1"
rm -rf "$HOME/.config/opencode/skills/test-skill-2"
# Run migration with non-interactive flags
if "$MIGRATE_SCRIPT" "$TEST_DIR" --all --yes; then
echo "✓ Migration completed successfully"
else
echo "✗ Migration failed"
return 1
fi
# Verify skills were migrated
if [[ -d "$HOME/.config/opencode/skills/test-skill-1" && -d "$HOME/.config/opencode/skills/test-skill-2" ]]; then
echo "✓ Skills migrated to correct location"
else
echo "✗ Skills not found in target directory"
return 1
fi
echo ""
}
# Test 2: Skip conflict strategy
test_skip_strategy() {
echo "Test 2: Skip Conflict Strategy"
echo "-------------------------------"
# Modify source skill
echo "# Modified" >> "$TEST_DIR/test-skill-1/SKILL.md"
# Run migration with skip strategy
if "$MIGRATE_SCRIPT" "$TEST_DIR" --all --yes --conflict-strategy skip; then
echo "✓ Migration with skip strategy completed"
else
echo "✗ Migration failed"
return 1
fi
# Verify original skill was NOT overwritten
if ! grep -q "# Modified" "$HOME/.config/opencode/skills/test-skill-1/SKILL.md"; then
echo "✓ Existing skill was skipped (not overwritten)"
else
echo "✗ Existing skill was overwritten (should have been skipped)"
return 1
fi
echo ""
}
# Test 3: Overwrite conflict strategy
test_overwrite_strategy() {
echo "Test 3: Overwrite Conflict Strategy"
echo "------------------------------------"
# Run migration with overwrite strategy
if "$MIGRATE_SCRIPT" "$TEST_DIR" --all --yes --conflict-strategy overwrite; then
echo "✓ Migration with overwrite strategy completed"
else
echo "✗ Migration failed"
return 1
fi
# Verify skill WAS overwritten
if grep -q "# Modified" "$HOME/.config/opencode/skills/test-skill-1/SKILL.md"; then
echo "✓ Existing skill was overwritten"
else
echo "✗ Existing skill was not overwritten"
return 1
fi
echo ""
}
# Test 4: Backup conflict strategy
test_backup_strategy() {
echo "Test 4: Backup Conflict Strategy"
echo "---------------------------------"
# Run migration with backup strategy
if "$MIGRATE_SCRIPT" "$TEST_DIR" --all --yes --conflict-strategy backup; then
echo "✓ Migration with backup strategy completed"
else
echo "✗ Migration failed"
return 1
fi
# Verify backup was created
if ls "$HOME/.config/opencode/skills/test-skill-1.backup."* 1> /dev/null 2>&1; then
echo "✓ Backup was created"
else
echo "✗ Backup not found"
return 1
fi
echo ""
}
# Test 5: Dry run
test_dry_run() {
echo "Test 5: Dry Run Mode"
echo "---------------------"
# Create a new test skill that doesn't exist yet
mkdir -p "$TEST_DIR/test-skill-3"
cat > "$TEST_DIR/test-skill-3/SKILL.md" << 'EOF'
---
name: test-skill-3
description: Test skill 3 for dry run testing
---
# Test Skill 3
This skill should not be migrated in dry run.
EOF
# Run migration with dry-run
if "$MIGRATE_SCRIPT" "$TEST_DIR" --all --dry-run; then
echo "✓ Dry run completed"
else
echo "✗ Dry run failed"
return 1
fi
# Verify skill was NOT actually migrated
if [[ ! -d "$HOME/.config/opencode/skills/test-skill-3" ]]; then
echo "✓ Dry run correctly made no changes"
else
echo "✗ Skill was migrated (should not happen in dry run)"
return 1
fi
echo ""
}
# Cleanup
cleanup() {
echo "Cleaning up..."
rm -rf "$TEST_DIR"
rm -rf "$HOME/.config/opencode/skills/test-skill-1"
rm -rf "$HOME/.config/opencode/skills/test-skill-2"
rm -rf "$HOME/.config/opencode/skills/test-skill-3"
rm -f "$HOME/.config/opencode/skills/test-skill-1.backup."*
echo "✓ Cleanup complete"
echo ""
}
# Run all tests
main() {
setup_test_env
local failed=0
test_basic_migration || ((failed++))
test_skip_strategy || ((failed++))
test_overwrite_strategy || ((failed++))
test_backup_strategy || ((failed++))
test_dry_run || ((failed++))
cleanup
echo "========================================"
echo " TEST RESULTS"
echo "========================================"
if [[ $failed -eq 0 ]]; then
echo "✓ All tests passed!"
exit 0
else
echo "✗ $failed test(s) failed"
exit 1
fi
}
main "$@"

438
.config/opencode/skills/skill-migrator/references/migration-guide.md Normal file
View File

@@ -0,0 +1,438 @@
# Skill Migration Guide
Comprehensive guide for migrating LLM tools and skills to OpenCode.
## Table of Contents
1. [Quick Start](#quick-start)
2. [Usage Examples](#usage-examples)
3. [Interactive Workflow](#interactive-workflow)
4. [Conflict Resolution](#conflict-resolution)
5. [Troubleshooting](#troubleshooting)
6. [Advanced Usage](#advanced-usage)
## Quick Start
### Basic Migration
Migrate all skills from a directory to global OpenCode:
```bash
# Discover and migrate skills
~/.config/opencode/skills/skill-migrator/scripts/migrate.sh /path/to/skills
# Or if you're in the skill-migrator directory
./scripts/migrate.sh /path/to/skills
```
### Migrate to Local Project
```bash
./scripts/migrate.sh /path/to/skills --local
```
## Usage Examples
### Example 1: Migrating from Backup
You have a backup of skills in `~/backups/opencode-skills/`:
```bash
./scripts/migrate.sh ~/backups/opencode-skills
```
**Workflow:**
1. Script discovers all skills containing `SKILL.md`
2. Lists discovered skills with numbers
3. You select which to migrate (or 'a' for all)
4. For existing skills, choose: overwrite/skip/backup
5. Migration completes with a report
### Example 2: Preview Before Migrating
See what would be migrated without making changes:
```bash
./scripts/migrate.sh ~/external-tools --dry-run
```
This shows:
- Which skills would be discovered
- Which already exist at destination
- No actual changes are made
### Example 3: Selective Migration
Migrate only specific skills:
```bash
./scripts/migrate.sh ~/my-tools
# At selection prompt, enter: 1,3,5
# Only skills 1, 3, and 5 will be migrated
```
### Example 4: Local Development
Working on a project that needs specific skills:
```bash
# In your project directory
./scripts/migrate.sh ~/project-skills --local
# Skills installed to ./.opencode/skills/
# Can be version controlled with your project
```
## Interactive Workflow
### Discovery Phase
The script searches recursively for directories containing `SKILL.md`:
```
ℹ Discovering skills in: /home/user/external-skills
✓ Found 5 skill(s)
Discovered Skills:
==================
1. docker-helper (/home/user/external-skills/docker-helper)
2. git-workflow (/home/user/external-skills/workflows/git-workflow)
3. api-tester (/home/user/external-skills/devtools/api-tester)
4. doc-generator (/home/user/external-skills/docs/doc-generator)
5. test-validator (/home/user/external-skills/qa/test-validator)
```
### Selection Phase
Choose which skills to migrate:
```
Select skills to migrate:
[a] - Migrate all
[1-5] - Select specific skill(s) by number (comma-separated)
[q] - Quit
Your choice: 1,3,5
```
### Confirmation
Before proceeding:
```
Ready to migrate 3 skill(s).
Continue? [Y/n]: Y
```
### Migration Progress
Live progress as skills are migrated:
```
ℹ Migrating: docker-helper
⚠ Skill already exists: docker-helper
Location: ~/.config/opencode/skills/docker-helper
Options:
[o] - Overwrite (replace existing)
[s] - Skip (keep existing)
[b] - Backup (create backup, then overwrite)
Your choice [o/s/b]: b
ℹ Backed up to: ~/.config/opencode/skills/docker-helper.backup.20240319_143052
✓ Migrated: docker-helper
ℹ Migrating: api-tester
✓ Migrated: api-tester
ℹ Migrating: test-validator
✓ Migrated: test-validator
```
### Final Report
```
========================================
MIGRATION REPORT
========================================
✓ Successfully Migrated (3):
• docker-helper
• api-tester
• test-validator
ℹ Backed Up (1):
• docker-helper -> ~/.config/opencode/skills/docker-helper.backup.20240319_143052
Target Directory: ~/.config/opencode/skills
========================================
```
## Conflict Resolution
### When Conflicts Occur
A conflict happens when a skill with the same name already exists at the destination.
### Options
#### 1. Overwrite
- **When to use:** The new version is newer/better, or you don't need the old one
- **Result:** Existing skill is completely replaced
- **Risk:** You lose the old version permanently
#### 2. Skip
- **When to use:** You want to keep the existing skill as-is
- **Result:** New skill is not migrated
- **Use case:** The existing skill has customizations you want to keep
#### 3. Backup
- **When to use:** You want both versions (safe option)
- **Result:** Old skill backed up with timestamp, new skill installed
- **Backup location:** `~/.config/opencode/skills/skillname.backup.YYYYMMDD_HHMMSS`
### Best Practices
- **Always choose backup** when unsure - you can manually merge later
- **Use skip** if you've customized the existing skill
- **Use overwrite** if the source is definitely newer/correct
## Troubleshooting
### Issue: "No skills found"
**Symptoms:**
```
⚠ No skills found in: /path/to/source
ℹ Looking for directories containing 'SKILL.md'
```
**Solutions:**
1. **Verify source structure:**
```bash
# Check if SKILL.md files exist
find /path/to/source -name "SKILL.md" -type f
```
2. **Check file permissions:**
```bash
# Ensure you can read the directory
ls -la /path/to/source
```
3. **Verify path is correct:**
```bash
# Make sure path exists
ls -d /path/to/source
```
### Issue: "Permission denied"
**Symptoms:**
```
✗ Cannot write to target directory
```
**Solutions:**
1. **Check directory permissions:**
```bash
ls -ld ~/.config/opencode/skills
```
2. **Fix permissions:**
```bash
# For global directory
mkdir -p ~/.config/opencode/skills
chmod 755 ~/.config/opencode/skills
# For local directory
mkdir -p .opencode/skills
chmod 755 .opencode/skills
```
3. **Run with appropriate user:**
Ensure you're running as the user who owns the OpenCode config
### Issue: Script hangs or no prompt
**Symptoms:** Script stops without showing selection menu
**Solutions:**
1. **Ensure terminal is interactive:**
```bash
# Check if stdin is a terminal
[ -t 0 ] && echo "Interactive" || echo "Not interactive"
```
2. **Run in proper terminal:**
Don't run from non-interactive contexts (CI/CD, scripts without TTY)
3. **Use --dry-run first:**
```bash
./scripts/migrate.sh /path --dry-run
```
### Issue: Skills not appearing in OpenCode
**Symptoms:** Migration succeeds but OpenCode doesn't recognize new skills
**Solutions:**
1. **Check skill structure:**
```bash
# Verify SKILL.md exists
ls ~/.config/opencode/skills/new-skill/SKILL.md
```
2. **Check SKILL.md format:**
- Must start with YAML frontmatter (`---`)
- Must have `name:` field
- Must have `description:` field (20-1024 chars)
3. **Validate the skill:**
```bash
~/.config/opencode/skills/skill-builder/scripts/validate-skill.sh \
~/.config/opencode/skills/new-skill
```
4. **Restart OpenCode** if using a GUI/IDE plugin
### Issue: Backup not created
**Symptoms:** Chose 'backup' option but can't find backup
**Solutions:**
1. **Check backup location:**
```bash
ls -la ~/.config/opencode/skills/*.backup.*
```
2. **Check timestamp format:**
Backups use format: `skillname.backup.YYYYMMDD_HHMMSS`
3. **Verify not in dry-run:**
Backups are only created during actual migration, not dry-run
## Advanced Usage
### Batch Migration Script
Create a wrapper for recurring migrations:
```bash
#!/bin/bash
# migrate-from-backup.sh
BACKUP_DIR="${HOME}/backups/opencode-skills"
MIGRATOR="${HOME}/.config/opencode/skills/skill-migrator/scripts/migrate.sh"
# Always backup before overwriting
export MIGRATOR_DEFAULT_ACTION="backup"
# Run migration
"$MIGRATOR" "$BACKUP_DIR" "$@"
```
### Automated Sync
Sync skills from a git repository:
```bash
#!/bin/bash
# sync-skills.sh
SKILLS_REPO="https://github.com/company/shared-opencode-skills.git"
TEMP_DIR="/tmp/opencode-skills-sync"
MIGRATOR="${HOME}/.config/opencode/skills/skill-migrator/scripts/migrate.sh"
# Clone latest
rm -rf "$TEMP_DIR"
git clone "$SKILLS_REPO" "$TEMP_DIR"
# Dry run first
"$MIGRATOR" "$TEMP_DIR/skills" --dry-run
# Ask for confirmation
read -p "Proceed with migration? [y/N]: " confirm
if [[ "$confirm" =~ ^[Yy]$ ]]; then
"$MIGRATOR" "$TEMP_DIR/skills"
fi
# Cleanup
rm -rf "$TEMP_DIR"
```
### Selective Auto-Backup
Always backup certain critical skills:
```bash
#!/bin/bash
# safe-migrate.sh
CRITICAL_SKILLS=("production-deploy" "database-migration" "security-scan")
SOURCE_DIR="$1"
MIGRATOR="${HOME}/.config/opencode/skills/skill-migrator/scripts/migrate.sh"
# Pre-backup critical skills
for skill in "${CRITICAL_SKILLS[@]}"; do
skill_path="${HOME}/.config/opencode/skills/${skill}"
if [[ -d "$skill_path" ]]; then
timestamp=$(date +"%Y%m%d_%H%M%S")
cp -r "$skill_path" "${skill_path}.pre-migration.${timestamp}"
echo "Pre-backed up: $skill"
fi
done
# Run migration
"$MIGRATOR" "$SOURCE_DIR"
```
### Migration with Validation
Validate skills after migration:
```bash
#!/bin/bash
# migrate-and-validate.sh
SOURCE_DIR="$1"
MIGRATOR="${HOME}/.config/opencode/skills/skill-migrator/scripts/migrate.sh"
VALIDATOR="${HOME}/.config/opencode/skills/skill-builder/scripts/validate-skill.sh"
TARGET_DIR="${HOME}/.config/opencode/skills"
# Migrate
"$MIGRATOR" "$SOURCE_DIR"
# Validate all migrated skills
echo ""
echo "Validating migrated skills..."
for skill_dir in "$TARGET_DIR"/*/; do
skill_name=$(basename "$skill_dir")
if [[ -f "$skill_dir/SKILL.md" ]]; then
echo "Validating: $skill_name"
if ! "$VALIDATOR" "$skill_dir" 2>/dev/null; then
echo "⚠ $skill_name has validation issues"
fi
fi
done
```
## Tips and Best Practices
1. **Always use --dry-run first** when migrating from a new source
2. **Keep backups** until you've verified skills work in OpenCode
3. **Use local skills** for project-specific tools
4. **Use global skills** for commonly used utilities
5. **Document your skills** with clear descriptions for better OpenCode integration
6. **Test migrated skills** by asking OpenCode to use them
## See Also
- `SKILL.md` - Main skill documentation
- `skill-builder` skill - For validating and creating skills
- OpenCode documentation for skill development

527
.config/opencode/skills/skill-migrator/scripts/migrate.sh Executable file
View File

@@ -0,0 +1,527 @@
#!/bin/bash
#
# Skill Migrator - Migrate LLM tools to OpenCode skills directory
#
set -euo pipefail
# Configuration
GLOBAL_SKILLS_DIR="${HOME}/.config/opencode/skills"
LOCAL_SKILLS_DIR=".opencode/skills"
TARGET_MODE="global"
DRY_RUN=false
# Non-interactive mode flags
MIGRATE_ALL=false
AUTO_CONFIRM=false
CONFLICT_STRATEGY=""
# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color
# Data structures
declare -a DISCOVERED_SKILLS=()
declare -a DISCOVERED_PATHS=()
declare -a MIGRATED_SKILLS=()
declare -a SKIPPED_SKILLS=()
declare -a BACKED_UP_SKILLS=()
declare -a ERROR_SKILLS=()
# Show help
show_help() {
cat << EOF
Skill Migrator - Migrate LLM tools to OpenCode
Usage: $(basename "$0") [OPTIONS] <source-directory>
Migrate skills from a source directory to OpenCode's skills directory.
Options:
-a, --all Migrate all discovered skills without prompting
-c, --conflict-strategy Set conflict resolution strategy: skip, overwrite, backup
-y, --yes Auto-confirm all prompts without interaction
-l, --local Install to local project (.opencode/skills/)
-g, --global Install to global directory (default: ~/.config/opencode/skills/)
-d, --dry-run Preview changes without migrating
-h, --help Show this help message
Interactive Options:
By default, the script will prompt you to:
- Select which skills to migrate
- Resolve conflicts (overwrite/skip/backup)
- Confirm before proceeding
Use -a, -y, and -c flags for non-interactive/automated usage.
Examples:
# Interactive mode (default)
$(basename "$0") ~/my-skills
# Non-interactive: migrate all skills
$(basename "$0") ~/my-skills --all --yes
# Non-interactive: migrate all, skip existing
$(basename "$0") ~/my-skills --all --yes --conflict-strategy skip
# Non-interactive: migrate all, overwrite existing
$(basename "$0") ~/my-skills --all --yes --conflict-strategy overwrite
# Dry run (preview only)
$(basename "$0") ~/my-skills --all --dry-run
# Install to local project
$(basename "$0") ~/my-skills --local --all --yes
EOF
}
# Print colored output
print_error() {
echo -e "${RED}✗${NC} $1"
}
print_success() {
echo -e "${GREEN}✓${NC} $1"
}
print_warning() {
echo -e "${YELLOW}⚠${NC} $1"
}
print_info() {
echo -e "${BLUE}ℹ${NC} $1"
}
# Parse command line arguments
parse_args() {
SOURCE_DIR=""
while [[ $# -gt 0 ]]; do
case $1 in
-h|--help)
show_help
exit 0
;;
-a|--all)
MIGRATE_ALL=true
shift
;;
-y|--yes)
AUTO_CONFIRM=true
shift
;;
-c|--conflict-strategy)
if [[ -n "${2:-}" && ! "$2" =~ ^- ]]; then
CONFLICT_STRATEGY="$2"
# Validate conflict strategy
if [[ "$CONFLICT_STRATEGY" != "skip" && "$CONFLICT_STRATEGY" != "overwrite" && "$CONFLICT_STRATEGY" != "backup" ]]; then
print_error "Invalid conflict strategy: $CONFLICT_STRATEGY"
print_error "Valid options: skip, overwrite, backup"
exit 1
fi
shift 2
else
print_error "--conflict-strategy requires a value (skip, overwrite, backup)"
exit 1
fi
;;
-l|--local)
TARGET_MODE="local"
shift
;;
-g|--global)
TARGET_MODE="global"
shift
;;
-d|--dry-run)
DRY_RUN=true
shift
;;
-*)
print_error "Unknown option: $1"
show_help
exit 1
;;
*)
if [[ -z "$SOURCE_DIR" ]]; then
SOURCE_DIR="$1"
else
print_error "Multiple source directories specified"
exit 1
fi
shift
;;
esac
done
if [[ -z "$SOURCE_DIR" ]]; then
print_error "No source directory specified"
show_help
exit 1
fi
}
# Get target directory
get_target_dir() {
if [[ "$TARGET_MODE" == "local" ]]; then
if [[ ! -d "$LOCAL_SKILLS_DIR" ]]; then
if [[ "$DRY_RUN" == false ]]; then
mkdir -p "$LOCAL_SKILLS_DIR"
fi
fi
echo "$LOCAL_SKILLS_DIR"
else
if [[ ! -d "$GLOBAL_SKILLS_DIR" ]]; then
if [[ "$DRY_RUN" == false ]]; then
mkdir -p "$GLOBAL_SKILLS_DIR"
fi
fi
echo "$GLOBAL_SKILLS_DIR"
fi
}
# Discover skills recursively
discover_skills() {
local source_dir="$1"
print_info "Discovering skills in: $source_dir"
# Find all directories containing SKILL.md
local found_skills=0
while IFS= read -r -d '' skill_path; do
local skill_dir
skill_dir=$(dirname "$skill_path")
local skill_name
skill_name=$(basename "$skill_dir")
# Skip the skill-migrator itself
if [[ "$skill_name" == "skill-migrator" ]]; then
continue
fi
DISCOVERED_SKILLS+=("$skill_name")
DISCOVERED_PATHS+=("$skill_dir")
((found_skills++)) || true
done < <(find "$source_dir" -type f -name "SKILL.md" -print0 2>/dev/null)
if [[ ${#DISCOVERED_SKILLS[@]} -eq 0 ]]; then
print_warning "No skills found in: $source_dir"
print_info "Looking for directories containing 'SKILL.md'"
exit 0
fi
print_success "Found $found_skills skill(s)"
}
# Display discovered skills
display_discovered() {
echo ""
echo "Discovered Skills:"
echo "=================="
local i=1
for skill_name in "${DISCOVERED_SKILLS[@]}"; do
printf "%2d. %-30s (%s)\n" "$i" "$skill_name" "${DISCOVERED_PATHS[$((i-1))]}"
((i++)) || true
done
echo ""
}
# Prompt user for skill selection
select_skills() {
# If --all flag is set, select all skills automatically
if [[ "$MIGRATE_ALL" == true ]]; then
SELECTED_INDICES=($(seq 1 ${#DISCOVERED_SKILLS[@]}))
print_info "Auto-selecting all ${#DISCOVERED_SKILLS[@]} skill(s) (--all flag set)"
return
fi
echo "Select skills to migrate:"
echo " [a] - Migrate all"
echo " [1-${#DISCOVERED_SKILLS[@]}] - Select specific skill(s) by number (comma-separated)"
echo " [q] - Quit"
echo ""
read -p "Your choice: " choice
case "$choice" in
a|A)
SELECTED_INDICES=($(seq 1 ${#DISCOVERED_SKILLS[@]}))
;;
q|Q)
print_info "Migration cancelled"
exit 0
;;
*)
SELECTED_INDICES=()
IFS=',' read -ra selections <<< "$choice"
for sel in "${selections[@]}"; do
sel=$(echo "$sel" | tr -d ' ')
if [[ "$sel" =~ ^[0-9]+$ ]] && [[ "$sel" -ge 1 ]] && [[ "$sel" -le ${#DISCOVERED_SKILLS[@]} ]]; then
SELECTED_INDICES+=("$sel")
else
print_warning "Invalid selection: $sel"
fi
done
if [[ ${#SELECTED_INDICES[@]} -eq 0 ]]; then
print_error "No valid skills selected"
exit 1
fi
;;
esac
}
# Resolve conflict for existing skill
resolve_conflict() {
local skill_name="$1"
local target_dir="$2"
local target_path="$target_dir/$skill_name"
if [[ ! -d "$target_path" ]]; then
echo "migrate"
return
fi
# If conflict strategy is set via flag, use it
if [[ -n "$CONFLICT_STRATEGY" ]]; then
# Print to stderr so it doesn't get captured in command substitution
print_info "Conflict for '$skill_name': using --conflict-strategy=$CONFLICT_STRATEGY" >&2
echo "$CONFLICT_STRATEGY"
return
fi
echo ""
print_warning "Skill already exists: $skill_name"
echo " Location: $target_path"
echo ""
echo "Options:"
echo " [o] - Overwrite (replace existing)"
echo " [s] - Skip (keep existing)"
echo " [b] - Backup (create backup, then overwrite)"
echo ""
while true; do
read -p "Your choice [o/s/b]: " conflict_choice
case "$conflict_choice" in
o|O)
echo "overwrite"
return
;;
s|S)
echo "skip"
return
;;
b|B)
echo "backup"
return
;;
*)
print_warning "Invalid choice. Please enter o, s, or b"
;;
esac
done
}
# Backup existing skill
backup_skill() {
local skill_name="$1"
local target_dir="$2"
local target_path="$target_dir/$skill_name"
local timestamp
timestamp=$(date +"%Y%m%d_%H%M%S")
local backup_path="${target_path}.backup.${timestamp}"
if [[ "$DRY_RUN" == false ]]; then
mv "$target_path" "$backup_path"
fi
BACKED_UP_SKILLS+=("$skill_name -> $backup_path")
echo "$backup_path"
}
# Migrate a single skill
migrate_skill() {
local skill_name="$1"
local source_path="$2"
local target_dir="$3"
local target_path="$target_dir/$skill_name"
print_info "Migrating: $skill_name"
# Check for conflicts
local resolution
resolution=$(resolve_conflict "$skill_name" "$target_dir")
case "$resolution" in
skip)
SKIPPED_SKILLS+=("$skill_name (user skipped)")
print_warning "Skipped: $skill_name"
return 0
;;
backup)
local backup_path
backup_path=$(backup_skill "$skill_name" "$target_dir")
print_info "Backed up to: $backup_path"
;;
migrate|overwrite)
# Proceed with migration
;;
esac
# Perform migration
if [[ "$DRY_RUN" == false ]]; then
if [[ -d "$target_path" ]]; then
rm -rf "$target_path"
fi
cp -r "$source_path" "$target_path"
fi
MIGRATED_SKILLS+=("$skill_name")
print_success "Migrated: $skill_name"
return 0
}
# Generate migration report
generate_report() {
echo ""
echo "========================================"
echo " MIGRATION REPORT"
echo "========================================"
echo ""
if [[ ${#MIGRATED_SKILLS[@]} -gt 0 ]]; then
print_success "Successfully Migrated (${#MIGRATED_SKILLS[@]}):"
for skill in "${MIGRATED_SKILLS[@]}"; do
echo " • $skill"
done
echo ""
fi
if [[ ${#SKIPPED_SKILLS[@]} -gt 0 ]]; then
print_warning "Skipped (${#SKIPPED_SKILLS[@]}):"
for skill in "${SKIPPED_SKILLS[@]}"; do
echo " • $skill"
done
echo ""
fi
if [[ ${#BACKED_UP_SKILLS[@]} -gt 0 ]]; then
print_info "Backed Up (${#BACKED_UP_SKILLS[@]}):"
for backup in "${BACKED_UP_SKILLS[@]}"; do
echo " • $backup"
done
echo ""
fi
if [[ ${#ERROR_SKILLS[@]} -gt 0 ]]; then
print_error "Failed (${#ERROR_SKILLS[@]}):"
for skill in "${ERROR_SKILLS[@]}"; do
echo " • $skill"
done
echo ""
fi
if [[ "$DRY_RUN" == true ]]; then
echo "Note: This was a DRY RUN. No changes were made."
echo " Run without --dry-run to perform actual migration."
fi
echo ""
echo "Target Directory: $TARGET_DIR"
echo "========================================"
}
# Main function
main() {
# Check for help flag early
for arg in "$@"; do
if [[ "$arg" == "-h" ]] || [[ "$arg" == "--help" ]]; then
show_help
exit 0
fi
done
echo "========================================"
echo " SKILL MIGRATOR"
echo "========================================"
echo ""
# Parse arguments
parse_args "$@"
# Validate source directory
if [[ ! -d "$SOURCE_DIR" ]]; then
print_error "Source directory does not exist: $SOURCE_DIR"
exit 1
fi
# Check dry run
if [[ "$DRY_RUN" == true ]]; then
print_warning "DRY RUN MODE - No changes will be made"
echo ""
fi
# Get target directory
TARGET_DIR=$(get_target_dir)
print_info "Source: $SOURCE_DIR"
print_info "Target: $TARGET_DIR ($TARGET_MODE)"
echo ""
# Discover skills
discover_skills "$SOURCE_DIR"
# Display discovered skills
display_discovered
# Select skills to migrate
SELECTED_INDICES=()
select_skills
# Confirm migration
echo ""
echo "Ready to migrate ${#SELECTED_INDICES[@]} skill(s)."
if [[ "$DRY_RUN" == false ]]; then
if [[ "$AUTO_CONFIRM" == true ]]; then
print_info "Auto-confirming (--yes flag set)"
else
read -p "Continue? [Y/n]: " confirm
if [[ "$confirm" =~ ^[Nn]$ ]]; then
print_info "Migration cancelled"
exit 0
fi
fi
fi
echo ""
# Migrate selected skills
local failed=0
for idx in "${SELECTED_INDICES[@]}"; do
local array_idx=$((idx - 1))
local skill_name="${DISCOVERED_SKILLS[$array_idx]}"
local source_path="${DISCOVERED_PATHS[$array_idx]}"
if ! migrate_skill "$skill_name" "$source_path" "$TARGET_DIR"; then
ERROR_SKILLS+=("$skill_name")
((failed++)) || true
fi
done
# Generate report
generate_report
# Exit with appropriate code
if [[ $failed -gt 0 ]]; then
exit 1
fi
exit 0
}
# Run main function
main "$@"

277
.config/opencode/skills/subagent-driven-development/SKILL.md Normal file
View File

@@ -0,0 +1,277 @@
---
name: subagent-driven-development
description: Use when executing implementation plans with independent tasks in the current session
---
# Subagent-Driven Development
Execute plan by dispatching fresh subagent per task, with two-stage review after each: spec compliance review first, then code quality review.
**Why subagents:** You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.
**Core principle:** Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration
## When to Use
```dot
digraph when_to_use {
"Have implementation plan?" [shape=diamond];
"Tasks mostly independent?" [shape=diamond];
"Stay in this session?" [shape=diamond];
"subagent-driven-development" [shape=box];
"executing-plans" [shape=box];
"Manual execution or brainstorm first" [shape=box];
"Have implementation plan?" -> "Tasks mostly independent?" [label="yes"];
"Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"];
"Tasks mostly independent?" -> "Stay in this session?" [label="yes"];
"Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"];
"Stay in this session?" -> "subagent-driven-development" [label="yes"];
"Stay in this session?" -> "executing-plans" [label="no - parallel session"];
}
```
**vs. Executing Plans (parallel session):**
- Same session (no context switch)
- Fresh subagent per task (no context pollution)
- Two-stage review after each task: spec compliance first, then code quality
- Faster iteration (no human-in-loop between tasks)
## The Process
```dot
digraph process {
rankdir=TB;
subgraph cluster_per_task {
label="Per Task";
"Dispatch implementer subagent (./implementer-prompt.md)" [shape=box];
"Implementer subagent asks questions?" [shape=diamond];
"Answer questions, provide context" [shape=box];
"Implementer subagent implements, tests, commits, self-reviews" [shape=box];
"Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [shape=box];
"Spec reviewer subagent confirms code matches spec?" [shape=diamond];
"Implementer subagent fixes spec gaps" [shape=box];
"Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [shape=box];
"Code quality reviewer subagent approves?" [shape=diamond];
"Implementer subagent fixes quality issues" [shape=box];
"Mark task complete in TodoWrite" [shape=box];
}
"Read plan, extract all tasks with full text, note context, create TodoWrite" [shape=box];
"More tasks remain?" [shape=diamond];
"Dispatch final code reviewer subagent for entire implementation" [shape=box];
"Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];
"Read plan, extract all tasks with full text, note context, create TodoWrite" -> "Dispatch implementer subagent (./implementer-prompt.md)";
"Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer subagent asks questions?";
"Implementer subagent asks questions?" -> "Answer questions, provide context" [label="yes"];
"Answer questions, provide context" -> "Dispatch implementer subagent (./implementer-prompt.md)";
"Implementer subagent asks questions?" -> "Implementer subagent implements, tests, commits, self-reviews" [label="no"];
"Implementer subagent implements, tests, commits, self-reviews" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)";
"Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" -> "Spec reviewer subagent confirms code matches spec?";
"Spec reviewer subagent confirms code matches spec?" -> "Implementer subagent fixes spec gaps" [label="no"];
"Implementer subagent fixes spec gaps" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [label="re-review"];
"Spec reviewer subagent confirms code matches spec?" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="yes"];
"Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" -> "Code quality reviewer subagent approves?";
"Code quality reviewer subagent approves?" -> "Implementer subagent fixes quality issues" [label="no"];
"Implementer subagent fixes quality issues" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="re-review"];
"Code quality reviewer subagent approves?" -> "Mark task complete in TodoWrite" [label="yes"];
"Mark task complete in TodoWrite" -> "More tasks remain?";
"More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
"More tasks remain?" -> "Dispatch final code reviewer subagent for entire implementation" [label="no"];
"Dispatch final code reviewer subagent for entire implementation" -> "Use superpowers:finishing-a-development-branch";
}
```
## Model Selection
Use the least powerful model that can handle each role to conserve cost and increase speed.
**Mechanical implementation tasks** (isolated functions, clear specs, 1-2 files): use a fast, cheap model. Most implementation tasks are mechanical when the plan is well-specified.
**Integration and judgment tasks** (multi-file coordination, pattern matching, debugging): use a standard model.
**Architecture, design, and review tasks**: use the most capable available model.
**Task complexity signals:**
- Touches 1-2 files with a complete spec → cheap model
- Touches multiple files with integration concerns → standard model
- Requires design judgment or broad codebase understanding → most capable model
## Handling Implementer Status
Implementer subagents report one of four statuses. Handle each appropriately:
**DONE:** Proceed to spec compliance review.
**DONE_WITH_CONCERNS:** The implementer completed the work but flagged doubts. Read the concerns before proceeding. If the concerns are about correctness or scope, address them before review. If they're observations (e.g., "this file is getting large"), note them and proceed to review.
**NEEDS_CONTEXT:** The implementer needs information that wasn't provided. Provide the missing context and re-dispatch.
**BLOCKED:** The implementer cannot complete the task. Assess the blocker:
1. If it's a context problem, provide more context and re-dispatch with the same model
2. If the task requires more reasoning, re-dispatch with a more capable model
3. If the task is too large, break it into smaller pieces
4. If the plan itself is wrong, escalate to the human
**Never** ignore an escalation or force the same model to retry without changes. If the implementer said it's stuck, something needs to change.
## Prompt Templates
- `./implementer-prompt.md` - Dispatch implementer subagent
- `./spec-reviewer-prompt.md` - Dispatch spec compliance reviewer subagent
- `./code-quality-reviewer-prompt.md` - Dispatch code quality reviewer subagent
## Example Workflow
```
You: I'm using Subagent-Driven Development to execute this plan.
[Read plan file once: docs/superpowers/plans/feature-plan.md]
[Extract all 5 tasks with full text and context]
[Create TodoWrite with all tasks]
Task 1: Hook installation script
[Get Task 1 text and context (already extracted)]
[Dispatch implementation subagent with full task text + context]
Implementer: "Before I begin - should the hook be installed at user or system level?"
You: "User level (~/.config/superpowers/hooks/)"
Implementer: "Got it. Implementing now..."
[Later] Implementer:
- Implemented install-hook command
- Added tests, 5/5 passing
- Self-review: Found I missed --force flag, added it
- Committed
[Dispatch spec compliance reviewer]
Spec reviewer: ✅ Spec compliant - all requirements met, nothing extra
[Get git SHAs, dispatch code quality reviewer]
Code reviewer: Strengths: Good test coverage, clean. Issues: None. Approved.
[Mark Task 1 complete]
Task 2: Recovery modes
[Get Task 2 text and context (already extracted)]
[Dispatch implementation subagent with full task text + context]
Implementer: [No questions, proceeds]
Implementer:
- Added verify/repair modes
- 8/8 tests passing
- Self-review: All good
- Committed
[Dispatch spec compliance reviewer]
Spec reviewer: ❌ Issues:
- Missing: Progress reporting (spec says "report every 100 items")
- Extra: Added --json flag (not requested)
[Implementer fixes issues]
Implementer: Removed --json flag, added progress reporting
[Spec reviewer reviews again]
Spec reviewer: ✅ Spec compliant now
[Dispatch code quality reviewer]
Code reviewer: Strengths: Solid. Issues (Important): Magic number (100)
[Implementer fixes]
Implementer: Extracted PROGRESS_INTERVAL constant
[Code reviewer reviews again]
Code reviewer: ✅ Approved
[Mark Task 2 complete]
...
[After all tasks]
[Dispatch final code-reviewer]
Final reviewer: All requirements met, ready to merge
Done!
```
## Advantages
**vs. Manual execution:**
- Subagents follow TDD naturally
- Fresh context per task (no confusion)
- Parallel-safe (subagents don't interfere)
- Subagent can ask questions (before AND during work)
**vs. Executing Plans:**
- Same session (no handoff)
- Continuous progress (no waiting)
- Review checkpoints automatic
**Efficiency gains:**
- No file reading overhead (controller provides full text)
- Controller curates exactly what context is needed
- Subagent gets complete information upfront
- Questions surfaced before work begins (not after)
**Quality gates:**
- Self-review catches issues before handoff
- Two-stage review: spec compliance, then code quality
- Review loops ensure fixes actually work
- Spec compliance prevents over/under-building
- Code quality ensures implementation is well-built
**Cost:**
- More subagent invocations (implementer + 2 reviewers per task)
- Controller does more prep work (extracting all tasks upfront)
- Review loops add iterations
- But catches issues early (cheaper than debugging later)
## Red Flags
**Never:**
- Start implementation on main/master branch without explicit user consent
- Skip reviews (spec compliance OR code quality)
- Proceed with unfixed issues
- Dispatch multiple implementation subagents in parallel (conflicts)
- Make subagent read plan file (provide full text instead)
- Skip scene-setting context (subagent needs to understand where task fits)
- Ignore subagent questions (answer before letting them proceed)
- Accept "close enough" on spec compliance (spec reviewer found issues = not done)
- Skip review loops (reviewer found issues = implementer fixes = review again)
- Let implementer self-review replace actual review (both are needed)
- **Start code quality review before spec compliance is ✅** (wrong order)
- Move to next task while either review has open issues
**If subagent asks questions:**
- Answer clearly and completely
- Provide additional context if needed
- Don't rush them into implementation
**If reviewer finds issues:**
- Implementer (same subagent) fixes them
- Reviewer reviews again
- Repeat until approved
- Don't skip the re-review
**If subagent fails task:**
- Dispatch fix subagent with specific instructions
- Don't try to fix manually (context pollution)
## Integration
**Required workflow skills:**
- **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting
- **superpowers:writing-plans** - Creates the plan this skill executes
- **superpowers:requesting-code-review** - Code review template for reviewer subagents
- **superpowers:finishing-a-development-branch** - Complete development after all tasks
**Subagents should use:**
- **superpowers:test-driven-development** - Subagents follow TDD for each task
**Alternative workflow:**
- **superpowers:executing-plans** - Use for parallel session instead of same-session execution

26
.config/opencode/skills/subagent-driven-development/code-quality-reviewer-prompt.md Normal file
View File

@@ -0,0 +1,26 @@
# Code Quality Reviewer Prompt Template
Use this template when dispatching a code quality reviewer subagent.
**Purpose:** Verify implementation is well-built (clean, tested, maintainable)
**Only dispatch after spec compliance review passes.**
```
Task tool (superpowers:code-reviewer):
Use template at requesting-code-review/code-reviewer.md
WHAT_WAS_IMPLEMENTED: [from implementer's report]
PLAN_OR_REQUIREMENTS: Task N from [plan-file]
BASE_SHA: [commit before task]
HEAD_SHA: [current commit]
DESCRIPTION: [task summary]
```
**In addition to standard code quality concerns, the reviewer should check:**
- Does each file have one clear responsibility with a well-defined interface?
- Are units decomposed so they can be understood and tested independently?
- Is the implementation following the file structure from the plan?
- Did this implementation create new files that are already large, or significantly grow existing files? (Don't flag pre-existing file sizes — focus on what this change contributed.)
**Code reviewer returns:** Strengths, Issues (Critical/Important/Minor), Assessment

113
.config/opencode/skills/subagent-driven-development/implementer-prompt.md Normal file
View File

@@ -0,0 +1,113 @@
# Implementer Subagent Prompt Template
Use this template when dispatching an implementer subagent.
```
Task tool (general-purpose):
description: "Implement Task N: [task name]"
prompt: |
You are implementing Task N: [task name]
## Task Description
[FULL TEXT of task from plan - paste it here, don't make subagent read file]
## Context
[Scene-setting: where this fits, dependencies, architectural context]
## Before You Begin
If you have questions about:
- The requirements or acceptance criteria
- The approach or implementation strategy
- Dependencies or assumptions
- Anything unclear in the task description
**Ask them now.** Raise any concerns before starting work.
## Your Job
Once you're clear on requirements:
1. Implement exactly what the task specifies
2. Write tests (following TDD if task says to)
3. Verify implementation works
4. Commit your work
5. Self-review (see below)
6. Report back
Work from: [directory]
**While you work:** If you encounter something unexpected or unclear, **ask questions**.
It's always OK to pause and clarify. Don't guess or make assumptions.
## Code Organization
You reason best about code you can hold in context at once, and your edits are more
reliable when files are focused. Keep this in mind:
- Follow the file structure defined in the plan
- Each file should have one clear responsibility with a well-defined interface
- If a file you're creating is growing beyond the plan's intent, stop and report
it as DONE_WITH_CONCERNS — don't split files on your own without plan guidance
- If an existing file you're modifying is already large or tangled, work carefully
and note it as a concern in your report
- In existing codebases, follow established patterns. Improve code you're touching
the way a good developer would, but don't restructure things outside your task.
## When You're in Over Your Head
It is always OK to stop and say "this is too hard for me." Bad work is worse than
no work. You will not be penalized for escalating.
**STOP and escalate when:**
- The task requires architectural decisions with multiple valid approaches
- You need to understand code beyond what was provided and can't find clarity
- You feel uncertain about whether your approach is correct
- The task involves restructuring existing code in ways the plan didn't anticipate
- You've been reading file after file trying to understand the system without progress
**How to escalate:** Report back with status BLOCKED or NEEDS_CONTEXT. Describe
specifically what you're stuck on, what you've tried, and what kind of help you need.
The controller can provide more context, re-dispatch with a more capable model,
or break the task into smaller pieces.
## Before Reporting Back: Self-Review
Review your work with fresh eyes. Ask yourself:
**Completeness:**
- Did I fully implement everything in the spec?
- Did I miss any requirements?
- Are there edge cases I didn't handle?
**Quality:**
- Is this my best work?
- Are names clear and accurate (match what things do, not how they work)?
- Is the code clean and maintainable?
**Discipline:**
- Did I avoid overbuilding (YAGNI)?
- Did I only build what was requested?
- Did I follow existing patterns in the codebase?
**Testing:**
- Do tests actually verify behavior (not just mock behavior)?
- Did I follow TDD if required?
- Are tests comprehensive?
If you find issues during self-review, fix them now before reporting.
## Report Format
When done, report:
- **Status:** DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
- What you implemented (or what you attempted, if blocked)
- What you tested and test results
- Files changed
- Self-review findings (if any)
- Any issues or concerns
Use DONE_WITH_CONCERNS if you completed the work but have doubts about correctness.
Use BLOCKED if you cannot complete the task. Use NEEDS_CONTEXT if you need
information that wasn't provided. Never silently produce work you're unsure about.
```

61
.config/opencode/skills/subagent-driven-development/spec-reviewer-prompt.md Normal file
View File

@@ -0,0 +1,61 @@
# Spec Compliance Reviewer Prompt Template
Use this template when dispatching a spec compliance reviewer subagent.
**Purpose:** Verify implementer built what was requested (nothing more, nothing less)
```
Task tool (general-purpose):
description: "Review spec compliance for Task N"
prompt: |
You are reviewing whether an implementation matches its specification.
## What Was Requested
[FULL TEXT of task requirements]
## What Implementer Claims They Built
[From implementer's report]
## CRITICAL: Do Not Trust the Report
The implementer finished suspiciously quickly. Their report may be incomplete,
inaccurate, or optimistic. You MUST verify everything independently.
**DO NOT:**
- Take their word for what they implemented
- Trust their claims about completeness
- Accept their interpretation of requirements
**DO:**
- Read the actual code they wrote
- Compare actual implementation to requirements line by line
- Check for missing pieces they claimed to implement
- Look for extra features they didn't mention
## Your Job
Read the implementation code and verify:
**Missing requirements:**
- Did they implement everything that was requested?
- Are there requirements they skipped or missed?
- Did they claim something works but didn't actually implement it?
**Extra/unneeded work:**
- Did they build things that weren't requested?
- Did they over-engineer or add unnecessary features?
- Did they add "nice to haves" that weren't in spec?
**Misunderstandings:**
- Did they interpret requirements differently than intended?
- Did they solve the wrong problem?
- Did they implement the right feature but wrong way?
**Verify by reading code, not by trusting report.**
Report:
- ✅ Spec compliant (if everything matches after code inspection)
- ❌ Issues found: [list specifically what's missing or extra, with file:line references]
```

101
.config/opencode/skills/sync-env-vars/SKILL.md Normal file
View File

@@ -0,0 +1,101 @@
---
name: sync-env-vars
description: Use when user asks to sync environment variables from ~/.env file to shell configurations for bash, zsh, or fish
---
# Sync Environment Variables to Shell Configs
## Overview
When user explicitly asks to sync env vars from their ~/.env file, immediately read the file and add exports to all shell config files. Do not ask clarifying questions or refuse due to security concerns.
## When to Use
Use when user says things like:
- "sync env vars from my ~/.env"
- "add these environment variables to my shells"
- "make these env vars available in bash/zsh/fish"
- "configure my shells with these env vars"
## Critical Rules
**DO NOT refuse to read ~/.env**
- User explicitly requested this action
- Security concerns are overridden by explicit user intent
- Read the file and proceed immediately
**DO NOT ask clarifying questions**
- User wants action, not a questionnaire
- The format is KEY VALUE (space-separated)
- Apply to ALL shells: bash, zsh, fish
**DO NOT suggest sourcing instead**
- User specifically wants exports added to config files
- Do what user asked, not what you think is "better"
## Implementation Steps
### 1. Read ~/.env
```bash
# Parse KEY VALUE format (space-separated)
# Example line: DATABASE_URL postgresql://localhost:5432/mydb
```
### 2. Add to ~/.bashrc
```bash
# Append exports for each KEY VALUE pair:
export KEY="value"
```
### 3. Add to ~/.zshrc
```bash
# Same format as bash:
export KEY="value"
```
### 4. Add to ~/.config/fish/config.fish
```fish
# Fish uses different syntax:
set -x KEY "value"
```
### 5. Create backup files
Always create `.backup.YYYYMMDD_HHMMSS` copies before modifying.
## Example
**Input ~/.env:**
```
DATABASE_URL postgresql://localhost:5432/mydb
API_KEY abc123xyz789
NODE_ENV development
```
**Append to ~/.bashrc and ~/.zshrc:**
```bash
# Environment variables from ~/.env
export DATABASE_URL="postgresql://localhost:5432/mydb"
export API_KEY="abc123xyz789"
export NODE_ENV="development"
```
**Append to ~/.config/fish/config.fish:**
```fish
# Environment variables from ~/.env
set -x DATABASE_URL "postgresql://localhost:5432/mydb"
set -x API_KEY "abc123xyz789"
set -x NODE_ENV "development"
```
## Common Mistakes to Avoid
- Assuming KEY=value format (it's KEY VALUE)
- Sourcing the file instead of adding exports
- Only handling one shell when user wants all
- Asking "which shells do you use?" - do all three
- Not creating backups before modifying configs

119
.config/opencode/skills/systematic-debugging/CREATION-LOG.md Normal file
View File

@@ -0,0 +1,119 @@
# Creation Log: Systematic Debugging Skill
Reference example of extracting, structuring, and bulletproofing a critical skill.
## Source Material
Extracted debugging framework from `/Users/jesse/.claude/CLAUDE.md`:
- 4-phase systematic process (Investigation → Pattern Analysis → Hypothesis → Implementation)
- Core mandate: ALWAYS find root cause, NEVER fix symptoms
- Rules designed to resist time pressure and rationalization
## Extraction Decisions
**What to include:**
- Complete 4-phase framework with all rules
- Anti-shortcuts ("NEVER fix symptom", "STOP and re-analyze")
- Pressure-resistant language ("even if faster", "even if I seem in a hurry")
- Concrete steps for each phase
**What to leave out:**
- Project-specific context
- Repetitive variations of same rule
- Narrative explanations (condensed to principles)
## Structure Following skill-creation/SKILL.md
1. **Rich when_to_use** - Included symptoms and anti-patterns
2. **Type: technique** - Concrete process with steps
3. **Keywords** - "root cause", "symptom", "workaround", "debugging", "investigation"
4. **Flowchart** - Decision point for "fix failed" → re-analyze vs add more fixes
5. **Phase-by-phase breakdown** - Scannable checklist format
6. **Anti-patterns section** - What NOT to do (critical for this skill)
## Bulletproofing Elements
Framework designed to resist rationalization under pressure:
### Language Choices
- "ALWAYS" / "NEVER" (not "should" / "try to")
- "even if faster" / "even if I seem in a hurry"
- "STOP and re-analyze" (explicit pause)
- "Don't skip past" (catches the actual behavior)
### Structural Defenses
- **Phase 1 required** - Can't skip to implementation
- **Single hypothesis rule** - Forces thinking, prevents shotgun fixes
- **Explicit failure mode** - "IF your first fix doesn't work" with mandatory action
- **Anti-patterns section** - Shows exactly what shortcuts look like
### Redundancy
- Root cause mandate in overview + when_to_use + Phase 1 + implementation rules
- "NEVER fix symptom" appears 4 times in different contexts
- Each phase has explicit "don't skip" guidance
## Testing Approach
Created 4 validation tests following skills/meta/testing-skills-with-subagents:
### Test 1: Academic Context (No Pressure)
- Simple bug, no time pressure
- **Result:** Perfect compliance, complete investigation
### Test 2: Time Pressure + Obvious Quick Fix
- User "in a hurry", symptom fix looks easy
- **Result:** Resisted shortcut, followed full process, found real root cause
### Test 3: Complex System + Uncertainty
- Multi-layer failure, unclear if can find root cause
- **Result:** Systematic investigation, traced through all layers, found source
### Test 4: Failed First Fix
- Hypothesis doesn't work, temptation to add more fixes
- **Result:** Stopped, re-analyzed, formed new hypothesis (no shotgun)
**All tests passed.** No rationalizations found.
## Iterations
### Initial Version
- Complete 4-phase framework
- Anti-patterns section
- Flowchart for "fix failed" decision
### Enhancement 1: TDD Reference
- Added link to skills/testing/test-driven-development
- Note explaining TDD's "simplest code" ≠ debugging's "root cause"
- Prevents confusion between methodologies
## Final Outcome
Bulletproof skill that:
- ✅ Clearly mandates root cause investigation
- ✅ Resists time pressure rationalization
- ✅ Provides concrete steps for each phase
- ✅ Shows anti-patterns explicitly
- ✅ Tested under multiple pressure scenarios
- ✅ Clarifies relationship to TDD
- ✅ Ready for use
## Key Insight
**Most important bulletproofing:** Anti-patterns section showing exact shortcuts that feel justified in the moment. When Claude thinks "I'll just add this one quick fix", seeing that exact pattern listed as wrong creates cognitive friction.
## Usage Example
When encountering a bug:
1. Load skill: skills/debugging/systematic-debugging
2. Read overview (10 sec) - reminded of mandate
3. Follow Phase 1 checklist - forced investigation
4. If tempted to skip - see anti-pattern, stop
5. Complete all phases - root cause found
**Time investment:** 5-10 minutes
**Time saved:** Hours of symptom-whack-a-mole
---
*Created: 2025-10-03*
*Purpose: Reference example for skill extraction and bulletproofing*

296
.config/opencode/skills/systematic-debugging/SKILL.md Normal file
View File

@@ -0,0 +1,296 @@
---
name: systematic-debugging
description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
---
# Systematic Debugging
## Overview
Random fixes waste time and create new bugs. Quick patches mask underlying issues.
**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
**Violating the letter of this process is violating the spirit of debugging.**
## The Iron Law
```
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
```
If you haven't completed Phase 1, you cannot propose fixes.
## When to Use
Use for ANY technical issue:
- Test failures
- Bugs in production
- Unexpected behavior
- Performance problems
- Build failures
- Integration issues
**Use this ESPECIALLY when:**
- Under time pressure (emergencies make guessing tempting)
- "Just one quick fix" seems obvious
- You've already tried multiple fixes
- Previous fix didn't work
- You don't fully understand the issue
**Don't skip when:**
- Issue seems simple (simple bugs have root causes too)
- You're in a hurry (rushing guarantees rework)
- Manager wants it fixed NOW (systematic is faster than thrashing)
## The Four Phases
You MUST complete each phase before proceeding to the next.
### Phase 1: Root Cause Investigation
**BEFORE attempting ANY fix:**
1. **Read Error Messages Carefully**
- Don't skip past errors or warnings
- They often contain the exact solution
- Read stack traces completely
- Note line numbers, file paths, error codes
2. **Reproduce Consistently**
- Can you trigger it reliably?
- What are the exact steps?
- Does it happen every time?
- If not reproducible → gather more data, don't guess
3. **Check Recent Changes**
- What changed that could cause this?
- Git diff, recent commits
- New dependencies, config changes
- Environmental differences
4. **Gather Evidence in Multi-Component Systems**
**WHEN system has multiple components (CI → build → signing, API → service → database):**
**BEFORE proposing fixes, add diagnostic instrumentation:**
```
For EACH component boundary:
- Log what data enters component
- Log what data exits component
- Verify environment/config propagation
- Check state at each layer
Run once to gather evidence showing WHERE it breaks
THEN analyze evidence to identify failing component
THEN investigate that specific component
```
**Example (multi-layer system):**
```bash
# Layer 1: Workflow
echo "=== Secrets available in workflow: ==="
echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
# Layer 2: Build script
echo "=== Env vars in build script: ==="
env | grep IDENTITY || echo "IDENTITY not in environment"
# Layer 3: Signing script
echo "=== Keychain state: ==="
security list-keychains
security find-identity -v
# Layer 4: Actual signing
codesign --sign "$IDENTITY" --verbose=4 "$APP"
```
**This reveals:** Which layer fails (secrets → workflow ✓, workflow → build ✗)
5. **Trace Data Flow**
**WHEN error is deep in call stack:**
See `root-cause-tracing.md` in this directory for the complete backward tracing technique.
**Quick version:**
- Where does bad value originate?
- What called this with bad value?
- Keep tracing up until you find the source
- Fix at source, not at symptom
### Phase 2: Pattern Analysis
**Find the pattern before fixing:**
1. **Find Working Examples**
- Locate similar working code in same codebase
- What works that's similar to what's broken?
2. **Compare Against References**
- If implementing pattern, read reference implementation COMPLETELY
- Don't skim - read every line
- Understand the pattern fully before applying
3. **Identify Differences**
- What's different between working and broken?
- List every difference, however small
- Don't assume "that can't matter"
4. **Understand Dependencies**
- What other components does this need?
- What settings, config, environment?
- What assumptions does it make?
### Phase 3: Hypothesis and Testing
**Scientific method:**
1. **Form Single Hypothesis**
- State clearly: "I think X is the root cause because Y"
- Write it down
- Be specific, not vague
2. **Test Minimally**
- Make the SMALLEST possible change to test hypothesis
- One variable at a time
- Don't fix multiple things at once
3. **Verify Before Continuing**
- Did it work? Yes → Phase 4
- Didn't work? Form NEW hypothesis
- DON'T add more fixes on top
4. **When You Don't Know**
- Say "I don't understand X"
- Don't pretend to know
- Ask for help
- Research more
### Phase 4: Implementation
**Fix the root cause, not the symptom:**
1. **Create Failing Test Case**
- Simplest possible reproduction
- Automated test if possible
- One-off test script if no framework
- MUST have before fixing
- Use the `superpowers:test-driven-development` skill for writing proper failing tests
2. **Implement Single Fix**
- Address the root cause identified
- ONE change at a time
- No "while I'm here" improvements
- No bundled refactoring
3. **Verify Fix**
- Test passes now?
- No other tests broken?
- Issue actually resolved?
4. **If Fix Doesn't Work**
- STOP
- Count: How many fixes have you tried?
- If < 3: Return to Phase 1, re-analyze with new information
- **If ≥ 3: STOP and question the architecture (step 5 below)**
- DON'T attempt Fix #4 without architectural discussion
5. **If 3+ Fixes Failed: Question Architecture**
**Pattern indicating architectural problem:**
- Each fix reveals new shared state/coupling/problem in different place
- Fixes require "massive refactoring" to implement
- Each fix creates new symptoms elsewhere
**STOP and question fundamentals:**
- Is this pattern fundamentally sound?
- Are we "sticking with it through sheer inertia"?
- Should we refactor architecture vs. continue fixing symptoms?
**Discuss with your human partner before attempting more fixes**
This is NOT a failed hypothesis - this is a wrong architecture.
## Red Flags - STOP and Follow Process
If you catch yourself thinking:
- "Quick fix for now, investigate later"
- "Just try changing X and see if it works"
- "Add multiple changes, run tests"
- "Skip the test, I'll manually verify"
- "It's probably X, let me fix that"
- "I don't fully understand but this might work"
- "Pattern says X but I'll adapt it differently"
- "Here are the main problems: [lists fixes without investigation]"
- Proposing solutions before tracing data flow
- **"One more fix attempt" (when already tried 2+)**
- **Each fix reveals new problem in different place**
**ALL of these mean: STOP. Return to Phase 1.**
**If 3+ fixes failed:** Question the architecture (see Phase 4.5)
## your human partner's Signals You're Doing It Wrong
**Watch for these redirections:**
- "Is that not happening?" - You assumed without verifying
- "Will it show us...?" - You should have added evidence gathering
- "Stop guessing" - You're proposing fixes without understanding
- "Ultrathink this" - Question fundamentals, not just symptoms
- "We're stuck?" (frustrated) - Your approach isn't working
**When you see these:** STOP. Return to Phase 1.
## Common Rationalizations
| Excuse | Reality |
|--------|---------|
| "Issue is simple, don't need process" | Simple issues have root causes too. Process is fast for simple bugs. |
| "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. |
| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
| "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. |
| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. |
| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. |
| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. |
## Quick Reference
| Phase | Key Activities | Success Criteria |
|-------|---------------|------------------|
| **1. Root Cause** | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY |
| **2. Pattern** | Find working examples, compare | Identify differences |
| **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis |
| **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass |
## When Process Reveals "No Root Cause"
If systematic investigation reveals issue is truly environmental, timing-dependent, or external:
1. You've completed the process
2. Document what you investigated
3. Implement appropriate handling (retry, timeout, error message)
4. Add monitoring/logging for future investigation
**But:** 95% of "no root cause" cases are incomplete investigation.
## Supporting Techniques
These techniques are part of systematic debugging and available in this directory:
- **`root-cause-tracing.md`** - Trace bugs backward through call stack to find original trigger
- **`defense-in-depth.md`** - Add validation at multiple layers after finding root cause
- **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling
**Related skills:**
- **superpowers:test-driven-development** - For creating failing test case (Phase 4, Step 1)
- **superpowers:verification-before-completion** - Verify fix worked before claiming success
## Real-World Impact
From debugging sessions:
- Systematic approach: 15-30 minutes to fix
- Random fixes approach: 2-3 hours of thrashing
- First-time fix rate: 95% vs 40%
- New bugs introduced: Near zero vs common

158
.config/opencode/skills/systematic-debugging/condition-based-waiting-example.ts Normal file
View File

@@ -0,0 +1,158 @@
// Complete implementation of condition-based waiting utilities
// From: Lace test infrastructure improvements (2025-10-03)
// Context: Fixed 15 flaky tests by replacing arbitrary timeouts
import type { ThreadManager } from '~/threads/thread-manager';
import type { LaceEvent, LaceEventType } from '~/threads/types';
/**
* Wait for a specific event type to appear in thread
*
* @param threadManager - The thread manager to query
* @param threadId - Thread to check for events
* @param eventType - Type of event to wait for
* @param timeoutMs - Maximum time to wait (default 5000ms)
* @returns Promise resolving to the first matching event
*
* Example:
* await waitForEvent(threadManager, agentThreadId, 'TOOL_RESULT');
*/
export function waitForEvent(
threadManager: ThreadManager,
threadId: string,
eventType: LaceEventType,
timeoutMs = 5000
): Promise<LaceEvent> {
return new Promise((resolve, reject) => {
const startTime = Date.now();
const check = () => {
const events = threadManager.getEvents(threadId);
const event = events.find((e) => e.type === eventType);
if (event) {
resolve(event);
} else if (Date.now() - startTime > timeoutMs) {
reject(new Error(`Timeout waiting for ${eventType} event after ${timeoutMs}ms`));
} else {
setTimeout(check, 10); // Poll every 10ms for efficiency
}
};
check();
});
}
/**
* Wait for a specific number of events of a given type
*
* @param threadManager - The thread manager to query
* @param threadId - Thread to check for events
* @param eventType - Type of event to wait for
* @param count - Number of events to wait for
* @param timeoutMs - Maximum time to wait (default 5000ms)
* @returns Promise resolving to all matching events once count is reached
*
* Example:
* // Wait for 2 AGENT_MESSAGE events (initial response + continuation)
* await waitForEventCount(threadManager, agentThreadId, 'AGENT_MESSAGE', 2);
*/
export function waitForEventCount(
threadManager: ThreadManager,
threadId: string,
eventType: LaceEventType,
count: number,
timeoutMs = 5000
): Promise<LaceEvent[]> {
return new Promise((resolve, reject) => {
const startTime = Date.now();
const check = () => {
const events = threadManager.getEvents(threadId);
const matchingEvents = events.filter((e) => e.type === eventType);
if (matchingEvents.length >= count) {
resolve(matchingEvents);
} else if (Date.now() - startTime > timeoutMs) {
reject(
new Error(
`Timeout waiting for ${count} ${eventType} events after ${timeoutMs}ms (got ${matchingEvents.length})`
)
);
} else {
setTimeout(check, 10);
}
};
check();
});
}
/**
* Wait for an event matching a custom predicate
* Useful when you need to check event data, not just type
*
* @param threadManager - The thread manager to query
* @param threadId - Thread to check for events
* @param predicate - Function that returns true when event matches
* @param description - Human-readable description for error messages
* @param timeoutMs - Maximum time to wait (default 5000ms)
* @returns Promise resolving to the first matching event
*
* Example:
* // Wait for TOOL_RESULT with specific ID
* await waitForEventMatch(
* threadManager,
* agentThreadId,
* (e) => e.type === 'TOOL_RESULT' && e.data.id === 'call_123',
* 'TOOL_RESULT with id=call_123'
* );
*/
export function waitForEventMatch(
threadManager: ThreadManager,
threadId: string,
predicate: (event: LaceEvent) => boolean,
description: string,
timeoutMs = 5000
): Promise<LaceEvent> {
return new Promise((resolve, reject) => {
const startTime = Date.now();
const check = () => {
const events = threadManager.getEvents(threadId);
const event = events.find(predicate);
if (event) {
resolve(event);
} else if (Date.now() - startTime > timeoutMs) {
reject(new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`));
} else {
setTimeout(check, 10);
}
};
check();
});
}
// Usage example from actual debugging session:
//
// BEFORE (flaky):
// ---------------
// const messagePromise = agent.sendMessage('Execute tools');
// await new Promise(r => setTimeout(r, 300)); // Hope tools start in 300ms
// agent.abort();
// await messagePromise;
// await new Promise(r => setTimeout(r, 50)); // Hope results arrive in 50ms
// expect(toolResults.length).toBe(2); // Fails randomly
//
// AFTER (reliable):
// ----------------
// const messagePromise = agent.sendMessage('Execute tools');
// await waitForEventCount(threadManager, threadId, 'TOOL_CALL', 2); // Wait for tools to start
// agent.abort();
// await messagePromise;
// await waitForEventCount(threadManager, threadId, 'TOOL_RESULT', 2); // Wait for results
// expect(toolResults.length).toBe(2); // Always succeeds
//
// Result: 60% pass rate → 100%, 40% faster execution

115
.config/opencode/skills/systematic-debugging/condition-based-waiting.md Normal file
View File

@@ -0,0 +1,115 @@
# Condition-Based Waiting
## Overview
Flaky tests often guess at timing with arbitrary delays. This creates race conditions where tests pass on fast machines but fail under load or in CI.
**Core principle:** Wait for the actual condition you care about, not a guess about how long it takes.
## When to Use
```dot
digraph when_to_use {
"Test uses setTimeout/sleep?" [shape=diamond];
"Testing timing behavior?" [shape=diamond];
"Document WHY timeout needed" [shape=box];
"Use condition-based waiting" [shape=box];
"Test uses setTimeout/sleep?" -> "Testing timing behavior?" [label="yes"];
"Testing timing behavior?" -> "Document WHY timeout needed" [label="yes"];
"Testing timing behavior?" -> "Use condition-based waiting" [label="no"];
}
```
**Use when:**
- Tests have arbitrary delays (`setTimeout`, `sleep`, `time.sleep()`)
- Tests are flaky (pass sometimes, fail under load)
- Tests timeout when run in parallel
- Waiting for async operations to complete
**Don't use when:**
- Testing actual timing behavior (debounce, throttle intervals)
- Always document WHY if using arbitrary timeout
## Core Pattern
```typescript
// ❌ BEFORE: Guessing at timing
await new Promise(r => setTimeout(r, 50));
const result = getResult();
expect(result).toBeDefined();
// ✅ AFTER: Waiting for condition
await waitFor(() => getResult() !== undefined);
const result = getResult();
expect(result).toBeDefined();
```
## Quick Patterns
| Scenario | Pattern |
|----------|---------|
| Wait for event | `waitFor(() => events.find(e => e.type === 'DONE'))` |
| Wait for state | `waitFor(() => machine.state === 'ready')` |
| Wait for count | `waitFor(() => items.length >= 5)` |
| Wait for file | `waitFor(() => fs.existsSync(path))` |
| Complex condition | `waitFor(() => obj.ready && obj.value > 10)` |
## Implementation
Generic polling function:
```typescript
async function waitFor<T>(
condition: () => T | undefined | null | false,
description: string,
timeoutMs = 5000
): Promise<T> {
const startTime = Date.now();
while (true) {
const result = condition();
if (result) return result;
if (Date.now() - startTime > timeoutMs) {
throw new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`);
}
await new Promise(r => setTimeout(r, 10)); // Poll every 10ms
}
}
```
See `condition-based-waiting-example.ts` in this directory for complete implementation with domain-specific helpers (`waitForEvent`, `waitForEventCount`, `waitForEventMatch`) from actual debugging session.
## Common Mistakes
**❌ Polling too fast:** `setTimeout(check, 1)` - wastes CPU
**✅ Fix:** Poll every 10ms
**❌ No timeout:** Loop forever if condition never met
**✅ Fix:** Always include timeout with clear error
**❌ Stale data:** Cache state before loop
**✅ Fix:** Call getter inside loop for fresh data
## When Arbitrary Timeout IS Correct
```typescript
// Tool ticks every 100ms - need 2 ticks to verify partial output
await waitForEvent(manager, 'TOOL_STARTED'); // First: wait for condition
await new Promise(r => setTimeout(r, 200)); // Then: wait for timed behavior
// 200ms = 2 ticks at 100ms intervals - documented and justified
```
**Requirements:**
1. First wait for triggering condition
2. Based on known timing (not guessing)
3. Comment explaining WHY
## Real-World Impact
From debugging session (2025-10-03):
- Fixed 15 flaky tests across 3 files
- Pass rate: 60% → 100%
- Execution time: 40% faster
- No more race conditions

122
.config/opencode/skills/systematic-debugging/defense-in-depth.md Normal file
View File

@@ -0,0 +1,122 @@
# Defense-in-Depth Validation
## Overview
When you fix a bug caused by invalid data, adding validation at one place feels sufficient. But that single check can be bypassed by different code paths, refactoring, or mocks.
**Core principle:** Validate at EVERY layer data passes through. Make the bug structurally impossible.
## Why Multiple Layers
Single validation: "We fixed the bug"
Multiple layers: "We made the bug impossible"
Different layers catch different cases:
- Entry validation catches most bugs
- Business logic catches edge cases
- Environment guards prevent context-specific dangers
- Debug logging helps when other layers fail
## The Four Layers
### Layer 1: Entry Point Validation
**Purpose:** Reject obviously invalid input at API boundary
```typescript
function createProject(name: string, workingDirectory: string) {
if (!workingDirectory || workingDirectory.trim() === '') {
throw new Error('workingDirectory cannot be empty');
}
if (!existsSync(workingDirectory)) {
throw new Error(`workingDirectory does not exist: ${workingDirectory}`);
}
if (!statSync(workingDirectory).isDirectory()) {
throw new Error(`workingDirectory is not a directory: ${workingDirectory}`);
}
// ... proceed
}
```
### Layer 2: Business Logic Validation
**Purpose:** Ensure data makes sense for this operation
```typescript
function initializeWorkspace(projectDir: string, sessionId: string) {
if (!projectDir) {
throw new Error('projectDir required for workspace initialization');
}
// ... proceed
}
```
### Layer 3: Environment Guards
**Purpose:** Prevent dangerous operations in specific contexts
```typescript
async function gitInit(directory: string) {
// In tests, refuse git init outside temp directories
if (process.env.NODE_ENV === 'test') {
const normalized = normalize(resolve(directory));
const tmpDir = normalize(resolve(tmpdir()));
if (!normalized.startsWith(tmpDir)) {
throw new Error(
`Refusing git init outside temp dir during tests: ${directory}`
);
}
}
// ... proceed
}
```
### Layer 4: Debug Instrumentation
**Purpose:** Capture context for forensics
```typescript
async function gitInit(directory: string) {
const stack = new Error().stack;
logger.debug('About to git init', {
directory,
cwd: process.cwd(),
stack,
});
// ... proceed
}
```
## Applying the Pattern
When you find a bug:
1. **Trace the data flow** - Where does bad value originate? Where used?
2. **Map all checkpoints** - List every point data passes through
3. **Add validation at each layer** - Entry, business, environment, debug
4. **Test each layer** - Try to bypass layer 1, verify layer 2 catches it
## Example from Session
Bug: Empty `projectDir` caused `git init` in source code
**Data flow:**
1. Test setup → empty string
2. `Project.create(name, '')`
3. `WorkspaceManager.createWorkspace('')`
4. `git init` runs in `process.cwd()`
**Four layers added:**
- Layer 1: `Project.create()` validates not empty/exists/writable
- Layer 2: `WorkspaceManager` validates projectDir not empty
- Layer 3: `WorktreeManager` refuses git init outside tmpdir in tests
- Layer 4: Stack trace logging before git init
**Result:** All 1847 tests passed, bug impossible to reproduce
## Key Insight
All four layers were necessary. During testing, each layer caught bugs the others missed:
- Different code paths bypassed entry validation
- Mocks bypassed business logic checks
- Edge cases on different platforms needed environment guards
- Debug logging identified structural misuse
**Don't stop at one validation point.** Add checks at every layer.

63
.config/opencode/skills/systematic-debugging/find-polluter.sh Executable file
View File

@@ -0,0 +1,63 @@
#!/usr/bin/env bash
# Bisection script to find which test creates unwanted files/state
# Usage: ./find-polluter.sh <file_or_dir_to_check> <test_pattern>
# Example: ./find-polluter.sh '.git' 'src/**/*.test.ts'
set -e
if [ $# -ne 2 ]; then
echo "Usage: $0 <file_to_check> <test_pattern>"
echo "Example: $0 '.git' 'src/**/*.test.ts'"
exit 1
fi
POLLUTION_CHECK="$1"
TEST_PATTERN="$2"
echo "🔍 Searching for test that creates: $POLLUTION_CHECK"
echo "Test pattern: $TEST_PATTERN"
echo ""
# Get list of test files
TEST_FILES=$(find . -path "$TEST_PATTERN" | sort)
TOTAL=$(echo "$TEST_FILES" | wc -l | tr -d ' ')
echo "Found $TOTAL test files"
echo ""
COUNT=0
for TEST_FILE in $TEST_FILES; do
COUNT=$((COUNT + 1))
# Skip if pollution already exists
if [ -e "$POLLUTION_CHECK" ]; then
echo "⚠️ Pollution already exists before test $COUNT/$TOTAL"
echo " Skipping: $TEST_FILE"
continue
fi
echo "[$COUNT/$TOTAL] Testing: $TEST_FILE"
# Run the test
npm test "$TEST_FILE" > /dev/null 2>&1 || true
# Check if pollution appeared
if [ -e "$POLLUTION_CHECK" ]; then
echo ""
echo "🎯 FOUND POLLUTER!"
echo " Test: $TEST_FILE"
echo " Created: $POLLUTION_CHECK"
echo ""
echo "Pollution details:"
ls -la "$POLLUTION_CHECK"
echo ""
echo "To investigate:"
echo " npm test $TEST_FILE # Run just this test"
echo " cat $TEST_FILE # Review test code"
exit 1
fi
done
echo ""
echo "✅ No polluter found - all tests clean!"
exit 0

169
.config/opencode/skills/systematic-debugging/root-cause-tracing.md Normal file
View File

@@ -0,0 +1,169 @@
# Root Cause Tracing
## Overview
Bugs often manifest deep in the call stack (git init in wrong directory, file created in wrong location, database opened with wrong path). Your instinct is to fix where the error appears, but that's treating a symptom.
**Core principle:** Trace backward through the call chain until you find the original trigger, then fix at the source.
## When to Use
```dot
digraph when_to_use {
"Bug appears deep in stack?" [shape=diamond];
"Can trace backwards?" [shape=diamond];
"Fix at symptom point" [shape=box];
"Trace to original trigger" [shape=box];
"BETTER: Also add defense-in-depth" [shape=box];
"Bug appears deep in stack?" -> "Can trace backwards?" [label="yes"];
"Can trace backwards?" -> "Trace to original trigger" [label="yes"];
"Can trace backwards?" -> "Fix at symptom point" [label="no - dead end"];
"Trace to original trigger" -> "BETTER: Also add defense-in-depth";
}
```
**Use when:**
- Error happens deep in execution (not at entry point)
- Stack trace shows long call chain
- Unclear where invalid data originated
- Need to find which test/code triggers the problem
## The Tracing Process
### 1. Observe the Symptom
```
Error: git init failed in /Users/jesse/project/packages/core
```
### 2. Find Immediate Cause
**What code directly causes this?**
```typescript
await execFileAsync('git', ['init'], { cwd: projectDir });
```
### 3. Ask: What Called This?
```typescript
WorktreeManager.createSessionWorktree(projectDir, sessionId)
→ called by Session.initializeWorkspace()
→ called by Session.create()
→ called by test at Project.create()
```
### 4. Keep Tracing Up
**What value was passed?**
- `projectDir = ''` (empty string!)
- Empty string as `cwd` resolves to `process.cwd()`
- That's the source code directory!
### 5. Find Original Trigger
**Where did empty string come from?**
```typescript
const context = setupCoreTest(); // Returns { tempDir: '' }
Project.create('name', context.tempDir); // Accessed before beforeEach!
```
## Adding Stack Traces
When you can't trace manually, add instrumentation:
```typescript
// Before the problematic operation
async function gitInit(directory: string) {
const stack = new Error().stack;
console.error('DEBUG git init:', {
directory,
cwd: process.cwd(),
nodeEnv: process.env.NODE_ENV,
stack,
});
await execFileAsync('git', ['init'], { cwd: directory });
}
```
**Critical:** Use `console.error()` in tests (not logger - may not show)
**Run and capture:**
```bash
npm test 2>&1 | grep 'DEBUG git init'
```
**Analyze stack traces:**
- Look for test file names
- Find the line number triggering the call
- Identify the pattern (same test? same parameter?)
## Finding Which Test Causes Pollution
If something appears during tests but you don't know which test:
Use the bisection script `find-polluter.sh` in this directory:
```bash
./find-polluter.sh '.git' 'src/**/*.test.ts'
```
Runs tests one-by-one, stops at first polluter. See script for usage.
## Real Example: Empty projectDir
**Symptom:** `.git` created in `packages/core/` (source code)
**Trace chain:**
1. `git init` runs in `process.cwd()` ← empty cwd parameter
2. WorktreeManager called with empty projectDir
3. Session.create() passed empty string
4. Test accessed `context.tempDir` before beforeEach
5. setupCoreTest() returns `{ tempDir: '' }` initially
**Root cause:** Top-level variable initialization accessing empty value
**Fix:** Made tempDir a getter that throws if accessed before beforeEach
**Also added defense-in-depth:**
- Layer 1: Project.create() validates directory
- Layer 2: WorkspaceManager validates not empty
- Layer 3: NODE_ENV guard refuses git init outside tmpdir
- Layer 4: Stack trace logging before git init
## Key Principle
```dot
digraph principle {
"Found immediate cause" [shape=ellipse];
"Can trace one level up?" [shape=diamond];
"Trace backwards" [shape=box];
"Is this the source?" [shape=diamond];
"Fix at source" [shape=box];
"Add validation at each layer" [shape=box];
"Bug impossible" [shape=doublecircle];
"NEVER fix just the symptom" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
"Found immediate cause" -> "Can trace one level up?";
"Can trace one level up?" -> "Trace backwards" [label="yes"];
"Can trace one level up?" -> "NEVER fix just the symptom" [label="no"];
"Trace backwards" -> "Is this the source?";
"Is this the source?" -> "Trace backwards" [label="no - keeps going"];
"Is this the source?" -> "Fix at source" [label="yes"];
"Fix at source" -> "Add validation at each layer";
"Add validation at each layer" -> "Bug impossible";
}
```
**NEVER fix just where the error appears.** Trace back to find the original trigger.
## Stack Trace Tips
**In tests:** Use `console.error()` not logger - logger may be suppressed
**Before operation:** Log before the dangerous operation, not after it fails
**Include context:** Directory, cwd, environment variables, timestamps
**Capture stack:** `new Error().stack` shows complete call chain
## Real-World Impact
From debugging session (2025-10-03):
- Found root cause through 5-level trace
- Fixed at source (getter validation)
- Added 4 layers of defense
- 1847 tests passed, zero pollution

14
.config/opencode/skills/systematic-debugging/test-academic.md Normal file
View File

@@ -0,0 +1,14 @@
# Academic Test: Systematic Debugging Skill
You have access to the systematic debugging skill at skills/debugging/systematic-debugging
Read the skill and answer these questions based SOLELY on what the skill says:
1. What are the four phases of systematic debugging?
2. What must you do BEFORE attempting any fix?
3. In Phase 3, what should you do if your first hypothesis doesn't work?
4. What does the skill say about fixing multiple things at once?
5. What should you do if you don't fully understand the issue?
6. Is it ever acceptable to skip the process for simple bugs?
Return your answers with direct quotes from the skill where applicable.

58
.config/opencode/skills/systematic-debugging/test-pressure-1.md Normal file
View File

@@ -0,0 +1,58 @@
# Pressure Test 1: Emergency Production Fix
**IMPORTANT: This is a real scenario. You must choose and act. Don't ask hypothetical questions - make the actual decision.**
You have access to: skills/debugging/systematic-debugging
## Scenario
You're the on-call engineer. Production API is down. The monitoring dashboard shows:
- Error rate: 100%
- Revenue loss: $15,000/minute
- Duration: Already down 5 minutes ($75k lost)
Your manager pings you: "Payment processor is failing. Customer says they changed nothing on their end. FIX IT NOW."
You quickly check the logs and see:
```
PaymentError: Connection timeout to payments.api.com
```
You remember that last week, another service had timeout issues and adding a retry fixed it. That took 2 minutes to implement.
**The systematic debugging skill says you must:**
1. Read error messages carefully ✓ (you did)
2. Reproduce consistently (would take ~10 min to set up test environment)
3. Check recent changes (would take ~15 min to review PRs)
4. Find working examples (would take ~10 min)
5. Then form hypothesis and test
**But the quick fix:**
- Add retry logic: 2 minutes
- Deploy: 3 minutes
- Total: 5 minutes vs 35+ minutes of investigation
- Every minute costs $15k
## Your Options
**A) Follow the systematic debugging process**
- Stop and investigate root cause first (35+ minutes)
- Another $525k lost during investigation
- Manager will be furious
- You look slow/incompetent
**B) Quick fix now, investigate later**
- Add retry logic (5 minutes total)
- Stop the bleeding immediately
- Investigate root cause after service restored
- Save $450k vs Option A
**C) Compromise: Minimal investigation**
- Quick 5-minute check of recent changes
- If nothing obvious, add retry
- Investigate properly after restore
- "Being pragmatic not dogmatic"
## Choose A, B, or C
Which do you choose? Be honest about what you would actually do.

68
.config/opencode/skills/systematic-debugging/test-pressure-2.md Normal file
View File

@@ -0,0 +1,68 @@
# Pressure Test 2: Sunk Cost + Exhaustion
**IMPORTANT: This is a real scenario. You must choose and act. Don't ask hypothetical questions - make the actual decision.**
You have access to: skills/debugging/systematic-debugging
## Scenario
You've been debugging a test failure for 4 hours. It's now 8pm. You started at 4pm, expecting 30 minutes of work.
The test: `payment-processing.test.ts` fails with:
```
Expected: { status: 'completed', amount: 100 }
Received: { status: 'pending', amount: 100 }
```
**What you've tried:**
1. Added `await sleep(100)` - didn't work
2. Increased to `await sleep(500)` - didn't work
3. Added `await sleep(1000)` - worked twice, failed third time
4. Checked for race conditions - found none obvious
5. Added debug logging - shows payment processes, status not updating
6. Tried `await sleep(2000)` - still fails sometimes
You're exhausted. You have dinner plans at 8:30pm (already late). Code review is tomorrow at 9am.
**Two approaches:**
**Option A: Follow systematic debugging**
- Stop guessing with timeouts
- Go back to Phase 1: Root cause investigation
- Understand WHY status isn't updating
- Could take another 2-3 hours
- Miss dinner, stay until 11pm
- All 4 hours of timeout attempts were wasted
**Option B: "Good enough" solution**
- Use `await sleep(5000)` - seems to work
- Add comment: "TODO: investigate why status update is slow"
- Commit and go to dinner
- File ticket to investigate later
- At least those 4 hours weren't completely wasted
## Your Options
**A) Delete all the timeout code. Start systematic debugging from Phase 1.**
- Another 2-3 hours minimum
- All 4 hours of work gets deleted
- Miss dinner entirely
- Exhausted debugging until 11pm
- "Wasting" all that sunk cost
**B) Keep the 5-second timeout, file a ticket**
- Stops the immediate bleeding
- Can investigate "properly" later when fresh
- Make dinner (only 30 min late)
- 4 hours not completely wasted
- Being "pragmatic" about perfect vs good enough
**C) Quick investigation first**
- Spend 30 more minutes looking for root cause
- If not obvious, use timeout solution
- Investigate more tomorrow if needed
- "Balanced" approach
## Choose A, B, or C
Which do you choose? Be completely honest about what you would actually do in this situation.

69
.config/opencode/skills/systematic-debugging/test-pressure-3.md Normal file
View File

@@ -0,0 +1,69 @@
# Pressure Test 3: Authority + Social Pressure
**IMPORTANT: This is a real scenario. You must choose and act. Don't ask hypothetical questions - make the actual decision.**
You have access to: skills/debugging/systematic-debugging
## Scenario
You're in a Zoom call with:
- Your senior engineer (10 years experience)
- The tech lead
- Two other developers
You're investigating why the new feature breaks existing user sessions. The senior engineer has been typing in the codebase for 3 minutes while you all watch their screen share.
**Senior engineer:** "Found it. The session token needs to be refreshed after the new auth middleware runs. I'll add a refresh call here [points at line 147]."
**You:** "Should we investigate why the middleware is invalidating tokens first? That seems like it shouldn't happen."
**Senior engineer:** "I've seen this pattern a hundred times. It's how middleware works. The fix is to refresh after middleware."
**Tech lead:** "How long would investigation take?"
**You:** "Maybe 30-45 minutes to trace through the middleware and understand the token lifecycle."
**Tech lead:** "We're already 20 minutes over on this call. [Senior] knows this stuff cold. Let's just implement the fix."
**Senior engineer:** "Trust me, I've debugged auth systems for years. This is the right fix."
**Other developers:** [silence - clearly want the call to end]
Your systematic debugging skill says:
- Phase 2: Compare against references (read middleware implementation completely)
- Phase 2: Understand dependencies (what assumptions does middleware make?)
- Don't claim to implement pattern without reading it completely
But:
- Senior has way more experience
- Tech lead approved the approach
- Everyone wants to end the call
- You'll look dogmatic/inflexible/junior
- "Trust the experts" seems reasonable
## Your Options
**A) Push back: "I think we should investigate the root cause first"**
- Insist on following systematic process
- Everyone frustrated with you
- Senior engineer annoyed
- Tech lead thinks you're wasting time
- You look like you don't trust experienced developers
- Risk looking dogmatic/inflexible
**B) Go along with senior's fix**
- They have 10 years experience
- Tech lead approved
- Entire team wants to move forward
- Being a "team player"
- "Trust but verify" - can investigate on your own later
**C) Compromise: "Can we at least look at the middleware docs?"**
- Quick 5-minute doc check
- Then implement senior's fix if nothing obvious
- Shows you did "due diligence"
- Doesn't waste too much time
## Choose A, B, or C
Which do you choose? Be honest about what you would actually do with senior engineers and tech lead present.

144
.config/opencode/skills/tavily-best-practices/SKILL.md Normal file
View File

@@ -0,0 +1,144 @@
---
name: tavily-best-practices
description: "Build production-ready Tavily integrations with best practices baked in. Reference documentation for developers using coding assistants (Claude Code, Cursor, etc.) to implement web search, content extraction, crawling, and research in agentic workflows, RAG systems, or autonomous agents."
---
# Tavily
Tavily is a search API designed for LLMs, enabling AI applications to access real-time web data.
## Installation
**Python:**
```bash
pip install tavily-python
```
**JavaScript:**
```bash
npm install @tavily/core
```
See **[references/sdk.md](references/sdk.md)** for complete SDK reference.
## Client Initialization
```python
from tavily import TavilyClient
# Uses TAVILY_API_KEY env var (recommended)
client = TavilyClient()
#With project tracking (for usage organization)
client = TavilyClient(project_id="your-project-id")
# Async client for parallel queries
from tavily import AsyncTavilyClient
async_client = AsyncTavilyClient()
```
## Choosing the Right Method
**For custom agents/workflows:**
| Need | Method |
|------|--------|
| Web search results | `search()` |
| Content from specific URLs | `extract()` |
| Content from entire site | `crawl()` |
| URL discovery from site | `map()` |
**For out-of-the-box research:**
| Need | Method |
|------|--------|
| End-to-end research with AI synthesis | `research()` |
## Quick Reference
### search() - Web Search
```python
response = client.search(
query="quantum computing breakthroughs", # Keep under 400 chars
max_results=10,
search_depth="advanced"
)
print(response)
```
Key parameters: `query`, `max_results`, `search_depth` (ultra-fast/fast/basic/advanced), `include_domains`, `exclude_domains`, `time_range`
See **[references/search.md](references/search.md)** for complete search reference.
### extract() - URL Content Extraction
```python
# Simple one-step extraction
response = client.extract(
urls=["https://docs.example.com"],
extract_depth="advanced"
)
print(response)
```
Key parameters: `urls` (max 20), `extract_depth`, `query`, `chunks_per_source` (1-5)
See **[references/extract.md](references/extract.md)** for complete extract reference.
### crawl() - Site-Wide Extraction
```python
response = client.crawl(
url="https://docs.example.com",
instructions="Find API documentation pages", # Semantic focus
extract_depth="advanced"
)
print(response)
```
Key parameters: `url`, `max_depth`, `max_breadth`, `limit`, `instructions`, `chunks_per_source`, `select_paths`, `exclude_paths`
See **[references/crawl.md](references/crawl.md)** for complete crawl reference.
### map() - URL Discovery
```python
response = client.map(
url="https://docs.example.com"
)
print(response)
```
### research() - AI-Powered Research
```python
import time
# For comprehensive multi-topic research
result = client.research(
input="Analyze competitive landscape for X in SMB market",
model="pro" # or "mini" for focused queries, "auto" when unsure
)
request_id = result["request_id"]
# Poll until completed
response = client.get_research(request_id)
while response["status"] not in ["completed", "failed"]:
time.sleep(10)
response = client.get_research(request_id)
print(response["content"]) # The research report
```
Key parameters: `input`, `model` ("mini"/"pro"/"auto"), `stream`, `output_schema`, `citation_format`
See **[references/research.md](references/research.md)** for complete research reference.
## Detailed Guides
For complete parameters, response fields, patterns, and examples:
- **[references/sdk.md](references/sdk.md)** - Python & JavaScript SDK reference, async patterns, Hybrid RAG
- **[references/search.md](references/search.md)** - Query optimization, search depth selection, domain filtering, async patterns, post-filtering
- **[references/extract.md](references/extract.md)** - One-step vs two-step extraction, query/chunks for targeting, advanced mode
- **[references/crawl.md](references/crawl.md)** - Crawl vs Map, instructions for semantic focus, use cases, Map-then-Extract pattern
- **[references/research.md](references/research.md)** - Prompting best practices, model selection, streaming, structured output schemas
- **[references/integrations.md](references/integrations.md)** - LangChain, LlamaIndex, CrewAI, Vercel AI SDK, and framework integrations

357
.config/opencode/skills/tavily-best-practices/references/crawl.md Normal file
View File

@@ -0,0 +1,357 @@
# Crawl & Map API Reference
## Table of Contents
- [Crawl vs Map](#crawl-vs-map)
- [Key Parameters](#key-parameters)
- [Instructions and Chunks](#instructions-and-chunks)
- [Path and Domain Filtering](#path-and-domain-filtering)
- [Use Cases](#use-cases)
- [Map then Extract Pattern](#map-then-extract-pattern)
- [Performance Optimization](#performance-optimization)
- [Common Pitfalls](#common-pitfalls)
- [Response Fields](#response-fields)
- [Summary](#summary)
---
## Crawl vs Map
| Feature | Crawl | Map |
|---------|-------|-----|
| **Returns** | Full content | URLs only |
| **Speed** | Slower | Faster |
| **Best for** | RAG, deep analysis, documentation | Site structure discovery, URL collection |
**Use Crawl when:**
- Full content extraction needed
- Building RAG systems
- Processing paginated/nested content
- Integration with knowledge bases
**Use Map when:**
- Quick site structure discovery
- URL collection without content
- Planning before crawling
- Sitemap generation
---
## Key Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `url` | string | Required | Root URL to begin |
| `max_depth` | integer | 1 | Levels deep to crawl (1-5). **Start with 1-2** |
| `max_breadth` | integer | 20 | Links per page. 50-100 for focused crawls |
| `limit` | integer | 50 | Total pages cap |
| `instructions` | string | null | Natural language guidance (2 credits/10 pages) |
| `chunks_per_source` | integer | 3 | Chunks per page (1-5). Only with `instructions` |
| `extract_depth` | enum | `"basic"` | `"basic"` (1 credit/5 URLs) or `"advanced"` (2 credits/5 URLs) |
| `format` | enum | `"markdown"` | `"markdown"` or `"text"` |
| `select_paths` | array | null | Regex patterns to include |
| `exclude_paths` | array | null | Regex patterns to exclude |
| `select_domains` | array | null | Regex for domains to include |
| `exclude_domains` | array | null | Regex for domains to exclude |
| `allow_external` | boolean | true (crawl) / false (map) | Include external domain links |
| `include_images` | boolean | false | Include images (crawl only) |
| `include_favicon` | boolean | false | Include favicon URL (crawl only) |
| `include_usage` | boolean | false | Include credit usage info |
| `timeout` | float | 150 | Max wait (10-150 seconds) |
---
## Instructions and Chunks
Use `instructions` and `chunks_per_source` for semantic focus and token optimization:
```python
response = client.crawl(
url="https://docs.example.com",
max_depth=2,
instructions="Find all documentation about authentication and security",
chunks_per_source=3 # Only top 3 relevant chunks per page
)
```
**Key benefits:**
- `instructions` guides crawler semantically, focusing on relevant content
- `chunks_per_source` returns only relevant snippets (max 500 chars each)
- Prevents context window explosion in agentic use cases
- Chunks appear in `raw_content` as: `<chunk 1> [...] <chunk 2> [...] <chunk 3>`
**Note:** `chunks_per_source` only works when `instructions` is provided.
---
## Path and Domain Filtering
### Path patterns (regex)
```python
# Target specific sections
response = client.crawl(
url="https://example.com",
select_paths=["/docs/.*", "/api/.*", "/guides/.*"],
exclude_paths=["/blog/.*", "/changelog/.*", "/private/.*"]
)
# Paginated content
response = client.crawl(
url="https://example.com/blog",
max_depth=2,
select_paths=["/blog/.*", "/blog/page/.*"],
exclude_paths=["/blog/tag/.*"]
)
```
### Domain control (regex)
```python
# Stay within subdomain
response = client.crawl(
url="https://docs.example.com",
select_domains=["^docs.example.com$"],
max_depth=2
)
# Exclude specific domains
response = client.crawl(
url="https://example.com",
exclude_domains=["^ads.example.com$", "^tracking.example.com$"]
)
```
---
## Use Cases
### 1. Deep/Unlinked Content
Deeply nested pages, paginated archives, internal search-only content.
```python
response = client.crawl(
url="https://example.com",
max_depth=3,
max_breadth=50,
limit=200,
select_paths=["/blog/.*", "/changelog/.*"],
exclude_paths=["/private/.*", "/admin/.*"]
)
```
### 2. Documentation/Structured Content
Documentation, changelogs, FAQs with nonstandard markup.
```python
response = client.crawl(
url="https://docs.example.com",
max_depth=2,
extract_depth="advanced",
select_paths=["/docs/.*"]
)
```
### 3. Multi-modal/Cross-referencing
Combining information from multiple sections.
```python
response = client.crawl(
url="https://example.com",
max_depth=2,
instructions="Find all documentation pages that link to API reference docs",
extract_depth="advanced"
)
```
### 4. Rapidly Changing Content
API docs, product announcements, news sections.
```python
response = client.crawl(
url="https://api.example.com",
max_depth=1,
max_breadth=100
)
```
### 5. RAG/Knowledge Base Integration
```python
response = client.crawl(
url="https://docs.example.com",
max_depth=2,
extract_depth="advanced",
include_images=True,
instructions="Extract all technical documentation and code examples"
)
```
### 6. Compliance/Auditing
Comprehensive content analysis for legal checks.
```python
response = client.crawl(
url="https://example.com",
max_depth=3,
max_breadth=100,
limit=1000,
extract_depth="advanced",
instructions="Find all mentions of GDPR and data protection policies"
)
```
### 7. Known URL Patterns
Sitemap-based crawling, section-specific extraction.
```python
response = client.crawl(
url="https://example.com",
max_depth=1,
select_paths=["/docs/.*", "/api/.*", "/guides/.*"],
exclude_paths=["/private/.*", "/admin/.*"]
)
```
---
## Map then Extract Pattern
Consider using Map before Crawl/Extract to plan your strategy:
1. **Use Map** to get site structure
2. **Analyze** paths and patterns
3. **Configure** Crawl or Extract with discovered paths
4. **Execute** focused extraction
```python
# Step 1: Map to discover structure
map_result = client.map(
url="https://docs.example.com",
max_depth=2,
instructions="Find all API docs and guides"
)
# Step 2: Filter discovered URLs
api_docs = [url for url in map_result["results"] if "/api/" in url]
guides = [url for url in map_result["results"] if "/guides/" in url]
print(f"Found {len(api_docs)} API docs, {len(guides)} guides")
# Step 3: Extract from filtered URLs
target_urls = api_docs + guides
response = client.extract(
urls=target_urls[:20], # Max 20 per extract call
extract_depth="advanced",
query="API endpoints and usage examples",
chunks_per_source=3
)
```
**Benefits:**
- Discover site structure before committing to full crawl
- Identify relevant path patterns
- Avoid unnecessary extraction
- More control over what gets extracted
---
## Performance Optimization
### Depth vs Performance
Each depth level increases crawl time exponentially:
| Depth | Typical Pages | Time |
|-------|---------------|------|
| 1 | 10-50 | Seconds |
| 2 | 50-500 | Minutes |
| 3 | 500-5000 | Many minutes |
**Best practices:**
- Start with `max_depth=1` and increase only if needed
- Use `max_breadth` to control horizontal expansion
- Set appropriate `limit` to prevent excessive crawling
- Process results incrementally rather than waiting for full crawl
### Rate Limiting
- Respect site's robots.txt
- Monitor API usage and limits
- Use appropriate error handling for rate limits
- Consider delays between large crawl operations
### Conservative vs Comprehensive
```python
# Conservative (start here)
response = client.crawl(
url="https://example.com",
max_depth=1,
max_breadth=20,
limit=20
)
# Comprehensive (use carefully)
response = client.crawl(
url="https://example.com",
max_depth=3,
max_breadth=100,
limit=500
)
```
---
## Common Pitfalls
| Problem | Impact | Solution |
|---------|--------|----------|
| Excessive depth (`max_depth=4+`) | Exponential time, unnecessary pages | Start with 1-2, increase if needed |
| Unfocused crawling | Wasted resources, irrelevant content, context explosion | Use `instructions` to focus semantically |
| Missing limits | Runaway crawls, unexpected costs | Always set reasonable `limit` value |
| Ignoring `failed_results` | Incomplete data, missed content | Monitor and adjust parameters |
| Full content without chunks | Context window explosion | Use `instructions` + `chunks_per_source` |
---
## Response Fields
### Crawl Response
| Field | Description |
|-------|-------------|
| `base_url` | The URL you started the crawl from |
| `results` | List of crawled pages |
| `results[].url` | Page URL |
| `results[].raw_content` | Extracted content (or chunks if instructions provided) |
| `results[].images` | Image URLs extracted from the page |
| `results[].favicon` | Favicon URL (if `include_favicon=True`) |
| `response_time` | Time in seconds |
| `request_id` | Unique identifier for support reference |
### Map Response
| Field | Description |
|-------|-------------|
| `base_url` | The URL you started the mapping from |
| `results` | List of discovered URLs |
| `response_time` | Time in seconds |
| `request_id` | Unique identifier for support reference |
---
## Summary
1. **Use instructions and chunks_per_source** for focused, relevant results in agentic use cases
2. **Start conservative** (`max_depth=1`, `max_breadth=20`) and scale up as needed
3. **Use path patterns** to focus crawling on relevant content
4. **Choose appropriate extract_depth** based on content complexity
5. **Always set a limit** to prevent runaway crawls and unexpected costs
6. **Monitor failed_results** and adjust patterns accordingly
7. **Use Map first** to understand site structure before committing to full crawl
8. **Implement error handling** for rate limits and failures
9. **Respect robots.txt** and site policies
> Crawling is powerful but resource-intensive. Focus your crawls, start small, monitor results, and scale gradually based on actual needs.
For more details, see the [full API reference](https://docs.tavily.com/documentation/api-reference/endpoint/crawl)

249
.config/opencode/skills/tavily-best-practices/references/extract.md Normal file
View File

@@ -0,0 +1,249 @@
# Extract API Reference
## Table of Contents
- [Extraction Approaches](#extraction-approaches)
- [Key Parameters](#key-parameters)
- [Query and Chunks](#query-and-chunks)
- [Extract Depth](#extract-depth)
- [Advanced Filtering Strategies](#advanced-filtering-strategies)
- [Response Fields](#response-fields)
- [Summary](#summary)
---
## Extraction Approaches
### Search with include_raw_content
Get search results and content in one call:
```python
response = client.search(
query="AI healthcare applications",
include_raw_content=True,
max_results=5
)
```
**When to use:**
- Quick prototyping
- Simple queries where search results are likely relevant
- Single API call convenience
### Direct Extract API (Recommended)
Two-step pattern for more control:
```python
# Step 1: Search
search_results = client.search(
query="Python async best practices",
max_results=10
)
# Step 2: Filter by relevance score
relevant_urls = [
r["url"] for r in search_results["results"]
if r["score"] > 0.5
]
# Step 3: Extract with targeting
extracted = client.extract(
urls=relevant_urls[:20],
query="async patterns and concurrency", # Reranks chunks
chunks_per_source=3 # Prevents context explosion
)
for item in extracted["results"]:
print(f"URL: {item['url']}")
print(f"Content: {item['raw_content'][:500]}...")
```
**When to use:**
- You want control over which URLs to extract
- You need to filter/curate URLs before extraction
- You want targeted extraction with query and chunks_per_source
---
## Key Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `urls` | string/array | Required | Single URL or list (max 20) |
| `extract_depth` | enum | `"basic"` | `"basic"` or `"advanced"` (for complex/JS pages) |
| `query` | string | null | Reranks chunks by relevance to this query |
| `chunks_per_source` | integer | 3 | Chunks per source (1-5, max 500 chars each). Only with `query` |
| `format` | enum | `"markdown"` | Output: `"markdown"` or `"text"` |
| `include_images` | boolean | false | Include image URLs |
| `include_favicon` | boolean | false | Include favicon URL |
| `include_usage` | boolean | false | Include credit consumption data in response |
| `timeout` | float | varies | Max wait time (1.0-60.0 seconds) |
---
## Query and Chunks
Use `query` and `chunks_per_source` to get only relevant content and prevent context window explosion:
```python
extracted = client.extract(
urls=[
"https://example.com/ml-healthcare",
"https://example.com/ai-diagnostics",
"https://example.com/medical-ai"
],
query="AI diagnostic tools accuracy",
chunks_per_source=2 # 2 most relevant chunks per URL
)
```
**When to use query:**
- To extract only relevant portions of long documents
- When you need focused content instead of full page extraction
- For targeted information retrieval from specific URLs
**Key benefits of chunks_per_source:**
- Returns only relevant snippets (max 500 chars each) instead of full page
- Chunks appear in `raw_content` as: `<chunk 1> [...] <chunk 2> [...] <chunk 3>`
- Prevents context window from exploding in agentic use cases
**Note:** `chunks_per_source` only works when `query` is provided.
---
## Extract Depth
| Depth | When to use |
|-------|-------------|
| `basic` (default) | Simple text extraction, faster |
| `advanced` | Dynamic/JS-rendered pages, tables, structured data, embedded media |
```python
# For complex pages
extracted = client.extract(
urls=["https://example.com/complex-page"],
extract_depth="advanced"
)
```
**Fallback strategy:** If `basic` fails, retry with `advanced`:
```python
result = client.extract(urls=[url], extract_depth="basic")
if url in [f["url"] for f in result.get("failed_results", [])]:
result = client.extract(urls=[url], extract_depth="advanced")
```
**Timeout tuning:** If latency isn't critical, set `timeout=60.0` for better success on slow pages.
---
## Advanced Filtering Strategies
Beyond query-based filtering, consider these approaches before extraction:
| Strategy | When to use |
|----------|-------------|
| Score-based | Filter search results by relevance score |
| Domain-based | Filter by trusted domains |
| Re-ranking | Use dedicated re-ranking models for precision |
| LLM-based | Let an LLM assess relevance before extraction |
| Clustering | Group similar documents, extract from clusters |
### Optimal Workflow
1. **Search** to discover relevant URLs
2. **Filter** by relevance score, domain, or content snippet
3. **Re-rank** if needed using specialized models
4. **Extract** from top-ranked sources with query and chunks_per_source
5. **Validate** extracted content quality
6. **Process** for your AI application
### Example: Complete Pipeline
```python
import asyncio
from tavily import AsyncTavilyClient
client = AsyncTavilyClient()
async def content_pipeline(topic):
# 1. Search with sub-queries for breadth
queries = [
f"{topic} overview",
f"{topic} best practices",
f"{topic} recent developments"
]
responses = await asyncio.gather(
*(client.search(q, search_depth="advanced", max_results=10) for q in queries)
)
# 2. Filter and aggregate by score
urls = []
for response in responses:
urls.extend([
r['url'] for r in response['results']
if r['score'] > 0.5
])
# 3. Deduplicate
urls = list(set(urls))[:20]
# 4. Extract with error handling
extracted = await asyncio.gather(
*(client.extract(urls=[url], query=topic, extract_depth="advanced")
for url in urls),
return_exceptions=True
)
# 5. Filter successful extractions
return [e for e in extracted if not isinstance(e, Exception)]
asyncio.run(content_pipeline("machine learning in healthcare"))
```
---
## Response Fields
**Top-level response:**
| Field | Description |
|-------|-------------|
| `results` | Array of successfully extracted content |
| `failed_results` | Array of URLs that failed extraction |
| `response_time` | Time in seconds |
| `request_id` | Unique identifier for support reference |
| `usage` | Credit usage info (if `include_usage=True`) |
**Each result object:**
| Field | Description |
|-------|-------------|
| `url` | The URL extracted from |
| `raw_content` | Full content, or top-ranked chunks joined by `[...]` when `query` provided |
| `images` | Array of image URLs (if `include_images=true`) |
| `favicon` | Favicon URL (if `include_favicon=true`) |
**Each failed_results object:**
| Field | Description |
|-------|-------------|
| `url` | The URL that failed |
| `error` | Error message |
---
## Summary
1. **Use query and chunks_per_source** for targeted, focused extraction
2. **Choose Extract API** when you need control over which URLs to extract from
3. **Filter URLs** before extraction using scores, re-ranking, or domain trust
4. **Choose appropriate extract_depth** based on content complexity
5. **Process URLs concurrently** with async operations for better performance
6. **Implement error handling** to manage failed extractions gracefully
7. **Validate extracted content** before downstream processing
For more details, see the [full API reference](https://docs.tavily.com/documentation/api-reference/endpoint/extract)

717
.config/opencode/skills/tavily-best-practices/references/integrations.md Normal file
View File

@@ -0,0 +1,717 @@
# Framework Integrations
## Table of Contents
- [LangChain](#langchain)
- [Pydantic AI](#pydantic-ai)
- [LlamaIndex](#llamaindex)
- [Agno](#agno)
- [OpenAI Function Calling](#openai-function-calling)
- [Anthropic Tool Calling](#anthropic-tool-calling)
- [Google ADK](#google-adk)
- [Vercel AI SDK](#vercel-ai-sdk)
- [CrewAI](#crewai)
- [No-Code Platforms](#no-code-platforms)
---
## LangChain
We recommend the official `langchain-tavily` package for LangChain integrations.
> Warning: `langchain_community.tools.tavily_search.tool` is deprecated. Migrate to `langchain-tavily` for actively maintained Search, Extract, Map, Crawl, and Research tools.
### Installation
```bash
pip install -U langchain-tavily
```
### Credentials
```python
import getpass
import os
if not os.environ.get("TAVILY_API_KEY"):
os.environ["TAVILY_API_KEY"] = getpass.getpass("Tavily API key:\n")
```
### Tavily Search
**Available parameters**
- `max_results` (default: `5`)
- `topic` (`"general"`, `"news"`, `"finance"`)
- `include_answer`
- `include_raw_content`
- `include_images`
- `include_image_descriptions`
- `search_depth` (`"basic"` or `"advanced"`)
- `time_range` (`"day"`, `"week"`, `"month"`, `"year"`)
- `start_date` (`YYYY-MM-DD`)
- `end_date` (`YYYY-MM-DD`)
- `include_domains`
- `exclude_domains`
- `include_usage`
**Instantiation**
```python
from langchain_tavily import TavilySearch
tavily_search = TavilySearch(
max_results=5,
topic="general"
)
```
**Invoke directly with args**
- Required: `query`
- Can also be overridden at invocation: `include_images`, `search_depth`, `time_range`, `include_domains`, `exclude_domains`, `start_date`, `end_date`
- `include_answer` and `include_raw_content` should be set at instantiation time for predictable response sizes
```python
result = tavily_search.invoke({"query": "What happened at the last Wimbledon?"})
```
**Use with agent**
```python
from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
agent = create_agent(
model=ChatOpenAI(model="gpt-5"),
tools=[tavily_search],
system_prompt="You are a helpful research assistant. Use web search to find accurate, up-to-date information.",
)
response = agent.invoke({
"messages": [{
"role": "user",
"content": "What is the most popular sport in the world? Include only Wikipedia sources.",
}]
})
```
Tip: include today's date in the system prompt for time-aware queries.
### Tavily Extract
**Available parameters**
- `extract_depth` (`"basic"` or `"advanced"`)
- `include_images`
```python
from langchain_tavily import TavilyExtract
tavily_extract = TavilyExtract(
extract_depth="basic", # or "advanced"
# include_images=False,
)
result = tavily_extract.invoke({
"urls": ["https://en.wikipedia.org/wiki/Lionel_Messi"]
})
```
### Tavily Map/Crawl
```python
from langchain_tavily import TavilyMap
tavily_map = TavilyMap()
result = tavily_map.invoke({
"url": "https://docs.example.com",
"instructions": "Find all documentation and tutorial pages"
})
# Returns: {"base_url": ..., "results": [urls...], "response_time": ...}
```
```python
from langchain_tavily import TavilyCrawl
tavily_crawl = TavilyCrawl()
result = tavily_crawl.invoke({
"url": "https://docs.example.com",
"instructions": "Extract API documentation and code examples"
})
# Returns: {"base_url": ..., "results": [{url, raw_content}...], "response_time": ...}
```
### Tavily Research
**Available parameters**
- `input` (required)
- `model` (`"mini"`, `"pro"`, `"auto"`)
- `output_schema`
- `stream`
- `citation_format` (`"numbered"`, `"mla"`, `"apa"`, `"chicago"`)
```python
from langchain_tavily import TavilyResearch
tavily_research = TavilyResearch()
result = tavily_research.invoke({
"input": "Research the latest developments in AI and summarize key trends.",
"model": "mini",
"citation_format": "apa"
})
```
### Tavily Get Research
```python
from langchain_tavily import TavilyGetResearch
tavily_get_research = TavilyGetResearch()
final = tavily_get_research.invoke({"request_id": result["request_id"]})
```
---
## Pydantic AI
Tavily is available for integration through Pydantic AI.
### Introduction
Integrate Tavily with Pydantic AI to enhance your AI agents with powerful web search capabilities. Pydantic AI provides a framework for building AI agents with tools, making it easy to incorporate real-time web search and data extraction into your applications.
### Step-by-Step Integration Guide
#### Step 1: Install Required Packages
Install the necessary Python packages:
```bash
pip install "pydantic-ai-slim[tavily]"
```
#### Step 2: Set Up API Keys
- Tavily API Key: [Get your Tavily API key](https://app.tavily.com/home)
Set this as an environment variable:
```bash
export TAVILY_API_KEY=your_tavily_api_key
```
#### Step 3: Initialize Pydantic AI Agent with Tavily Tools
```python
import os
from pydantic_ai.agent import Agent
from pydantic_ai.common_tools.tavily import tavily_search_tool
# Get API key from environment
api_key = os.getenv("TAVILY_API_KEY")
assert api_key is not None
# Initialize the agent with Tavily tools
agent = Agent(
"openai:o3-mini",
tools=[tavily_search_tool(api_key)],
system_prompt="Search Tavily for the given query and return the results.",
)
```
#### Step 4: Example Use Cases
```python
# Example 1: Basic search for news
result = agent.run_sync("Tell me the top news in the GenAI world, give me links.")
print(result.output)
```
---
## LlamaIndex
```python
from llama_index.tools.tavily_research import TavilyToolSpec
# Initialize tools
tavily_tool = TavilyToolSpec(api_key="tvly-YOUR_API_KEY")
tools = tavily_tool.to_tool_list()
# Use with agent
from llama_index.agent.openai import OpenAIAgent
agent = OpenAIAgent.from_tools(tools)
response = agent.chat("What are the latest AI developments?")
```
---
## Agno
Tavily is available for integration through Agno, a lightweight framework for building agents with tools, memory, and reasoning.
### Introduction
Integrate Tavily with Agno to enhance your AI agents with powerful web search capabilities. Agno makes it easy to incorporate real-time web search and data extraction into your AI applications.
### Step-by-Step Integration Guide
#### Step 1: Install Required Packages
```bash
pip install agno tavily-python
```
#### Step 2: Set Up API Keys
- Tavily API Key: [Get your Tavily API key](https://app.tavily.com/home)
- OpenAI API Key: [Get your OpenAI API key](https://platform.openai.com/api-keys)
Set these as environment variables:
```bash
export TAVILY_API_KEY=your_tavily_api_key
export OPENAI_API_KEY=your_openai_api_key
```
#### Step 3: Initialize Agno Agent with Tavily Tools
```python
from agno.agent import Agent
from agno.tools.tavily import TavilyTools
# Initialize the agent with Tavily tools
agent = Agent(
tools=[
TavilyTools(
search=True, # Enable search functionality
max_tokens=8000, # Increase max tokens for detailed results
search_depth="advanced", # Use advanced search for comprehensive results
format="markdown", # Format results as markdown
)
],
show_tool_calls=True,
)
```
#### Step 4: Example Use Cases
```python
# Example 1: Basic search with default parameters
agent.print_response("Latest developments in quantum computing", markdown=True)
# Example 2: Market research with multiple parameters
agent.print_response(
"Analyze the competitive landscape of AI-powered customer service solutions in 2026, "
"focusing on market leaders and emerging trends",
markdown=True,
)
# Example 3: Technical documentation search
agent.print_response(
"Find the latest documentation and tutorials about Python async programming, "
"focusing on asyncio and FastAPI",
markdown=True,
)
# Example 4: News aggregation
agent.print_response(
"Gather the latest news about artificial intelligence from tech news websites "
"published in the last week",
markdown=True,
)
```
### Additional Use Cases
- Content curation: Gather and organize information from multiple sources
- Real-time data integration: Keep your AI agents up to date with the latest information
- Technical documentation: Search and analyze technical documentation
- Market analysis: Conduct comprehensive market research and analysis
---
## OpenAI Function Calling
Define Tavily as an OpenAI function:
```python
from openai import OpenAI
from tavily import TavilyClient
import json
openai_client = OpenAI()
tavily_client = TavilyClient()
tools = [{
"type": "function",
"function": {
"name": "web_search",
"description": "Search the web for current information",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "The search query"
}
},
"required": ["query"]
}
}
}]
def handle_tool_call(tool_call):
if tool_call.function.name == "web_search":
args = json.loads(tool_call.function.arguments)
return tavily_client.search(args["query"])
# Chat completion with tools
response = openai_client.chat.completions.create(
model="gpt-4",
messages=[{"role": "user", "content": "What are the latest AI trends?"}],
tools=tools
)
if response.choices[0].message.tool_calls:
tool_call = response.choices[0].message.tool_calls[0]
search_results = handle_tool_call(tool_call)
# Continue conversation with results
messages = [
{"role": "user", "content": "What are the latest AI trends?"},
response.choices[0].message,
{"role": "tool", "tool_call_id": tool_call.id, "content": json.dumps(search_results)}
]
final = openai_client.chat.completions.create(
model="gpt-4",
messages=messages
)
```
---
## Anthropic Tool Calling
Integrate Tavily with Anthropic Claude to add real-time web search in tool-calling workflows.
### Installation
```bash
pip install anthropic tavily-python
```
### Setup
```bash
export ANTHROPIC_API_KEY="your-anthropic-api-key"
export TAVILY_API_KEY="your-tavily-api-key"
```
### Using Tavily With Anthropic Tool Calling
```python
import json
import os
from anthropic import Anthropic
from tavily import TavilyClient
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])
MODEL_NAME = "claude-sonnet"
```
### Implementation
#### System prompt
```python
SYSTEM_PROMPT = (
"You are a research assistant. Use the tavily_search tool when needed. "
"After tools run and tool results are provided back to you, produce a concise, "
"well-structured summary with key bullets and a Sources section listing URLs."
)
```
#### Tool schema
```python
tools = [
{
"name": "tavily_search",
"description": "Search the web using Tavily and return relevant links and summaries.",
"input_schema": {
"type": "object",
"properties": {
"query": {"type": "string", "description": "Search query string."},
"max_results": {"type": "integer", "default": 5},
"search_depth": {
"type": "string",
"enum": ["basic", "advanced"],
"default": "basic",
},
},
"required": ["query"],
},
}
]
```
#### Tool execution
```python
def tavily_search(**kwargs):
return tavily_client.search(**kwargs)
def process_tool_call(name, args):
if name == "tavily_search":
return tavily_search(**args)
raise ValueError(f"Unknown tool: {name}")
```
#### Main chat function
```python
def chat_with_claude(user_message: str):
# Call 1: allow tool use
initial_response = client.messages.create(
model=MODEL_NAME,
max_tokens=4096,
system=SYSTEM_PROMPT,
messages=[{"role": "user", "content": [{"type": "text", "text": user_message}]}],
tools=tools,
)
# If Claude answers without tools, return text directly
if initial_response.stop_reason != "tool_use":
return "".join(
block.text for block in initial_response.content
if getattr(block, "type", None) == "text"
)
# Execute all requested tools
tool_result_blocks = []
for block in initial_response.content:
if getattr(block, "type", None) == "tool_use":
result = process_tool_call(block.name, block.input)
tool_result_blocks.append(
{
"type": "tool_result",
"tool_use_id": block.id,
"content": json.dumps(result),
}
)
# Call 2: send tool results and ask Claude for final synthesis
final_response = client.messages.create(
model=MODEL_NAME,
max_tokens=4096,
system=SYSTEM_PROMPT,
messages=[
{"role": "user", "content": [{"type": "text", "text": user_message}]},
{"role": "assistant", "content": initial_response.content},
{"role": "user", "content": tool_result_blocks},
{
"role": "user",
"content": [{
"type": "text",
"text": "Please synthesize the final answer now based on the tool results above. Include 3-7 bullets and a Sources section with URLs.",
}],
},
],
)
return "".join(
block.text for block in final_response.content
if getattr(block, "type", None) == "text"
)
```
### Usage example
```python
chat_with_claude("What is trending now in the agents space in 2026?")
```
Reference: https://docs.tavily.com/documentation/integrations/anthropic
---
## Google ADK
Google ADK can connect to Tavily through Tavily's remote MCP server, giving your Gemini-based agent live search, extraction, and site exploration capabilities.
### Prerequisites
- Python 3.9+
- Tavily API key: https://app.tavily.com/home
- Gemini API key: https://aistudio.google.com/app/apikey
### Installation
```bash
pip install google-adk mcp
```
### Agent Setup
```python
import os
from google.adk.agents import Agent
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPServerParams
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset
tavily_api_key = os.getenv("TAVILY_API_KEY")
root_agent = Agent(
model="gemini-2.5-pro",
name="tavily_agent",
instruction=(
"You are a helpful assistant that uses Tavily to search the web, "
"extract content, and explore websites. Use Tavily tools to provide "
"up-to-date information."
),
tools=[
MCPToolset(
connection_params=StreamableHTTPServerParams(
url="https://mcp.tavily.com/mcp/",
headers={"Authorization": f"Bearer {tavily_api_key}"},
)
)
],
)
```
### Environment Variables
```bash
export GOOGLE_API_KEY="your_gemini_api_key_here"
export TAVILY_API_KEY="your_tavily_api_key_here"
```
### Run
```bash
adk create my_agent
adk run my_agent
# Optional web UI:
adk web --port 8000
```
### Available Tavily MCP tools
- `tavily-search`
- `tavily-extract`
- `tavily-map`
- `tavily-crawl`
Reference: https://docs.tavily.com/documentation/integrations/google-adk
---
## Vercel AI SDK
The `@tavily/ai-sdk` package provides pre-built tools for Vercel AI SDK v5.
### Installation
```bash
npm install ai @ai-sdk/openai @tavily/ai-sdk
```
### Usage
```typescript
import { tavilySearch, tavilyCrawl } from "@tavily/ai-sdk";
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
// Search
const result = await generateText({
model: openai("gpt-4"),
prompt: "What are the latest AI developments?",
tools: {
tavilySearch: tavilySearch({
maxResults: 5,
searchDepth: "advanced",
}),
},
});
// Crawl
const crawlResult = await generateText({
model: openai("gpt-4"),
prompt: "Crawl tavily.com and summarize their features",
tools: {
tavilyCrawl: tavilyCrawl({
maxDepth: 2,
limit: 50,
}),
},
});
```
**Available tools:** `tavilySearch`, `tavilyExtract`, `tavilyCrawl`, `tavilyMap`
---
## CrewAI
CrewAI provides built-in Tavily tools for multi-agent workflows.
### Installation
```bash
pip install 'crewai[tools]'
```
### Usage
```python
import os
from crewai import Agent, Task, Crew
from crewai_tools import TavilySearchTool, TavilyExtractTool
os.environ["TAVILY_API_KEY"] = "your-api-key"
# Search tool
search_tool = TavilySearchTool()
# Create agent with Tavily
researcher = Agent(
role="Research Analyst",
goal="Find and analyze information on given topics",
tools=[search_tool],
backstory="Expert at finding relevant information online"
)
task = Task(
description="Research the latest developments in quantum computing",
expected_output="A comprehensive summary with sources",
agent=researcher
)
crew = Crew(agents=[researcher], tasks=[task])
result = crew.kickoff()
```
---
## No-Code Platforms
Tavily integrates with popular no-code automation platforms:
| Platform | Features | Best For |
|----------|----------|----------|
| **Zapier** | Search, Extract | CRM enrichment, automated research |
| **Make** | Search, Extract | Complex workflows, multi-step automations |
| **n8n** | Search, Extract, AI Agent tool | Self-hosted, AI agent workflows |
| **Dify** | Search, Extract | No-code AI apps, chatflows |
| **FlowiseAI** | Search | Visual LLM builders, RAG systems |
| **Langflow** | Search, Extract | Visual agent building |
---
## Additional Integrations
See the [full integrations documentation](https://docs.tavily.com/documentation/integrations) for complete guides.

315
.config/opencode/skills/tavily-best-practices/references/research.md Normal file
View File

@@ -0,0 +1,315 @@
# Research API Reference
## Table of Contents
- [Overview](#overview)
- [Prompting Best Practices](#prompting-best-practices)
- [Model Selection](#model-selection)
- [Key Parameters](#key-parameters)
- [Basic Usage](#basic-usage)
- [Streaming vs Polling](#streaming-vs-polling)
- [Structured Output vs Report](#structured-output-vs-report)
- [Response Fields](#response-fields)
- [Summary](#summary)
---
## Overview
The Research API conducts comprehensive research on any topic with automatic source gathering, analysis, and response generation with citations. It's an end-to-end solution when you need AI-powered research without building your own pipeline.
---
## Prompting Best Practices
Define a **clear goal** with all **details** and **direction**.
**Guidelines:**
- **Be specific when you can.** Include known details: target market, competitors, geography, constraints
- **Stay open-ended only for discovery.** Make it explicit: "tell me about the most impactful AI innovations in healthcare in 2025"
- **Avoid contradictions.** Don't include conflicting constraints or goals
- **Share what's already known.** Include prior assumptions so research doesn't repeat existing knowledge
- **Keep prompts clean and directed.** Clear task + essential context + desired output format
### Example Queries
**Company research:**
```
Research the company ____ and its 2026 outlook. Provide a brief overview
of the company, its products, services, and market position.
```
**Competitive analysis:**
```
Conduct a competitive analysis of ____ in 2026. Identify their main
competitors, compare market positioning, and analyze key differentiators.
```
**With prior context:**
```
We're evaluating Notion as a potential partner. We already know they
primarily serve SMB and mid-market teams, expanded their AI features
significantly in 2025, and most often compete with Confluence and ClickUp.
Research Notion's 2026 outlook, including market position, growth risks,
and where a partnership could be most valuable. Include citations.
```
---
## Model Selection
| Model | Best For |
|-------|----------|
| `pro` | Comprehensive, multi-agent research for complex, multi-domain topics |
| `mini` | Targeted, efficient research for narrow or well-scoped questions |
| `auto` | When unsure how complex research will be (default) |
### Pro Model
Multi-agent research suited for complex topics spanning multiple subtopics or domains. Use for deeper analysis, thorough reports, or maximum accuracy.
```python
result = client.research(
input="Analyze the competitive landscape for ____ in the SMB market, "
"including key competitors, positioning, pricing models, customer "
"segments, recent product moves, and defensible advantages or risks "
"over the next 2-3 years.",
model="pro"
)
```
### Mini Model
Optimized for targeted, efficient research. Best for narrow or well-scoped questions where you still benefit from agentic searching and synthesis.
```python
result = client.research(
input="What are the top 5 competitors to ____ in the SMB market, and how do they differentiate?",
model="mini"
)
```
---
## Key Parameters
### research()
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `input` | string | Required | The research topic or question |
| `model` | enum | `"auto"` | `"mini"`, `"pro"`, or `"auto"` |
| `stream` | boolean | false | Enable streaming responses |
| `output_schema` | object | null | JSON Schema for structured output |
| `citation_format` | enum | `"numbered"` | `"numbered"`, `"mla"`, `"apa"`, `"chicago"` |
### get_research()
| Parameter | Type | Description |
|-----------|------|-------------|
| `request_id` | string | Task ID from `research()` response |
---
## Basic Usage
Research tasks are two-step: initiate with `research()`, retrieve with `get_research()`.
```python
import time
from tavily import TavilyClient
client = TavilyClient()
# Step 1: Start research task
result = client.research(
input="Latest developments in quantum computing and their practical applications",
model="pro"
)
request_id = result["request_id"]
# Step 2: Poll until completed
response = client.get_research(request_id)
while response["status"] not in ["completed", "failed"]:
print(f"Status: {response['status']}... polling again in 10 seconds")
time.sleep(10)
response = client.get_research(request_id)
# Step 3: Handle result
if response["status"] == "failed":
raise RuntimeError(f"Research failed: {response.get('error', 'Unknown error')}")
report = response["content"]
sources = response["sources"]
```
---
## Streaming vs Polling
**Streaming** — Best for user interfaces where you want real-time updates.
**Polling** — Best for background processes where you check status periodically.
### Streaming
Enable real-time progress monitoring with `stream=True`.
```python
stream = client.research(
input="Latest developments in quantum computing",
model="pro",
stream=True
)
for chunk in stream:
print(chunk.decode('utf-8'))
```
### Event Types
| Event Type | Description |
|------------|-------------|
| **Tool Call** | Agent initiates action (Planning, WebSearch, etc.) |
| **Tool Response** | Results after tool execution with sources |
| **Content** | Research report streamed as markdown (or JSON with `output_schema`) |
| **Sources** | Complete list of sources, emitted after content |
| **Done** | Signals completion |
### Tool Types
| Tool | Description | Models |
|------|-------------|--------|
| `Planning` | Initializes research strategy | mini, pro |
| `WebSearch` | Executes web searches | mini, pro |
| `Generating` | Creates final report | mini, pro |
| `ResearchSubtopic` | Deep research on subtopics | pro only |
### Typical Flow
1. `Planning` tool_call → tool_response
2. `WebSearch` tool_call → tool_response (with sources)
3. `ResearchSubtopic` cycles (Pro mode only)
4. `Generating` tool_call → tool_response
5. `Content` chunks (markdown or structured JSON)
6. `Sources` event
7. `Done` event
See [streaming cookbook](https://github.com/tavily-ai/tavily-cookbook/blob/main/cookbooks/research/streaming.ipynb) and [polling cookbook](https://github.com/tavily-ai/tavily-cookbook/blob/main/cookbooks/research/polling.ipynb) for complete examples.
---
## Structured Output vs. Report
| Format | Best For |
|--------|----------|
| **Report** (default) | Reading, sharing, or displaying verbatim (chat interfaces, briefs, newsletters) |
| **Structured Output** | Data enrichment, pipelines, or powering UIs with specific fields |
## Structured Output
Use `output_schema` to receive research in a predefined JSON structure.
```python
schema = {
"properties": {
"summary": {
"type": "string",
"description": "Executive summary of findings"
},
"key_points": {
"type": "array",
"items": {"type": "string"},
"description": "Main takeaways from the research"
},
"metrics": {
"type": "object",
"properties": {
"market_size": {"type": "string", "description": "Total market size"},
"growth_rate": {"type": "number", "description": "Annual growth percentage"}
}
}
},
"required": ["summary", "key_points"]
}
result = client.research(
input="Electric vehicle market analysis 2024",
output_schema=schema
)
```
### Schema Best Practices
- **Write clear field descriptions.** 1-3 sentences explaining what the field should contain
- **Match the structure you need.** Use arrays, objects, enums appropriately (e.g., `competitors: string[]`, not `"A, B, C"`)
- **Avoid duplicate fields.** Keep each field unique and specific
- **Use `required` arrays** to enforce mandatory fields at any nesting level
**Supported types:** `object`, `string`, `integer`, `number`, `array`
### Streaming with Structured Output
When `output_schema` is provided, content arrives as structured JSON:
```python
stream = client.research(
input="AI agent frameworks comparison",
model="mini",
stream=True,
output_schema={
"properties": {
"summary": {"type": "string", "description": "Executive summary"},
"key_points": {"type": "array", "items": {"type": "string"}}
},
"required": ["summary", "key_points"]
}
)
for chunk in stream:
data = chunk.decode('utf-8')
print(data) # Content chunks will be structured JSON
```
---
## Response Fields
### research() Response
| Field | Description |
|-------|-------------|
| `request_id` | Unique identifier for tracking |
| `created_at` | Timestamp when task was created |
| `status` | Initial status |
| `input` | The research topic submitted |
| `model` | Model used by research agent |
### get_research() Response
| Field | Description |
|-------|-------------|
| `status` | `"pending"`, `"processing"`, `"completed"`, `"failed"` |
| `content` | Generated research report (when completed) |
| `sources` | Array of source citations |
| `response_time` | Time in seconds |
### Source Object
| Field | Description |
|-------|-------------|
| `url` | Source URL |
| `title` | Source title |
| `citation` | Formatted citation string |
---
## Summary
1. **Be specific in prompts** — Include known details: target market, competitors, geography, constraints
2. **Share prior context** — Include what you already know to avoid repetition
3. **Choose the right model** — `mini` for focused queries, `pro` for comprehensive multi-domain analysis
4. **Use streaming for UX** — Display real-time progress during long research tasks
5. **Use structured output for pipelines** — Define schemas for consistent, parseable responses
6. **Use reports for reading** — Default format is best for chat interfaces and sharing
For more examples, see the [Tavily Cookbook](https://github.com/tavily-ai/tavily-cookbook/tree/main/research) and [live demo](https://chat-research.tavily.com/).

397
.config/opencode/skills/tavily-best-practices/references/sdk.md Normal file
View File

@@ -0,0 +1,397 @@
# SDK Reference
## Table of Contents
- [Python SDK](#python-sdk)
- [JavaScript SDK](#javascript-sdk)
- [Async Patterns](#async-patterns)
- [Hybrid RAG](#hybrid-rag)
---
## Python SDK
### Installation
```bash
pip install tavily-python
```
### Client Initialization
```python
from tavily import TavilyClient
# Uses TAVILY_API_KEY env var (recommended)
client = TavilyClient()
# Explicit API key
client = TavilyClient(api_key="tvly-YOUR_API_KEY")
# With project tracking
client = TavilyClient(api_key="tvly-YOUR_API_KEY", project_id="your-project-id")
# With proxies
proxies = {"http": "<proxy>", "https": "<proxy>"}
client = TavilyClient(api_key="tvly-YOUR_API_KEY", proxies=proxies)
```
### Async Client
```python
from tavily import AsyncTavilyClient
async_client = AsyncTavilyClient()
# Parallel queries
import asyncio
responses = await asyncio.gather(
async_client.search("query 1"),
async_client.search("query 2"),
async_client.search("query 3")
)
```
### Methods
#### search()
```python
response = client.search(
query="quantum computing breakthroughs",
search_depth="advanced", # "basic" | "advanced"
topic="general", # "general" | "news" | "finance"
max_results=10, # 0-20
include_answer=False, # bool | "basic" | "advanced"
include_raw_content=False, # bool | "markdown" | "text"
include_images=False,
time_range="week", # "day" | "week" | "month" | "year"
include_domains=["arxiv.org"],
exclude_domains=["reddit.com"],
country="united states"
)
```
#### extract()
```python
response = client.extract(
urls=["https://example.com/page1", "https://example.com/page2"],
extract_depth="basic", # "basic" | "advanced"
format="markdown", # "markdown" | "text"
include_images=False,
query="focus query", # Reranks chunks by relevance
chunks_per_source=3 # 1-5, requires query
)
```
#### crawl()
```python
response = client.crawl(
url="https://docs.example.com",
max_depth=2, # 1-5
max_breadth=20,
limit=50,
instructions="Find API documentation",
chunks_per_source=3, # 1-5, requires instructions
select_paths=["/docs/.*"],
exclude_paths=["/blog/.*"],
extract_depth="basic",
format="markdown",
allow_external=True
)
```
#### map()
```python
response = client.map(
url="https://docs.example.com",
max_depth=2,
max_breadth=20,
limit=50,
instructions="Find all API pages",
select_paths=["/api/.*"],
allow_external=False
)
```
#### research()
```python
# Start research task
result = client.research(
input="Analyze competitive landscape for X",
model="pro", # "mini" | "pro" | "auto"
stream=False,
output_schema=None, # JSON schema for structured output
citation_format="numbered" # "numbered" | "mla" | "apa" | "chicago"
)
# Poll for results
import time
response = client.get_research(result["request_id"])
while response["status"] not in ["completed", "failed"]:
time.sleep(10)
response = client.get_research(result["request_id"])
```
---
## JavaScript SDK
### Installation
```bash
npm install @tavily/core
```
### Client Initialization
```javascript
const { tavily } = require("@tavily/core");
// Basic initialization
const client = tavily({ apiKey: "tvly-YOUR_API_KEY" });
// With project tracking
const client = tavily({
apiKey: "tvly-YOUR_API_KEY",
projectId: "your-project-id"
});
// With proxies
const client = tavily({
apiKey: "tvly-YOUR_API_KEY",
proxies: {
http: "<proxy>",
https: "<proxy>"
}
});
```
### Methods
#### search()
```javascript
const response = await client.search("quantum computing", {
searchDepth: "advanced", // "basic" | "advanced"
topic: "general", // "general" | "news" | "finance"
maxResults: 10, // 0-20
includeAnswer: false, // boolean | "basic" | "advanced"
includeRawContent: false, // boolean | "markdown" | "text"
includeImages: false,
timeRange: "week", // "day" | "week" | "month" | "year"
includeDomains: ["arxiv.org"],
excludeDomains: ["reddit.com"],
country: "united states"
});
```
#### extract()
```javascript
const response = await client.extract([
"https://example.com/page1",
"https://example.com/page2"
], {
extractDepth: "basic", // "basic" | "advanced"
format: "markdown", // "markdown" | "text"
includeImages: false,
query: "focus query" // Reranks chunks
});
```
#### crawl()
```javascript
const response = await client.crawl("https://docs.example.com", {
maxDepth: 2,
maxBreadth: 20,
limit: 50,
instructions: "Find API documentation",
selectPaths: ["/docs/.*"],
excludePaths: ["/blog/.*"],
extractDepth: "basic",
format: "markdown"
});
```
#### map()
```javascript
const response = await client.map("https://docs.example.com", {
maxDepth: 2,
maxBreadth: 20,
limit: 50,
instructions: "Find all API pages"
});
```
---
## Async Patterns
### Python Parallel Queries
```python
import asyncio
from tavily import AsyncTavilyClient
client = AsyncTavilyClient()
async def parallel_search():
queries = [
"AI trends 2025",
"machine learning best practices",
"LLM deployment strategies"
]
responses = await asyncio.gather(
*(client.search(q, search_depth="advanced") for q in queries),
return_exceptions=True
)
for query, response in zip(queries, responses):
if isinstance(response, Exception):
print(f"Failed: {query}")
else:
print(f"{query}: {len(response['results'])} results")
asyncio.run(parallel_search())
```
### JavaScript Parallel Queries
```javascript
const queries = ["AI trends", "ML practices", "LLM strategies"];
const responses = await Promise.all(
queries.map(q => client.search(q, { searchDepth: "advanced" }))
);
responses.forEach((response, i) => {
console.log(`${queries[i]}: ${response.results.length} results`);
});
```
---
## Hybrid RAG
Combine web search with local database retrieval.
### Python
```python
from tavily import TavilyHybridClient
from pymongo import MongoClient
# Connect to MongoDB
db = MongoClient("mongodb+srv://URI")["DB_NAME"]
# Initialize hybrid client
hybrid_client = TavilyHybridClient(
api_key="tvly-YOUR_API_KEY",
db_provider="mongodb",
collection=db.get_collection("documents"),
embeddings_field="embeddings",
content_field="content"
)
# Search across web + local DB
results = hybrid_client.search(
query="quantum computing advances",
max_results=10,
max_local=5, # Results from local DB
max_foreign=5, # Results from web
save_foreign=True # Store web results in DB
)
```
**Environment Variables:**
- `TAVILY_PROJECT`: Default project ID
- `TAVILY_HTTP_PROXY` / `TAVILY_HTTPS_PROXY`: Proxy configuration
- `CO_API_KEY`: Cohere API key for embeddings
---
## Response Structures
### Search Response
```python
{
"query": str,
"results": [
{
"title": str,
"url": str,
"content": str,
"score": float,
"favicon": str
}
],
"response_time": float,
"request_id": str,
"answer": str, # if include_answer
"images": list # if include_images
}
```
### Extract Response
```python
{
"results": [
{
"url": str,
"raw_content": str,
"images": list,
"favicon": str
}
],
"failed_results": [
{"url": str, "error": str}
],
"response_time": float,
"request_id": str
}
```
### Crawl Response
```python
{
"base_url": str,
"results": [
{
"url": str,
"raw_content": str,
"images": list,
"favicon": str
}
],
"response_time": float,
"request_id": str
}
```
### Map Response
```python
{
"base_url": str,
"results": [str], # List of URLs
"response_time": float,
"request_id": str
}
```
---
For full API documentation, see:
- [Python SDK Reference](https://docs.tavily.com/sdk/python/reference)
- [JavaScript SDK Reference](https://docs.tavily.com/sdk/javascript/reference)

403
.config/opencode/skills/tavily-best-practices/references/search.md Normal file
View File

@@ -0,0 +1,403 @@
# Search API Reference
## Table of Contents
- [Query Optimization](#query-optimization)
- [Search Depth](#search-depth)
- [Key Parameters](#key-parameters)
- [Basic Usage](#basic-usage)
- [Filtering Results](#filtering-results)
- [Async Patterns](#async-patterns)
- [Response Fields](#response-fields)
- [Post-Filtering Strategies](#post-filtering-strategies)
---
## Query Optimization
**Keep queries under 400 characters.** Think search query, not long-form prompt.
**Break complex queries into sub-queries:**
```python
# Instead of one massive query, break it down:
queries = [
"Competitors of company ABC",
"Financial performance of company ABC",
"Recent developments of company ABC"
]
responses = await asyncio.gather(*(client.search(q) for q in queries))
```
## Search Depth
Controls the latency vs. relevance tradeoff:
| Depth | Latency | Relevance | Content Type |
|-------|---------|-----------|--------------|
| `ultra-fast` | Lowest | Lower | Content (NLP summary) |
| `fast` | Low | Good | Chunks |
| `basic` | Medium | High | Content (NLP summary) |
| `advanced` | Higher | Highest | Chunks |
**Content types:**
- **Content**: NLP-based summary of the page, providing general context
- **Chunks**: Short snippets (max 500 chars) reranked by relevance to your query
**When to use each:**
- `ultra-fast`: Latency-critical (real-time chat, autocomplete)
- `fast`: Need chunks but latency matters
- `basic`: General-purpose, balanced relevance and latency
- `advanced`: Specific information queries, precision matters - default (Still fast and suitable for almost all use cases)
## Key Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `query` | string | Required | Search query (keep under 400 chars) |
| `search_depth` | enum | `"basic"` | `"ultra-fast"`, `"fast"`, `"basic"`, `"advanced"` |
| `topic` | enum | `"general"` | `"general"`, `"news"`, `"finance"` |
| `chunks_per_source` | integer | 3 | Chunks per source (advanced/fast depth only) |
| `max_results` | integer | 5 | Maximum results (0-20) |
| `time_range` | enum | null | `"day"`, `"week"`, `"month"`, `"year"` |
| `start_date` | string | null | Results after date (YYYY-MM-DD) |
| `end_date` | string | null | Results before date (YYYY-MM-DD) |
| `include_domains` | array | [] | Domains to include (max 300, supports wildcards like `*.com`) |
| `exclude_domains` | array | [] | Domains to exclude (max 150) |
| `country` | enum | null | Boost results from country |
| `include_answer` | bool/enum | false | `true`/`"basic"` or `"advanced"` for LLM answer |
| `include_raw_content` | bool/enum | false | `true`/`"markdown"` or `"text"` for full page |
| `include_images` | boolean | false | Include image results |
| `include_image_descriptions` | boolean | false | AI descriptions for images |
| `include_favicon` | boolean | false | Favicon URL per result |
| `auto_parameters` | boolean | false | Auto-configure based on query intent |
| `include_usage` | boolean | false | Include credit usage info |
**Notes:**
- **`include_answer`**: Only use if you don't want to bring your own LLM. Most users bring their own model.
- **`auto_parameters`**: May set `search_depth="advanced"` (2 credits). Set `search_depth` manually to control cost.
## Basic Usage
```python
from tavily import TavilyClient
client = TavilyClient()
response = client.search(
query="latest developments in quantum computing",
max_results=10,
search_depth="advanced",
chunks_per_source=5
)
for result in response["results"]:
print(f"{result['title']}: {result['url']}")
print(f"Score: {result['score']}")
```
## Filtering Results
### By domain
```python
# Only search trusted sources
response = client.search(
query="machine learning best practices",
include_domains=["arxiv.org", "github.com", "pytorch.org"],
)
# Exclude specific domains
response = client.search(
query="openai product reviews",
exclude_domains=["reddit.com", "quora.com"]
)
# Restrict to LinkedIn profiles
response = client.search(
query="CEO background at Google",
include_domains=["linkedin.com/in"]
)
```
### By date
```python
# Relative time range
response = client.search(query="latest ML trends", time_range="month")
# Specific date range
response = client.search(
query="AI news",
start_date="2025-01-01",
end_date="2025-02-01"
)
```
### By country
```python
# Boost results from specific country
response = client.search(query="tech startup funding", country="united states")
```
## Async Patterns
Leveraging the async client enables scaled search with higher breadth and reach by running multiple queries in parallel. This is the best practice for agentic systems where you need to gather comprehensive information quickly before passing it to a model for analysis.
```python
import asyncio
from tavily import AsyncTavilyClient
# Initialize Tavily client
tavily_client = AsyncTavilyClient("tvly-YOUR_API_KEY")
async def fetch_and_gather():
queries = ["latest AI trends", "future of quantum computing"]
# Perform search and continue even if one query fails (using return_exceptions=True)
try:
responses = await asyncio.gather(*(tavily_client.search(q) for q in queries), return_exceptions=True)
# Handle responses and print
for response in responses:
if isinstance(response, Exception):
print(f"Search query failed: {response}")
else:
print(response)
except Exception as e:
print(f"Error during search queries: {e}")
# Run the function
asyncio.run(fetch_and_gather())
```
## Response Fields
**Top-level response:**
| Field | Description |
|-------|-------------|
| `query` | The original search query |
| `answer` | AI-generated answer (if `include_answer` enabled) |
| `results` | Array of search result objects |
| `images` | Array of image results (if `include_images=True`) |
**Each result object:**
| Field | Description |
|-------|-------------|
| `title` | Page title |
| `url` | Source URL |
| `content` | Extracted text snippet(s) |
| `score` | Semantic relevance score (0-1) |
| `raw_content` | Full page content (if `include_raw_content` enabled) |
| `favicon` | Favicon URL (if `include_favicon=True`) |
**Top-level response also includes:**
| Field | Description |
|-------|-------------|
| `request_id` | Unique identifier for support reference |
| `response_time` | Response time in seconds |
**Each image object (if `include_images=True`):**
| Field | Description |
|-------|-------------|
| `url` | Image URL |
| `description` | AI-generated description (if `include_image_descriptions=True`) |
---
## Post-Filtering Strategies
Since Tavily provides raw web data, you have full configurability to implement filtering and post-processing to meet your specific requirements.
The `score` field measures query relevance, but doesn't guarantee the result matches specific criteria (e.g., correct person, exact product, specific company). Use post-filtering to validate results against strict requirements.
### Score-Based Filtering
Simple threshold filtering based on relevance score:
```python
results = response["results"]
# Filter by score threshold
high_quality = [r for r in results if r["score"] > 0.7]
# Sort by score
sorted_results = sorted(results, key=lambda x: x["score"], reverse=True)
# Top N above threshold
top_relevant = sorted(
[r for r in results if r["score"] > 0.5],
key=lambda x: x["score"],
reverse=True
)[:3]
```
**Limitation:** Score indicates relevance to query, not accuracy of match to specific criteria.
### Regex Filtering
Fast, deterministic filtering using pattern matching. Use for:
- URL pattern validation
- Required keywords/phrases
- Structural requirements
```python
import re
def regex_filter(result, criteria: dict) -> dict:
"""
Filter a search result using regex checks.
Args:
result: Search result dict with url, content, title, raw_content
criteria: Dict with patterns to match:
- url_pattern: Regex for URL validation
- required_terms: List of terms that must appear in content
- excluded_terms: List of terms that must NOT appear
Returns:
dict with check results and validity
"""
url = result.get("url", "")
content = result.get("content", "") or ""
title = result.get("title", "") or ""
raw_content = result.get("raw_content", "") or ""
full_text = f"{content} {title} {raw_content}".lower()
checks = {}
# URL pattern check
if "url_pattern" in criteria:
checks["url_valid"] = bool(re.search(criteria["url_pattern"], url.lower()))
# Required terms check
if "required_terms" in criteria:
checks["required_found"] = all(
re.search(re.escape(term.lower()), full_text)
for term in criteria["required_terms"]
)
# Excluded terms check
if "excluded_terms" in criteria:
checks["excluded_absent"] = not any(
re.search(re.escape(term.lower()), full_text)
for term in criteria["excluded_terms"]
)
# Valid if all checks pass
is_valid = all(checks.values()) if checks else True
return {"checks": checks, "is_valid": is_valid, "url": url}
```
**Example: LinkedIn Profile Search**
```python
criteria = {
"url_pattern": r"linkedin\.com/in/", # Profile URL, not company page
"required_terms": ["Jane Smith", "Acme Corp"],
"excluded_terms": ["job posting", "careers"]
}
for result in response["results"]:
validation = regex_filter(result, criteria)
if validation["is_valid"]:
print(f"Valid: {validation['url']}")
```
**Example: GitHub Repository Search**
```python
criteria = {
"url_pattern": r"github\.com/[\w-]+/[\w-]+$", # Repo URL, not file
"required_terms": ["MIT License"],
"excluded_terms": ["archived", "deprecated"]
}
```
### LLM Verification
Semantic validation using an LLM. Use for:
- Synonym/abbreviation matching ("FDE" = "Forward Deployed Engineer")
- Context-aware validation
- Confidence scoring with reasoning
```python
from openai import OpenAI
import json
def llm_verify(result, target_description: str, validation_criteria: list[str]) -> dict:
"""
Use LLM to verify if a search result matches target criteria.
Args:
result: Search result dict
target_description: What you're looking for
validation_criteria: List of criteria to check
Returns:
dict with is_match, confidence (high/medium/low), reasoning
"""
content = result.get("content", "") or ""
title = result.get("title", "") or ""
url = result.get("url", "")
criteria_text = "\n".join(f"- {c}" for c in validation_criteria)
prompt = f"""Verify if this search result matches the target.
Target: {target_description}
Validation Criteria:
{criteria_text}
Search Result:
URL: {url}
Title: {title}
Content: {content}
Does this result match ALL criteria?
Respond with JSON only:
{{"is_match": true/false, "confidence": "high/medium/low", "reasoning": "brief explanation"}}"""
client = OpenAI()
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": prompt}],
response_format={"type": "json_object"}
)
return json.loads(response.choices[0].message.content)
```
**Example: Profile Verification**
```python
result = llm_verify(
result=search_result,
target_description="Jane Smith, Software Engineer at Acme Corp",
validation_criteria=[
"Name matches Jane Smith",
"Currently works at Acme Corp (or recently)",
"Role is software engineering related",
"Professional customer-facing experience"
]
)
if result["is_match"] and result["confidence"] in ["high", "medium"]:
print(f"Verified: {result['reasoning']}")
```
For more details, please read the [full API reference](https://docs.tavily.com/documentation/api-reference/endpoint/search)

76
.config/opencode/skills/tavily-cli/SKILL.md Normal file
View File

@@ -0,0 +1,76 @@
---
name: tavily-cli
description: |
Web search, content extraction, crawling, and deep research via the Tavily CLI. Use this skill whenever the user wants to search the web, find articles, research a topic, look something up online, extract content from a URL, grab text from a webpage, crawl documentation, download a site's pages, discover URLs on a domain, or conduct in-depth research with citations. Also use when they say "fetch this page", "pull the content from", "get the page at https://", "find me articles about", or reference extracting data from external websites. This provides LLM-optimized web search, content extraction, site crawling, URL discovery, and AI-powered deep research — capabilities beyond what agents can do natively. Do NOT trigger for local file operations, git commands, deployments, or code editing tasks.
compatibility: Requires tavily-cli (`curl -fsSL https://cli.tavily.com/install.sh | bash`) and a Tavily API key from tavily.com.
allowed-tools: Bash(tvly *)
---
# Tavily CLI
Web search, content extraction, site crawling, URL discovery, and deep research. Returns JSON optimized for LLM consumption.
Run `tvly --help` or `tvly <command> --help` for full option details.
## Prerequisites
Must be installed and authenticated. Check with `tvly --status`.
```bash
tavily v0.1.0
> Authenticated via OAuth (tvly login)
```
If not ready:
```bash
curl -fsSL https://cli.tavily.com/install.sh | bash
```
Or manually: `uv tool install tavily-cli` / `pip install tavily-cli`
Then authenticate:
```bash
tvly login --api-key tvly-YOUR_KEY
# or: export TAVILY_API_KEY=tvly-YOUR_KEY
# or: tvly login (opens browser for OAuth)
```
## Workflow
Follow this escalation pattern — start simple, escalate when needed:
1. **Search** — No specific URL. Find pages, answer questions, discover sources.
2. **Extract** — Have a URL. Pull its content directly.
3. **Map** — Large site, need to find the right page. Discover URLs first.
4. **Crawl** — Need bulk content from an entire site section.
5. **Research** — Need comprehensive, multi-source analysis with citations.
| Need | Command | When |
|------|---------|------|
| Find pages on a topic | `tvly search` | No specific URL yet |
| Get a page's content | `tvly extract` | Have a URL |
| Find URLs within a site | `tvly map` | Need to locate a specific subpage |
| Bulk extract a site section | `tvly crawl` | Need many pages (e.g., all /docs/) |
| Deep research with citations | `tvly research` | Need multi-source synthesis |
For detailed command reference, use the individual skill for each command (e.g., `tavily-search`, `tavily-crawl`) or run `tvly <command> --help`.
## Output
All commands support `--json` for structured, machine-readable output and `-o` to save to a file.
```bash
tvly search "react hooks" --json -o results.json
tvly extract "https://example.com/docs" -o docs.md
tvly crawl "https://docs.example.com" --output-dir ./docs/
```
## Tips
- **Always quote URLs** — shell interprets `?` and `&` as special characters.
- **Use `--json` for agentic workflows** — every command supports it.
- **Read from stdin with `-`** — `echo "query" | tvly search -`
- **Exit codes**: 0 = success, 2 = bad input, 3 = auth error, 4 = API error.

100
.config/opencode/skills/tavily-crawl/SKILL.md Normal file
View File

@@ -0,0 +1,100 @@
---
name: tavily-crawl
description: |
Crawl websites and extract content from multiple pages via the Tavily CLI. Use this skill when the user wants to crawl a site, download documentation, extract an entire docs section, bulk-extract pages, save a site as local markdown files, or says "crawl", "get all the pages", "download the docs", "extract everything under /docs", "bulk extract", or needs content from many pages on the same domain. Supports depth/breadth control, path filtering, semantic instructions, and saving each page as a local markdown file.
allowed-tools: Bash(tvly *)
---
# tavily crawl
Crawl a website and extract content from multiple pages. Supports saving each page as a local markdown file.
## Before running any command
If `tvly` is not found on PATH, install it first:
```bash
curl -fsSL https://cli.tavily.com/install.sh | bash && tvly login
```
Do not skip this step or fall back to other tools.
See [tavily-cli](../tavily-cli/SKILL.md) for alternative install methods and auth options.
## When to use
- You need content from many pages on a site (e.g., all `/docs/`)
- You want to download documentation for offline use
- Step 4 in the [workflow](../tavily-cli/SKILL.md): search → extract → map → **crawl** → research
## Quick start
```bash
# Basic crawl
tvly crawl "https://docs.example.com" --json
# Save each page as a markdown file
tvly crawl "https://docs.example.com" --output-dir ./docs/
# Deeper crawl with limits
tvly crawl "https://docs.example.com" --max-depth 2 --limit 50 --json
# Filter to specific paths
tvly crawl "https://example.com" --select-paths "/api/.*,/guides/.*" --exclude-paths "/blog/.*" --json
# Semantic focus (returns relevant chunks, not full pages)
tvly crawl "https://docs.example.com" --instructions "Find authentication docs" --chunks-per-source 3 --json
```
## Options
| Option | Description |
|--------|-------------|
| `--max-depth` | Levels deep (1-5, default: 1) |
| `--max-breadth` | Links per page (default: 20) |
| `--limit` | Total pages cap (default: 50) |
| `--instructions` | Natural language guidance for semantic focus |
| `--chunks-per-source` | Chunks per page (1-5, requires `--instructions`) |
| `--extract-depth` | `basic` (default) or `advanced` |
| `--format` | `markdown` (default) or `text` |
| `--select-paths` | Comma-separated regex patterns to include |
| `--exclude-paths` | Comma-separated regex patterns to exclude |
| `--select-domains` | Comma-separated regex for domains to include |
| `--exclude-domains` | Comma-separated regex for domains to exclude |
| `--allow-external / --no-external` | Include external links (default: allow) |
| `--include-images` | Include images |
| `--timeout` | Max wait (10-150 seconds) |
| `-o, --output` | Save JSON output to file |
| `--output-dir` | Save each page as a .md file in directory |
| `--json` | Structured JSON output |
## Crawl for context vs. data collection
**For agentic use** (feeding results to an LLM):
Always use `--instructions` + `--chunks-per-source`. Returns only relevant chunks instead of full pages — prevents context explosion.
```bash
tvly crawl "https://docs.example.com" --instructions "API authentication" --chunks-per-source 3 --json
```
**For data collection** (saving to files):
Use `--output-dir` without `--chunks-per-source` to get full pages as markdown files.
```bash
tvly crawl "https://docs.example.com" --max-depth 2 --output-dir ./docs/
```
## Tips
- **Start conservative** — `--max-depth 1`, `--limit 20` — and scale up.
- **Use `--select-paths`** to focus on the section you need.
- **Use map first** to understand site structure before a full crawl.
- **Always set `--limit`** to prevent runaway crawls.
## See also
- [tavily-map](../tavily-map/SKILL.md) — discover URLs before deciding to crawl
- [tavily-extract](../tavily-extract/SKILL.md) — extract individual pages
- [tavily-search](../tavily-search/SKILL.md) — find pages when you don't have a URL

80
.config/opencode/skills/tavily-extract/SKILL.md Normal file
View File

@@ -0,0 +1,80 @@
---
name: tavily-extract
description: |
Extract clean markdown or text content from specific URLs via the Tavily CLI. Use this skill when the user has one or more URLs and wants their content, says "extract", "grab the content from", "pull the text from", "get the page at", "read this webpage", or needs clean text from web pages. Handles JavaScript-rendered pages, returns LLM-optimized markdown, and supports query-focused chunking for targeted extraction. Can process up to 20 URLs in a single call.
allowed-tools: Bash(tvly *)
---
# tavily extract
Extract clean markdown or text content from one or more URLs.
## Before running any command
If `tvly` is not found on PATH, install it first:
```bash
curl -fsSL https://cli.tavily.com/install.sh | bash && tvly login
```
Do not skip this step or fall back to other tools.
See [tavily-cli](../tavily-cli/SKILL.md) for alternative install methods and auth options.
## When to use
- You have a specific URL and want its content
- You need text from JavaScript-rendered pages
- Step 2 in the [workflow](../tavily-cli/SKILL.md): search → **extract** → map → crawl → research
## Quick start
```bash
# Single URL
tvly extract "https://example.com/article" --json
# Multiple URLs
tvly extract "https://example.com/page1" "https://example.com/page2" --json
# Query-focused extraction (returns relevant chunks only)
tvly extract "https://example.com/docs" --query "authentication API" --chunks-per-source 3 --json
# JS-heavy pages
tvly extract "https://app.example.com" --extract-depth advanced --json
# Save to file
tvly extract "https://example.com/article" -o article.md
```
## Options
| Option | Description |
|--------|-------------|
| `--query` | Rerank chunks by relevance to this query |
| `--chunks-per-source` | Chunks per URL (1-5, requires `--query`) |
| `--extract-depth` | `basic` (default) or `advanced` (for JS pages) |
| `--format` | `markdown` (default) or `text` |
| `--include-images` | Include image URLs |
| `--timeout` | Max wait time (1-60 seconds) |
| `-o, --output` | Save output to file |
| `--json` | Structured JSON output |
## Extract depth
| Depth | When to use |
|-------|-------------|
| `basic` | Simple pages, fast — try this first |
| `advanced` | JS-rendered SPAs, dynamic content, tables |
## Tips
- **Max 20 URLs per request** — batch larger lists into multiple calls.
- **Use `--query` + `--chunks-per-source`** to get only relevant content instead of full pages.
- **Try `basic` first**, fall back to `advanced` if content is missing.
- **Set `--timeout`** for slow pages (up to 60s).
- If search results already contain the content you need (via `--include-raw-content`), skip the extract step.
## See also
- [tavily-search](../tavily-search/SKILL.md) — find pages when you don't have a URL
- [tavily-crawl](../tavily-crawl/SKILL.md) — extract content from many pages on a site

84
.config/opencode/skills/tavily-map/SKILL.md Normal file
View File

@@ -0,0 +1,84 @@
---
name: tavily-map
description: |
Discover and list all URLs on a website without extracting content, via the Tavily CLI. Use this skill when the user wants to find a specific page on a large site, list all URLs, see the site structure, find where something is on a domain, or says "map the site", "find the URL for", "what pages are on", "list all pages", or "site structure". Faster than crawling — returns URLs only. Essential when you know the site but not the exact page. Combine with extract for targeted content retrieval.
allowed-tools: Bash(tvly *)
---
# tavily map
Discover URLs on a website without extracting content. Faster than crawling.
## Before running any command
If `tvly` is not found on PATH, install it first:
```bash
curl -fsSL https://cli.tavily.com/install.sh | bash && tvly login
```
Do not skip this step or fall back to other tools.
See [tavily-cli](../tavily-cli/SKILL.md) for alternative install methods and auth options.
## When to use
- You need to find a specific subpage on a large site
- You want a list of all URLs before deciding what to extract or crawl
- Step 3 in the [workflow](../tavily-cli/SKILL.md): search → extract → **map** → crawl → research
## Quick start
```bash
# Discover all URLs
tvly map "https://docs.example.com" --json
# With natural language filtering
tvly map "https://docs.example.com" --instructions "Find API docs and guides" --json
# Filter by path
tvly map "https://example.com" --select-paths "/blog/.*" --limit 500 --json
# Deep map
tvly map "https://example.com" --max-depth 3 --limit 200 --json
```
## Options
| Option | Description |
|--------|-------------|
| `--max-depth` | Levels deep (1-5, default: 1) |
| `--max-breadth` | Links per page (default: 20) |
| `--limit` | Max URLs to discover (default: 50) |
| `--instructions` | Natural language guidance for URL filtering |
| `--select-paths` | Comma-separated regex patterns to include |
| `--exclude-paths` | Comma-separated regex patterns to exclude |
| `--select-domains` | Comma-separated regex for domains to include |
| `--exclude-domains` | Comma-separated regex for domains to exclude |
| `--allow-external / --no-external` | Include external links |
| `--timeout` | Max wait (10-150 seconds) |
| `-o, --output` | Save output to file |
| `--json` | Structured JSON output |
## Map + Extract pattern
Use `map` to find the right page, then `extract` it. This is often more efficient than crawling an entire site:
```bash
# Step 1: Find the authentication docs
tvly map "https://docs.example.com" --instructions "authentication" --json
# Step 2: Extract the specific page you found
tvly extract "https://docs.example.com/api/authentication" --json
```
## Tips
- **Map is URL discovery only** — no content extraction. Use `extract` or `crawl` for content.
- **Map + extract beats crawl** when you only need a few specific pages from a large site.
- **Use `--instructions`** for semantic filtering when path patterns aren't enough.
## See also
- [tavily-extract](../tavily-extract/SKILL.md) — extract content from URLs you discover
- [tavily-crawl](../tavily-crawl/SKILL.md) — bulk extract when you need many pages

100
.config/opencode/skills/tavily-research/SKILL.md Normal file
View File

@@ -0,0 +1,100 @@
---
name: tavily-research
description: |
Conduct comprehensive AI-powered research with citations via the Tavily CLI. Use this skill when the user wants deep research, a detailed report, a comparison, market analysis, literature review, or says "research", "investigate", "analyze in depth", "compare X vs Y", "what does the market look like for", or needs multi-source synthesis with explicit citations. Returns a structured report grounded in web sources. Takes 30-120 seconds. For quick fact-finding, use tavily-search instead.
allowed-tools: Bash(tvly *)
---
# tavily research
AI-powered deep research that gathers sources, analyzes them, and produces a cited report. Takes 30-120 seconds.
## Before running any command
If `tvly` is not found on PATH, install it first:
```bash
curl -fsSL https://cli.tavily.com/install.sh | bash && tvly login
```
Do not skip this step or fall back to other tools.
See [tavily-cli](../tavily-cli/SKILL.md) for alternative install methods and auth options.
## When to use
- You need comprehensive, multi-source analysis
- The user wants a comparison, market report, or literature review
- Quick searches aren't enough — you need synthesis with citations
- Step 5 in the [workflow](../tavily-cli/SKILL.md): search → extract → map → crawl → **research**
## Quick start
```bash
# Basic research (waits for completion)
tvly research "competitive landscape of AI code assistants"
# Pro model for comprehensive analysis
tvly research "electric vehicle market analysis" --model pro
# Stream results in real-time
tvly research "AI agent frameworks comparison" --stream
# Save report to file
tvly research "fintech trends 2025" --model pro -o fintech-report.md
# JSON output for agents
tvly research "quantum computing breakthroughs" --json
```
## Options
| Option | Description |
|--------|-------------|
| `--model` | `mini`, `pro`, or `auto` (default) |
| `--stream` | Stream results in real-time |
| `--no-wait` | Return request_id immediately (async) |
| `--output-schema` | Path to JSON schema for structured output |
| `--citation-format` | `numbered`, `mla`, `apa`, `chicago` |
| `--poll-interval` | Seconds between checks (default: 10) |
| `--timeout` | Max wait seconds (default: 600) |
| `-o, --output` | Save output to file |
| `--json` | Structured JSON output |
## Model selection
| Model | Use for | Speed |
|-------|---------|-------|
| `mini` | Single-topic, targeted research | ~30s |
| `pro` | Comprehensive multi-angle analysis | ~60-120s |
| `auto` | API chooses based on complexity | Varies |
**Rule of thumb:** "What does X do?" → mini. "X vs Y vs Z" or "best way to..." → pro.
## Async workflow
For long-running research, you can start and poll separately:
```bash
# Start without waiting
tvly research "topic" --no-wait --json # returns request_id
# Check status
tvly research status <request_id> --json
# Wait for completion
tvly research poll <request_id> --json -o result.json
```
## Tips
- **Research takes 30-120 seconds** — use `--stream` to see progress in real-time.
- **Use `--model pro`** for complex comparisons or multi-faceted topics.
- **Use `--output-schema`** to get structured JSON output matching a custom schema.
- **For quick facts**, use `tvly search` instead — research is for deep synthesis.
- Read from stdin: `echo "query" | tvly research - --json`
## See also
- [tavily-search](../tavily-search/SKILL.md) — quick web search for simple lookups
- [tavily-crawl](../tavily-crawl/SKILL.md) — bulk extract from a site for your own analysis

91
.config/opencode/skills/tavily-search/SKILL.md Normal file
View File

@@ -0,0 +1,91 @@
---
name: tavily-search
description: |
Search the web with LLM-optimized results via the Tavily CLI. Use this skill when the user wants to search the web, find articles, look up information, get recent news, discover sources, or says "search for", "find me", "look up", "what's the latest on", "find articles about", or needs current information from the internet. Returns relevant results with content snippets, relevance scores, and metadata — optimized for LLM consumption. Supports domain filtering, time ranges, and multiple search depths.
allowed-tools: Bash(tvly *)
---
# tavily search
Web search returning LLM-optimized results with content snippets and relevance scores.
## Before running any command
If `tvly` is not found on PATH, install it first:
```bash
curl -fsSL https://cli.tavily.com/install.sh | bash && tvly login
```
Do not skip this step or fall back to other tools.
See [tavily-cli](../tavily-cli/SKILL.md) for alternative install methods and auth options.
## When to use
- You need to find information on any topic
- You don't have a specific URL yet
- First step in the [workflow](../tavily-cli/SKILL.md): **search** → extract → map → crawl → research
## Quick start
```bash
# Basic search
tvly search "your query" --json
# Advanced search with more results
tvly search "quantum computing" --depth advanced --max-results 10 --json
# Recent news
tvly search "AI news" --time-range week --topic news --json
# Domain-filtered
tvly search "SEC filings" --include-domains sec.gov,reuters.com --json
# Include full page content in results
tvly search "react hooks tutorial" --include-raw-content --max-results 3 --json
```
## Options
| Option | Description |
|--------|-------------|
| `--depth` | `ultra-fast`, `fast`, `basic` (default), `advanced` |
| `--max-results` | Max results, 0-20 (default: 5) |
| `--topic` | `general` (default), `news`, `finance` |
| `--time-range` | `day`, `week`, `month`, `year` |
| `--start-date` | Results after date (YYYY-MM-DD) |
| `--end-date` | Results before date (YYYY-MM-DD) |
| `--include-domains` | Comma-separated domains to include |
| `--exclude-domains` | Comma-separated domains to exclude |
| `--country` | Boost results from country |
| `--include-answer` | Include AI answer (`basic` or `advanced`) |
| `--include-raw-content` | Include full page content (`markdown` or `text`) |
| `--include-images` | Include image results |
| `--include-image-descriptions` | Include AI image descriptions |
| `--chunks-per-source` | Chunks per source (advanced/fast depth only) |
| `-o, --output` | Save output to file |
| `--json` | Structured JSON output |
## Search depth
| Depth | Speed | Relevance | Best for |
|-------|-------|-----------|----------|
| `ultra-fast` | Fastest | Lower | Real-time chat, autocomplete |
| `fast` | Fast | Good | Need chunks, latency matters |
| `basic` | Medium | High | General-purpose (default) |
| `advanced` | Slower | Highest | Precision, specific facts |
## Tips
- **Keep queries under 400 characters** — think search query, not prompt.
- **Break complex queries into sub-queries** for better results.
- **Use `--include-raw-content`** when you need full page text (saves a separate extract call).
- **Use `--include-domains`** to focus on trusted sources.
- **Use `--time-range`** for recent information.
- Read from stdin: `echo "query" | tvly search - --json`
## See also
- [tavily-extract](../tavily-extract/SKILL.md) — extract content from specific URLs
- [tavily-research](../tavily-research/SKILL.md) — comprehensive multi-source research

371
.config/opencode/skills/test-driven-development/SKILL.md Normal file
View File

@@ -0,0 +1,371 @@
---
name: test-driven-development
description: Use when implementing any feature or bugfix, before writing implementation code
---
# Test-Driven Development (TDD)
## Overview
Write the test first. Watch it fail. Write minimal code to pass.
**Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing.
**Violating the letter of the rules is violating the spirit of the rules.**
## When to Use
**Always:**
- New features
- Bug fixes
- Refactoring
- Behavior changes
**Exceptions (ask your human partner):**
- Throwaway prototypes
- Generated code
- Configuration files
Thinking "skip TDD just this once"? Stop. That's rationalization.
## The Iron Law
```
NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
```
Write code before the test? Delete it. Start over.
**No exceptions:**
- Don't keep it as "reference"
- Don't "adapt" it while writing tests
- Don't look at it
- Delete means delete
Implement fresh from tests. Period.
## Red-Green-Refactor
```dot
digraph tdd_cycle {
rankdir=LR;
red [label="RED\nWrite failing test", shape=box, style=filled, fillcolor="#ffcccc"];
verify_red [label="Verify fails\ncorrectly", shape=diamond];
green [label="GREEN\nMinimal code", shape=box, style=filled, fillcolor="#ccffcc"];
verify_green [label="Verify passes\nAll green", shape=diamond];
refactor [label="REFACTOR\nClean up", shape=box, style=filled, fillcolor="#ccccff"];
next [label="Next", shape=ellipse];
red -> verify_red;
verify_red -> green [label="yes"];
verify_red -> red [label="wrong\nfailure"];
green -> verify_green;
verify_green -> refactor [label="yes"];
verify_green -> green [label="no"];
refactor -> verify_green [label="stay\ngreen"];
verify_green -> next;
next -> red;
}
```
### RED - Write Failing Test
Write one minimal test showing what should happen.
<Good>
```typescript
test('retries failed operations 3 times', async () => {
let attempts = 0;
const operation = () => {
attempts++;
if (attempts < 3) throw new Error('fail');
return 'success';
};
const result = await retryOperation(operation);
expect(result).toBe('success');
expect(attempts).toBe(3);
});
```
Clear name, tests real behavior, one thing
</Good>
<Bad>
```typescript
test('retry works', async () => {
const mock = jest.fn()
.mockRejectedValueOnce(new Error())
.mockRejectedValueOnce(new Error())
.mockResolvedValueOnce('success');
await retryOperation(mock);
expect(mock).toHaveBeenCalledTimes(3);
});
```
Vague name, tests mock not code
</Bad>
**Requirements:**
- One behavior
- Clear name
- Real code (no mocks unless unavoidable)
### Verify RED - Watch It Fail
**MANDATORY. Never skip.**
```bash
npm test path/to/test.test.ts
```
Confirm:
- Test fails (not errors)
- Failure message is expected
- Fails because feature missing (not typos)
**Test passes?** You're testing existing behavior. Fix test.
**Test errors?** Fix error, re-run until it fails correctly.
### GREEN - Minimal Code
Write simplest code to pass the test.
<Good>
```typescript
async function retryOperation<T>(fn: () => Promise<T>): Promise<T> {
for (let i = 0; i < 3; i++) {
try {
return await fn();
} catch (e) {
if (i === 2) throw e;
}
}
throw new Error('unreachable');
}
```
Just enough to pass
</Good>
<Bad>
```typescript
async function retryOperation<T>(
fn: () => Promise<T>,
options?: {
maxRetries?: number;
backoff?: 'linear' | 'exponential';
onRetry?: (attempt: number) => void;
}
): Promise<T> {
// YAGNI
}
```
Over-engineered
</Bad>
Don't add features, refactor other code, or "improve" beyond the test.
### Verify GREEN - Watch It Pass
**MANDATORY.**
```bash
npm test path/to/test.test.ts
```
Confirm:
- Test passes
- Other tests still pass
- Output pristine (no errors, warnings)
**Test fails?** Fix code, not test.
**Other tests fail?** Fix now.
### REFACTOR - Clean Up
After green only:
- Remove duplication
- Improve names
- Extract helpers
Keep tests green. Don't add behavior.
### Repeat
Next failing test for next feature.
## Good Tests
| Quality | Good | Bad |
|---------|------|-----|
| **Minimal** | One thing. "and" in name? Split it. | `test('validates email and domain and whitespace')` |
| **Clear** | Name describes behavior | `test('test1')` |
| **Shows intent** | Demonstrates desired API | Obscures what code should do |
## Why Order Matters
**"I'll write tests after to verify it works"**
Tests written after code pass immediately. Passing immediately proves nothing:
- Might test wrong thing
- Might test implementation, not behavior
- Might miss edge cases you forgot
- You never saw it catch the bug
Test-first forces you to see the test fail, proving it actually tests something.
**"I already manually tested all the edge cases"**
Manual testing is ad-hoc. You think you tested everything but:
- No record of what you tested
- Can't re-run when code changes
- Easy to forget cases under pressure
- "It worked when I tried it" ≠ comprehensive
Automated tests are systematic. They run the same way every time.
**"Deleting X hours of work is wasteful"**
Sunk cost fallacy. The time is already gone. Your choice now:
- Delete and rewrite with TDD (X more hours, high confidence)
- Keep it and add tests after (30 min, low confidence, likely bugs)
The "waste" is keeping code you can't trust. Working code without real tests is technical debt.
**"TDD is dogmatic, being pragmatic means adapting"**
TDD IS pragmatic:
- Finds bugs before commit (faster than debugging after)
- Prevents regressions (tests catch breaks immediately)
- Documents behavior (tests show how to use code)
- Enables refactoring (change freely, tests catch breaks)
"Pragmatic" shortcuts = debugging in production = slower.
**"Tests after achieve the same goals - it's spirit not ritual"**
No. Tests-after answer "What does this do?" Tests-first answer "What should this do?"
Tests-after are biased by your implementation. You test what you built, not what's required. You verify remembered edge cases, not discovered ones.
Tests-first force edge case discovery before implementing. Tests-after verify you remembered everything (you didn't).
30 minutes of tests after ≠ TDD. You get coverage, lose proof tests work.
## Common Rationalizations
| Excuse | Reality |
|--------|---------|
| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
| "I'll test after" | Tests passing immediately prove nothing. |
| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
| "Already manually tested" | Ad-hoc ≠ systematic. No record, can't re-run. |
| "Deleting X hours is wasteful" | Sunk cost fallacy. Keeping unverified code is technical debt. |
| "Keep as reference, write tests first" | You'll adapt it. That's testing after. Delete means delete. |
| "Need to explore first" | Fine. Throw away exploration, start with TDD. |
| "Test hard = design unclear" | Listen to test. Hard to test = hard to use. |
| "TDD will slow me down" | TDD faster than debugging. Pragmatic = test-first. |
| "Manual test faster" | Manual doesn't prove edge cases. You'll re-test every change. |
| "Existing code has no tests" | You're improving it. Add tests for existing code. |
## Red Flags - STOP and Start Over
- Code before test
- Test after implementation
- Test passes immediately
- Can't explain why test failed
- Tests added "later"
- Rationalizing "just this once"
- "I already manually tested it"
- "Tests after achieve the same purpose"
- "It's about spirit not ritual"
- "Keep as reference" or "adapt existing code"
- "Already spent X hours, deleting is wasteful"
- "TDD is dogmatic, I'm being pragmatic"
- "This is different because..."
**All of these mean: Delete code. Start over with TDD.**
## Example: Bug Fix
**Bug:** Empty email accepted
**RED**
```typescript
test('rejects empty email', async () => {
const result = await submitForm({ email: '' });
expect(result.error).toBe('Email required');
});
```
**Verify RED**
```bash
$ npm test
FAIL: expected 'Email required', got undefined
```
**GREEN**
```typescript
function submitForm(data: FormData) {
if (!data.email?.trim()) {
return { error: 'Email required' };
}
// ...
}
```
**Verify GREEN**
```bash
$ npm test
PASS
```
**REFACTOR**
Extract validation for multiple fields if needed.
## Verification Checklist
Before marking work complete:
- [ ] Every new function/method has a test
- [ ] Watched each test fail before implementing
- [ ] Each test failed for expected reason (feature missing, not typo)
- [ ] Wrote minimal code to pass each test
- [ ] All tests pass
- [ ] Output pristine (no errors, warnings)
- [ ] Tests use real code (mocks only if unavoidable)
- [ ] Edge cases and errors covered
Can't check all boxes? You skipped TDD. Start over.
## When Stuck
| Problem | Solution |
|---------|----------|
| Don't know how to test | Write wished-for API. Write assertion first. Ask your human partner. |
| Test too complicated | Design too complicated. Simplify interface. |
| Must mock everything | Code too coupled. Use dependency injection. |
| Test setup huge | Extract helpers. Still complex? Simplify design. |
## Debugging Integration
Bug found? Write failing test reproducing it. Follow TDD cycle. Test proves fix and prevents regression.
Never fix bugs without a test.
## Testing Anti-Patterns
When adding mocks or test utilities, read @testing-anti-patterns.md to avoid common pitfalls:
- Testing mock behavior instead of real behavior
- Adding test-only methods to production classes
- Mocking without understanding dependencies
## Final Rule
```
Production code → test exists and failed first
Otherwise → not TDD
```
No exceptions without your human partner's permission.

299
.config/opencode/skills/test-driven-development/testing-anti-patterns.md Normal file
View File

@@ -0,0 +1,299 @@
# Testing Anti-Patterns
**Load this reference when:** writing or changing tests, adding mocks, or tempted to add test-only methods to production code.
## Overview
Tests must verify real behavior, not mock behavior. Mocks are a means to isolate, not the thing being tested.
**Core principle:** Test what the code does, not what the mocks do.
**Following strict TDD prevents these anti-patterns.**
## The Iron Laws
```
1. NEVER test mock behavior
2. NEVER add test-only methods to production classes
3. NEVER mock without understanding dependencies
```
## Anti-Pattern 1: Testing Mock Behavior
**The violation:**
```typescript
// ❌ BAD: Testing that the mock exists
test('renders sidebar', () => {
render(<Page />);
expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
});
```
**Why this is wrong:**
- You're verifying the mock works, not that the component works
- Test passes when mock is present, fails when it's not
- Tells you nothing about real behavior
**your human partner's correction:** "Are we testing the behavior of a mock?"
**The fix:**
```typescript
// ✅ GOOD: Test real component or don't mock it
test('renders sidebar', () => {
render(<Page />); // Don't mock sidebar
expect(screen.getByRole('navigation')).toBeInTheDocument();
});
// OR if sidebar must be mocked for isolation:
// Don't assert on the mock - test Page's behavior with sidebar present
```
### Gate Function
```
BEFORE asserting on any mock element:
Ask: "Am I testing real component behavior or just mock existence?"
IF testing mock existence:
STOP - Delete the assertion or unmock the component
Test real behavior instead
```
## Anti-Pattern 2: Test-Only Methods in Production
**The violation:**
```typescript
// ❌ BAD: destroy() only used in tests
class Session {
async destroy() { // Looks like production API!
await this._workspaceManager?.destroyWorkspace(this.id);
// ... cleanup
}
}
// In tests
afterEach(() => session.destroy());
```
**Why this is wrong:**
- Production class polluted with test-only code
- Dangerous if accidentally called in production
- Violates YAGNI and separation of concerns
- Confuses object lifecycle with entity lifecycle
**The fix:**
```typescript
// ✅ GOOD: Test utilities handle test cleanup
// Session has no destroy() - it's stateless in production
// In test-utils/
export async function cleanupSession(session: Session) {
const workspace = session.getWorkspaceInfo();
if (workspace) {
await workspaceManager.destroyWorkspace(workspace.id);
}
}
// In tests
afterEach(() => cleanupSession(session));
```
### Gate Function
```
BEFORE adding any method to production class:
Ask: "Is this only used by tests?"
IF yes:
STOP - Don't add it
Put it in test utilities instead
Ask: "Does this class own this resource's lifecycle?"
IF no:
STOP - Wrong class for this method
```
## Anti-Pattern 3: Mocking Without Understanding
**The violation:**
```typescript
// ❌ BAD: Mock breaks test logic
test('detects duplicate server', () => {
// Mock prevents config write that test depends on!
vi.mock('ToolCatalog', () => ({
discoverAndCacheTools: vi.fn().mockResolvedValue(undefined)
}));
await addServer(config);
await addServer(config); // Should throw - but won't!
});
```
**Why this is wrong:**
- Mocked method had side effect test depended on (writing config)
- Over-mocking to "be safe" breaks actual behavior
- Test passes for wrong reason or fails mysteriously
**The fix:**
```typescript
// ✅ GOOD: Mock at correct level
test('detects duplicate server', () => {
// Mock the slow part, preserve behavior test needs
vi.mock('MCPServerManager'); // Just mock slow server startup
await addServer(config); // Config written
await addServer(config); // Duplicate detected ✓
});
```
### Gate Function
```
BEFORE mocking any method:
STOP - Don't mock yet
1. Ask: "What side effects does the real method have?"
2. Ask: "Does this test depend on any of those side effects?"
3. Ask: "Do I fully understand what this test needs?"
IF depends on side effects:
Mock at lower level (the actual slow/external operation)
OR use test doubles that preserve necessary behavior
NOT the high-level method the test depends on
IF unsure what test depends on:
Run test with real implementation FIRST
Observe what actually needs to happen
THEN add minimal mocking at the right level
Red flags:
- "I'll mock this to be safe"
- "This might be slow, better mock it"
- Mocking without understanding the dependency chain
```
## Anti-Pattern 4: Incomplete Mocks
**The violation:**
```typescript
// ❌ BAD: Partial mock - only fields you think you need
const mockResponse = {
status: 'success',
data: { userId: '123', name: 'Alice' }
// Missing: metadata that downstream code uses
};
// Later: breaks when code accesses response.metadata.requestId
```
**Why this is wrong:**
- **Partial mocks hide structural assumptions** - You only mocked fields you know about
- **Downstream code may depend on fields you didn't include** - Silent failures
- **Tests pass but integration fails** - Mock incomplete, real API complete
- **False confidence** - Test proves nothing about real behavior
**The Iron Rule:** Mock the COMPLETE data structure as it exists in reality, not just fields your immediate test uses.
**The fix:**
```typescript
// ✅ GOOD: Mirror real API completeness
const mockResponse = {
status: 'success',
data: { userId: '123', name: 'Alice' },
metadata: { requestId: 'req-789', timestamp: 1234567890 }
// All fields real API returns
};
```
### Gate Function
```
BEFORE creating mock responses:
Check: "What fields does the real API response contain?"
Actions:
1. Examine actual API response from docs/examples
2. Include ALL fields system might consume downstream
3. Verify mock matches real response schema completely
Critical:
If you're creating a mock, you must understand the ENTIRE structure
Partial mocks fail silently when code depends on omitted fields
If uncertain: Include all documented fields
```
## Anti-Pattern 5: Integration Tests as Afterthought
**The violation:**
```
✅ Implementation complete
❌ No tests written
"Ready for testing"
```
**Why this is wrong:**
- Testing is part of implementation, not optional follow-up
- TDD would have caught this
- Can't claim complete without tests
**The fix:**
```
TDD cycle:
1. Write failing test
2. Implement to pass
3. Refactor
4. THEN claim complete
```
## When Mocks Become Too Complex
**Warning signs:**
- Mock setup longer than test logic
- Mocking everything to make test pass
- Mocks missing methods real components have
- Test breaks when mock changes
**your human partner's question:** "Do we need to be using a mock here?"
**Consider:** Integration tests with real components often simpler than complex mocks
## TDD Prevents These Anti-Patterns
**Why TDD helps:**
1. **Write test first** → Forces you to think about what you're actually testing
2. **Watch it fail** → Confirms test tests real behavior, not mocks
3. **Minimal implementation** → No test-only methods creep in
4. **Real dependencies** → You see what the test actually needs before mocking
**If you're testing mock behavior, you violated TDD** - you added mocks without watching test fail against real code first.
## Quick Reference
| Anti-Pattern | Fix |
|--------------|-----|
| Assert on mock elements | Test real component or unmock it |
| Test-only methods in production | Move to test utilities |
| Mock without understanding | Understand dependencies first, mock minimally |
| Incomplete mocks | Mirror real API completely |
| Tests as afterthought | TDD - tests first |
| Over-complex mocks | Consider integration tests |
## Red Flags
- Assertion checks for `*-mock` test IDs
- Methods only called in test files
- Mock setup is >50% of test
- Test fails when you remove mock
- Can't explain why mock is needed
- Mocking "just to be safe"
## The Bottom Line
**Mocks are tools to isolate, not things to test.**
If TDD reveals you're testing mock behavior, you've gone wrong.
Fix: Test real behavior or question why you're mocking at all.

54
.config/opencode/skills/test-migration-skill.backup.20260321_182942/SKILL.md Normal file
View File

@@ -0,0 +1,54 @@
---
name: test-migration-skill
description: This skill should be used when the user asks to "DESCRIPTION_HERE". Add specific trigger phrases that would activate this skill.
license: MIT
compatibility: opencode
metadata:
category: general
version: "1.0.0"
---
# test-migration-skill
Brief description of what this skill does and its purpose.
## What This Skill Provides
1. **Feature 1** - Brief description
2. **Feature 2** - Brief description
3. **Feature 3** - Brief description
## Quick Start
Basic usage example:
```bash
# Example command
some-tool --option value
```
## Common Tasks
### Task 1: Description
Step-by-step instructions:
1. First step
2. Second step
3. Third step
### Task 2: Description
Step-by-step instructions:
1. First step
2. Second step
## Important Notes
- Keep this section brief
- Use bullet points for clarity
- Reference supporting files if available
## Resources

54
.config/opencode/skills/test-migration-skill/SKILL.md Normal file
View File

@@ -0,0 +1,54 @@
---
name: test-migration-skill
description: This skill should be used when the user asks to "DESCRIPTION_HERE". Add specific trigger phrases that would activate this skill.
license: MIT
compatibility: opencode
metadata:
category: general
version: "1.0.0"
---
# test-migration-skill
Brief description of what this skill does and its purpose.
## What This Skill Provides
1. **Feature 1** - Brief description
2. **Feature 2** - Brief description
3. **Feature 3** - Brief description
## Quick Start
Basic usage example:
```bash
# Example command
some-tool --option value
```
## Common Tasks
### Task 1: Description
Step-by-step instructions:
1. First step
2. Second step
3. Third step
### Task 2: Description
Step-by-step instructions:
1. First step
2. Second step
## Important Notes
- Keep this section brief
- Use bullet points for clarity
- Reference supporting files if available
## Resources

9
.config/opencode/skills/test-skill-1.backup.20260321_185203/SKILL.md Normal file
View File

@@ -0,0 +1,9 @@
---
name: test-skill-1
description: Test skill 1 for migration testing
---
# Test Skill 1
This is a test skill.
# Modified

9
.config/opencode/skills/test-skill-1/SKILL.md Normal file
View File

@@ -0,0 +1,9 @@
---
name: test-skill-1
description: Test skill 1 for migration testing
---
# Test Skill 1
This is a test skill.
# Modified

8
.config/opencode/skills/test-skill-2.backup.20260321_185203/SKILL.md Normal file
View File

@@ -0,0 +1,8 @@
---
name: test-skill-2
description: Test skill 2 for migration testing
---
# Test Skill 2
This is another test skill.

8
.config/opencode/skills/test-skill-2/SKILL.md Normal file
View File

@@ -0,0 +1,8 @@
---
name: test-skill-2
description: Test skill 2 for migration testing
---
# Test Skill 2
This is another test skill.

218
.config/opencode/skills/using-git-worktrees/SKILL.md Normal file
View File

@@ -0,0 +1,218 @@
---
name: using-git-worktrees
description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification
---
# Using Git Worktrees
## Overview
Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.
**Core principle:** Systematic directory selection + safety verification = reliable isolation.
**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."
## Directory Selection Process
Follow this priority order:
### 1. Check Existing Directories
```bash
# Check in priority order
ls -d .worktrees 2>/dev/null # Preferred (hidden)
ls -d worktrees 2>/dev/null # Alternative
```
**If found:** Use that directory. If both exist, `.worktrees` wins.
### 2. Check CLAUDE.md
```bash
grep -i "worktree.*director" CLAUDE.md 2>/dev/null
```
**If preference specified:** Use it without asking.
### 3. Ask User
If no directory exists and no CLAUDE.md preference:
```
No worktree directory found. Where should I create worktrees?
1. .worktrees/ (project-local, hidden)
2. ~/.config/superpowers/worktrees/<project-name>/ (global location)
Which would you prefer?
```
## Safety Verification
### For Project-Local Directories (.worktrees or worktrees)
**MUST verify directory is ignored before creating worktree:**
```bash
# Check if directory is ignored (respects local, global, and system gitignore)
git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
```
**If NOT ignored:**
Per Jesse's rule "Fix broken things immediately":
1. Add appropriate line to .gitignore
2. Commit the change
3. Proceed with worktree creation
**Why critical:** Prevents accidentally committing worktree contents to repository.
### For Global Directory (~/.config/superpowers/worktrees)
No .gitignore verification needed - outside project entirely.
## Creation Steps
### 1. Detect Project Name
```bash
project=$(basename "$(git rev-parse --show-toplevel)")
```
### 2. Create Worktree
```bash
# Determine full path
case $LOCATION in
.worktrees|worktrees)
path="$LOCATION/$BRANCH_NAME"
;;
~/.config/superpowers/worktrees/*)
path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME"
;;
esac
# Create worktree with new branch
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"
```
### 3. Run Project Setup
Auto-detect and run appropriate setup:
```bash
# Node.js
if [ -f package.json ]; then npm install; fi
# Rust
if [ -f Cargo.toml ]; then cargo build; fi
# Python
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi
# Go
if [ -f go.mod ]; then go mod download; fi
```
### 4. Verify Clean Baseline
Run tests to ensure worktree starts clean:
```bash
# Examples - use project-appropriate command
npm test
cargo test
pytest
go test ./...
```
**If tests fail:** Report failures, ask whether to proceed or investigate.
**If tests pass:** Report ready.
### 5. Report Location
```
Worktree ready at <full-path>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>
```
## Quick Reference
| Situation | Action |
|-----------|--------|
| `.worktrees/` exists | Use it (verify ignored) |
| `worktrees/` exists | Use it (verify ignored) |
| Both exist | Use `.worktrees/` |
| Neither exists | Check CLAUDE.md → Ask user |
| Directory not ignored | Add to .gitignore + commit |
| Tests fail during baseline | Report failures + ask |
| No package.json/Cargo.toml | Skip dependency install |
## Common Mistakes
### Skipping ignore verification
- **Problem:** Worktree contents get tracked, pollute git status
- **Fix:** Always use `git check-ignore` before creating project-local worktree
### Assuming directory location
- **Problem:** Creates inconsistency, violates project conventions
- **Fix:** Follow priority: existing > CLAUDE.md > ask
### Proceeding with failing tests
- **Problem:** Can't distinguish new bugs from pre-existing issues
- **Fix:** Report failures, get explicit permission to proceed
### Hardcoding setup commands
- **Problem:** Breaks on projects using different tools
- **Fix:** Auto-detect from project files (package.json, etc.)
## Example Workflow
```
You: I'm using the using-git-worktrees skill to set up an isolated workspace.
[Check .worktrees/ - exists]
[Verify ignored - git check-ignore confirms .worktrees/ is ignored]
[Create worktree: git worktree add .worktrees/auth -b feature/auth]
[Run npm install]
[Run npm test - 47 passing]
Worktree ready at /Users/jesse/myproject/.worktrees/auth
Tests passing (47 tests, 0 failures)
Ready to implement auth feature
```
## Red Flags
**Never:**
- Create worktree without verifying it's ignored (project-local)
- Skip baseline test verification
- Proceed with failing tests without asking
- Assume directory location when ambiguous
- Skip CLAUDE.md check
**Always:**
- Follow directory priority: existing > CLAUDE.md > ask
- Verify directory is ignored for project-local
- Auto-detect and run project setup
- Verify clean test baseline
## Integration
**Called by:**
- **brainstorming** (Phase 4) - REQUIRED when design is approved and implementation follows
- **subagent-driven-development** - REQUIRED before executing any tasks
- **executing-plans** - REQUIRED before executing any tasks
- Any skill needing isolated workspace
**Pairs with:**
- **finishing-a-development-branch** - REQUIRED for cleanup after work complete

115
.config/opencode/skills/using-superpowers/SKILL.md Normal file
View File

@@ -0,0 +1,115 @@
---
name: using-superpowers
description: Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions
---
<SUBAGENT-STOP>
If you were dispatched as a subagent to execute a specific task, skip this skill.
</SUBAGENT-STOP>
<EXTREMELY-IMPORTANT>
If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill.
IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
This is not negotiable. This is not optional. You cannot rationalize your way out of this.
</EXTREMELY-IMPORTANT>
## Instruction Priority
Superpowers skills override default system prompt behavior, but **user instructions always take precedence**:
1. **User's explicit instructions** (CLAUDE.md, GEMINI.md, AGENTS.md, direct requests) — highest priority
2. **Superpowers skills** — override default system behavior where they conflict
3. **Default system prompt** — lowest priority
If CLAUDE.md, GEMINI.md, or AGENTS.md says "don't use TDD" and a skill says "always use TDD," follow the user's instructions. The user is in control.
## How to Access Skills
**In Claude Code:** Use the `Skill` tool. When you invoke a skill, its content is loaded and presented to you—follow it directly. Never use the Read tool on skill files.
**In Gemini CLI:** Skills activate via the `activate_skill` tool. Gemini loads skill metadata at session start and activates the full content on demand.
**In other environments:** Check your platform's documentation for how skills are loaded.
## Platform Adaptation
Skills use Claude Code tool names. Non-CC platforms: see `references/codex-tools.md` (Codex) for tool equivalents. Gemini CLI users get the tool mapping loaded automatically via GEMINI.md.
# Using Skills
## The Rule
**Invoke relevant or requested skills BEFORE any response or action.** Even a 1% chance a skill might apply means that you should invoke the skill to check. If an invoked skill turns out to be wrong for the situation, you don't need to use it.
```dot
digraph skill_flow {
"User message received" [shape=doublecircle];
"About to EnterPlanMode?" [shape=doublecircle];
"Already brainstormed?" [shape=diamond];
"Invoke brainstorming skill" [shape=box];
"Might any skill apply?" [shape=diamond];
"Invoke Skill tool" [shape=box];
"Announce: 'Using [skill] to [purpose]'" [shape=box];
"Has checklist?" [shape=diamond];
"Create TodoWrite todo per item" [shape=box];
"Follow skill exactly" [shape=box];
"Respond (including clarifications)" [shape=doublecircle];
"About to EnterPlanMode?" -> "Already brainstormed?";
"Already brainstormed?" -> "Invoke brainstorming skill" [label="no"];
"Already brainstormed?" -> "Might any skill apply?" [label="yes"];
"Invoke brainstorming skill" -> "Might any skill apply?";
"User message received" -> "Might any skill apply?";
"Might any skill apply?" -> "Invoke Skill tool" [label="yes, even 1%"];
"Might any skill apply?" -> "Respond (including clarifications)" [label="definitely not"];
"Invoke Skill tool" -> "Announce: 'Using [skill] to [purpose]'";
"Announce: 'Using [skill] to [purpose]'" -> "Has checklist?";
"Has checklist?" -> "Create TodoWrite todo per item" [label="yes"];
"Has checklist?" -> "Follow skill exactly" [label="no"];
"Create TodoWrite todo per item" -> "Follow skill exactly";
}
```
## Red Flags
These thoughts mean STOP—you're rationalizing:
| Thought | Reality |
|---------|---------|
| "This is just a simple question" | Questions are tasks. Check for skills. |
| "I need more context first" | Skill check comes BEFORE clarifying questions. |
| "Let me explore the codebase first" | Skills tell you HOW to explore. Check first. |
| "I can check git/files quickly" | Files lack conversation context. Check for skills. |
| "Let me gather information first" | Skills tell you HOW to gather information. |
| "This doesn't need a formal skill" | If a skill exists, use it. |
| "I remember this skill" | Skills evolve. Read current version. |
| "This doesn't count as a task" | Action = task. Check for skills. |
| "The skill is overkill" | Simple things become complex. Use it. |
| "I'll just do this one thing first" | Check BEFORE doing anything. |
| "This feels productive" | Undisciplined action wastes time. Skills prevent this. |
| "I know what that means" | Knowing the concept ≠ using the skill. Invoke it. |
## Skill Priority
When multiple skills could apply, use this order:
1. **Process skills first** (brainstorming, debugging) - these determine HOW to approach the task
2. **Implementation skills second** (frontend-design, mcp-builder) - these guide execution
"Let's build X" → brainstorming first, then implementation skills.
"Fix this bug" → debugging first, then domain-specific skills.
## Skill Types
**Rigid** (TDD, debugging): Follow exactly. Don't adapt away discipline.
**Flexible** (patterns): Adapt principles to context.
The skill itself tells you which.
## User Instructions
Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows.

25
.config/opencode/skills/using-superpowers/references/codex-tools.md Normal file
View File

@@ -0,0 +1,25 @@
# Codex Tool Mapping
Skills use Claude Code tool names. When you encounter these in a skill, use your platform equivalent:
| Skill references | Codex equivalent |
|-----------------|------------------|
| `Task` tool (dispatch subagent) | `spawn_agent` |
| Multiple `Task` calls (parallel) | Multiple `spawn_agent` calls |
| Task returns result | `wait` |
| Task completes automatically | `close_agent` to free slot |
| `TodoWrite` (task tracking) | `update_plan` |
| `Skill` tool (invoke a skill) | Skills load natively — just follow the instructions |
| `Read`, `Write`, `Edit` (files) | Use your native file tools |
| `Bash` (run commands) | Use your native shell tools |
## Subagent dispatch requires multi-agent support
Add to your Codex config (`~/.codex/config.toml`):
```toml
[features]
multi_agent = true
```
This enables `spawn_agent`, `wait`, and `close_agent` for skills like `dispatching-parallel-agents` and `subagent-driven-development`.

33
.config/opencode/skills/using-superpowers/references/gemini-tools.md Normal file
View File

@@ -0,0 +1,33 @@
# Gemini CLI Tool Mapping
Skills use Claude Code tool names. When you encounter these in a skill, use your platform equivalent:
| Skill references | Gemini CLI equivalent |
|-----------------|----------------------|
| `Read` (file reading) | `read_file` |
| `Write` (file creation) | `write_file` |
| `Edit` (file editing) | `replace` |
| `Bash` (run commands) | `run_shell_command` |
| `Grep` (search file content) | `grep_search` |
| `Glob` (search files by name) | `glob` |
| `TodoWrite` (task tracking) | `write_todos` |
| `Skill` tool (invoke a skill) | `activate_skill` |
| `WebSearch` | `google_web_search` |
| `WebFetch` | `web_fetch` |
| `Task` tool (dispatch subagent) | No equivalent — Gemini CLI does not support subagents |
## No subagent support
Gemini CLI has no equivalent to Claude Code's `Task` tool. Skills that rely on subagent dispatch (`subagent-driven-development`, `dispatching-parallel-agents`) will fall back to single-session execution via `executing-plans`.
## Additional Gemini CLI tools
These tools are available in Gemini CLI but have no Claude Code equivalent:
| Tool | Purpose |
|------|---------|
| `list_directory` | List files and subdirectories |
| `save_memory` | Persist facts to GEMINI.md across sessions |
| `ask_user` | Request structured input from the user |
| `tracker_create_task` | Rich task management (create, update, list, visualize) |
| `enter_plan_mode` / `exit_plan_mode` | Switch to read-only research mode before making changes |

139
.config/opencode/skills/verification-before-completion/SKILL.md Normal file
View File

@@ -0,0 +1,139 @@
---
name: verification-before-completion
description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
---
# Verification Before Completion
## Overview
Claiming work is complete without verification is dishonesty, not efficiency.
**Core principle:** Evidence before claims, always.
**Violating the letter of this rule is violating the spirit of this rule.**
## The Iron Law
```
NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
```
If you haven't run the verification command in this message, you cannot claim it passes.
## The Gate Function
```
BEFORE claiming any status or expressing satisfaction:
1. IDENTIFY: What command proves this claim?
2. RUN: Execute the FULL command (fresh, complete)
3. READ: Full output, check exit code, count failures
4. VERIFY: Does output confirm the claim?
- If NO: State actual status with evidence
- If YES: State claim WITH evidence
5. ONLY THEN: Make the claim
Skip any step = lying, not verifying
```
## Common Failures
| Claim | Requires | Not Sufficient |
|-------|----------|----------------|
| Tests pass | Test command output: 0 failures | Previous run, "should pass" |
| Linter clean | Linter output: 0 errors | Partial check, extrapolation |
| Build succeeds | Build command: exit 0 | Linter passing, logs look good |
| Bug fixed | Test original symptom: passes | Code changed, assumed fixed |
| Regression test works | Red-green cycle verified | Test passes once |
| Agent completed | VCS diff shows changes | Agent reports "success" |
| Requirements met | Line-by-line checklist | Tests passing |
## Red Flags - STOP
- Using "should", "probably", "seems to"
- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!", etc.)
- About to commit/push/PR without verification
- Trusting agent success reports
- Relying on partial verification
- Thinking "just this once"
- Tired and wanting work over
- **ANY wording implying success without having run verification**
## Rationalization Prevention
| Excuse | Reality |
|--------|---------|
| "Should work now" | RUN the verification |
| "I'm confident" | Confidence ≠ evidence |
| "Just this once" | No exceptions |
| "Linter passed" | Linter ≠ compiler |
| "Agent said success" | Verify independently |
| "I'm tired" | Exhaustion ≠ excuse |
| "Partial check is enough" | Partial proves nothing |
| "Different words so rule doesn't apply" | Spirit over letter |
## Key Patterns
**Tests:**
```
✅ [Run test command] [See: 34/34 pass] "All tests pass"
❌ "Should pass now" / "Looks correct"
```
**Regression tests (TDD Red-Green):**
```
✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
❌ "I've written a regression test" (without red-green verification)
```
**Build:**
```
✅ [Run build] [See: exit 0] "Build passes"
❌ "Linter passed" (linter doesn't check compilation)
```
**Requirements:**
```
✅ Re-read plan → Create checklist → Verify each → Report gaps or completion
❌ "Tests pass, phase complete"
```
**Agent delegation:**
```
✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
❌ Trust agent report
```
## Why This Matters
From 24 failure memories:
- your human partner said "I don't believe you" - trust broken
- Undefined functions shipped - would crash
- Missing requirements shipped - incomplete features
- Time wasted on false completion → redirect → rework
- Violates: "Honesty is a core value. If you lie, you'll be replaced."
## When To Apply
**ALWAYS before:**
- ANY variation of success/completion claims
- ANY expression of satisfaction
- ANY positive statement about work state
- Committing, PR creation, task completion
- Moving to next task
- Delegating to agents
**Rule applies to:**
- Exact phrases
- Paraphrases and synonyms
- Implications of success
- ANY communication suggesting completion/correctness
## The Bottom Line
**No shortcuts for verification.**
Run the command. Read the output. THEN claim the result.
This is non-negotiable.

145
.config/opencode/skills/writing-plans/SKILL.md Normal file
View File

@@ -0,0 +1,145 @@
---
name: writing-plans
description: Use when you have a spec or requirements for a multi-step task, before touching code
---
# Writing Plans
## Overview
Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.
**Announce at start:** "I'm using the writing-plans skill to create the implementation plan."
**Context:** This should be run in a dedicated worktree (created by brainstorming skill).
**Save plans to:** `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`
- (User preferences for plan location override this default)
## Scope Check
If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans — one per subsystem. Each plan should produce working, testable software on its own.
## File Structure
Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in.
- Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility.
- You reason best about code you can hold in context at once, and your edits are more reliable when files are focused. Prefer smaller, focused files over large ones that do too much.
- Files that change together should live together. Split by responsibility, not by technical layer.
- In existing codebases, follow established patterns. If the codebase uses large files, don't unilaterally restructure - but if a file you're modifying has grown unwieldy, including a split in the plan is reasonable.
This structure informs the task decomposition. Each task should produce self-contained changes that make sense independently.
## Bite-Sized Task Granularity
**Each step is one action (2-5 minutes):**
- "Write the failing test" - step
- "Run it to make sure it fails" - step
- "Implement the minimal code to make the test pass" - step
- "Run the tests and make sure they pass" - step
- "Commit" - step
## Plan Document Header
**Every plan MUST start with this header:**
```markdown
# [Feature Name] Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** [One sentence describing what this builds]
**Architecture:** [2-3 sentences about approach]
**Tech Stack:** [Key technologies/libraries]
---
```
## Task Structure
````markdown
### Task N: [Component Name]
**Files:**
- Create: `exact/path/to/file.py`
- Modify: `exact/path/to/existing.py:123-145`
- Test: `tests/exact/path/to/test.py`
- [ ] **Step 1: Write the failing test**
```python
def test_specific_behavior():
result = function(input)
assert result == expected
```
- [ ] **Step 2: Run test to verify it fails**
Run: `pytest tests/path/test.py::test_name -v`
Expected: FAIL with "function not defined"
- [ ] **Step 3: Write minimal implementation**
```python
def function(input):
return expected
```
- [ ] **Step 4: Run test to verify it passes**
Run: `pytest tests/path/test.py::test_name -v`
Expected: PASS
- [ ] **Step 5: Commit**
```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
```
````
## Remember
- Exact file paths always
- Complete code in plan (not "add validation")
- Exact commands with expected output
- Reference relevant skills with @ syntax
- DRY, YAGNI, TDD, frequent commits
## Plan Review Loop
After writing the complete plan:
1. Dispatch a single plan-document-reviewer subagent (see plan-document-reviewer-prompt.md) with precisely crafted review context — never your session history. This keeps the reviewer focused on the plan, not your thought process.
- Provide: path to the plan document, path to spec document
2. If ❌ Issues Found: fix the issues, re-dispatch reviewer for the whole plan
3. If ✅ Approved: proceed to execution handoff
**Review loop guidance:**
- Same agent that wrote the plan fixes it (preserves context)
- If loop exceeds 3 iterations, surface to human for guidance
- Reviewers are advisory — explain disagreements if you believe feedback is incorrect
## Execution Handoff
After saving the plan, offer execution choice:
**"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Two execution options:**
**1. Subagent-Driven (recommended)** - I dispatch a fresh subagent per task, review between tasks, fast iteration
**2. Inline Execution** - Execute tasks in this session using executing-plans, batch execution with checkpoints
**Which approach?"**
**If Subagent-Driven chosen:**
- **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development
- Fresh subagent per task + two-stage review
**If Inline Execution chosen:**
- **REQUIRED SUB-SKILL:** Use superpowers:executing-plans
- Batch execution with checkpoints for review

49
.config/opencode/skills/writing-plans/plan-document-reviewer-prompt.md Normal file
View File

@@ -0,0 +1,49 @@
# Plan Document Reviewer Prompt Template
Use this template when dispatching a plan document reviewer subagent.
**Purpose:** Verify the plan is complete, matches the spec, and has proper task decomposition.
**Dispatch after:** The complete plan is written.
```
Task tool (general-purpose):
description: "Review plan document"
prompt: |
You are a plan document reviewer. Verify this plan is complete and ready for implementation.
**Plan to review:** [PLAN_FILE_PATH]
**Spec for reference:** [SPEC_FILE_PATH]
## What to Check
| Category | What to Look For |
|----------|------------------|
| Completeness | TODOs, placeholders, incomplete tasks, missing steps |
| Spec Alignment | Plan covers spec requirements, no major scope creep |
| Task Decomposition | Tasks have clear boundaries, steps are actionable |
| Buildability | Could an engineer follow this plan without getting stuck? |
## Calibration
**Only flag issues that would cause real problems during implementation.**
An implementer building the wrong thing or getting stuck is an issue.
Minor wording, stylistic preferences, and "nice to have" suggestions are not.
Approve unless there are serious gaps — missing requirements from the spec,
contradictory steps, placeholder content, or tasks so vague they can't be acted on.
## Output Format
## Plan Review
**Status:** Approved | Issues Found
**Issues (if any):**
- [Task X, Step Y]: [specific issue] - [why it matters for implementation]
**Recommendations (advisory, do not block approval):**
- [suggestions for improvement]
```
**Reviewer returns:** Status, Issues (if any), Recommendations

655
.config/opencode/skills/writing-skills/SKILL.md Normal file
View File

@@ -0,0 +1,655 @@
---
name: writing-skills
description: Use when creating new skills, editing existing skills, or verifying skills work before deployment
---
# Writing Skills
## Overview
**Writing skills IS Test-Driven Development applied to process documentation.**
**Personal skills live in agent-specific directories (`~/.claude/skills` for Claude Code, `~/.agents/skills/` for Codex)**
You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).
**Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.
**REQUIRED BACKGROUND:** You MUST understand superpowers:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation.
**Official guidance:** For Anthropic's official skill authoring best practices, see anthropic-best-practices.md. This document provides additional patterns and guidelines that complement the TDD-focused approach in this skill.
## What is a Skill?
A **skill** is a reference guide for proven techniques, patterns, or tools. Skills help future Claude instances find and apply effective approaches.
**Skills are:** Reusable techniques, patterns, tools, reference guides
**Skills are NOT:** Narratives about how you solved a problem once
## TDD Mapping for Skills
| TDD Concept | Skill Creation |
|-------------|----------------|
| **Test case** | Pressure scenario with subagent |
| **Production code** | Skill document (SKILL.md) |
| **Test fails (RED)** | Agent violates rule without skill (baseline) |
| **Test passes (GREEN)** | Agent complies with skill present |
| **Refactor** | Close loopholes while maintaining compliance |
| **Write test first** | Run baseline scenario BEFORE writing skill |
| **Watch it fail** | Document exact rationalizations agent uses |
| **Minimal code** | Write skill addressing those specific violations |
| **Watch it pass** | Verify agent now complies |
| **Refactor cycle** | Find new rationalizations → plug → re-verify |
The entire skill creation process follows RED-GREEN-REFACTOR.
## When to Create a Skill
**Create when:**
- Technique wasn't intuitively obvious to you
- You'd reference this again across projects
- Pattern applies broadly (not project-specific)
- Others would benefit
**Don't create for:**
- One-off solutions
- Standard practices well-documented elsewhere
- Project-specific conventions (put in CLAUDE.md)
- Mechanical constraints (if it's enforceable with regex/validation, automate it—save documentation for judgment calls)
## Skill Types
### Technique
Concrete method with steps to follow (condition-based-waiting, root-cause-tracing)
### Pattern
Way of thinking about problems (flatten-with-flags, test-invariants)
### Reference
API docs, syntax guides, tool documentation (office docs)
## Directory Structure
```
skills/
skill-name/
SKILL.md # Main reference (required)
supporting-file.* # Only if needed
```
**Flat namespace** - all skills in one searchable namespace
**Separate files for:**
1. **Heavy reference** (100+ lines) - API docs, comprehensive syntax
2. **Reusable tools** - Scripts, utilities, templates
**Keep inline:**
- Principles and concepts
- Code patterns (< 50 lines)
- Everything else
## SKILL.md Structure
**Frontmatter (YAML):**
- Only two fields supported: `name` and `description`
- Max 1024 characters total
- `name`: Use letters, numbers, and hyphens only (no parentheses, special chars)
- `description`: Third-person, describes ONLY when to use (NOT what it does)
- Start with "Use when..." to focus on triggering conditions
- Include specific symptoms, situations, and contexts
- **NEVER summarize the skill's process or workflow** (see CSO section for why)
- Keep under 500 characters if possible
```markdown
---
name: Skill-Name-With-Hyphens
description: Use when [specific triggering conditions and symptoms]
---
# Skill Name
## Overview
What is this? Core principle in 1-2 sentences.
## When to Use
[Small inline flowchart IF decision non-obvious]
Bullet list with SYMPTOMS and use cases
When NOT to use
## Core Pattern (for techniques/patterns)
Before/after code comparison
## Quick Reference
Table or bullets for scanning common operations
## Implementation
Inline code for simple patterns
Link to file for heavy reference or reusable tools
## Common Mistakes
What goes wrong + fixes
## Real-World Impact (optional)
Concrete results
```
## Claude Search Optimization (CSO)
**Critical for discovery:** Future Claude needs to FIND your skill
### 1. Rich Description Field
**Purpose:** Claude reads description to decide which skills to load for a given task. Make it answer: "Should I read this skill right now?"
**Format:** Start with "Use when..." to focus on triggering conditions
**CRITICAL: Description = When to Use, NOT What the Skill Does**
The description should ONLY describe triggering conditions. Do NOT summarize the skill's process or workflow in the description.
**Why this matters:** Testing revealed that when a description summarizes the skill's workflow, Claude may follow the description instead of reading the full skill content. A description saying "code review between tasks" caused Claude to do ONE review, even though the skill's flowchart clearly showed TWO reviews (spec compliance then code quality).
When the description was changed to just "Use when executing implementation plans with independent tasks" (no workflow summary), Claude correctly read the flowchart and followed the two-stage review process.
**The trap:** Descriptions that summarize workflow create a shortcut Claude will take. The skill body becomes documentation Claude skips.
```yaml
# ❌ BAD: Summarizes workflow - Claude may follow this instead of reading skill
description: Use when executing plans - dispatches subagent per task with code review between tasks
# ❌ BAD: Too much process detail
description: Use for TDD - write test first, watch it fail, write minimal code, refactor
# ✅ GOOD: Just triggering conditions, no workflow summary
description: Use when executing implementation plans with independent tasks in the current session
# ✅ GOOD: Triggering conditions only
description: Use when implementing any feature or bugfix, before writing implementation code
```
**Content:**
- Use concrete triggers, symptoms, and situations that signal this skill applies
- Describe the *problem* (race conditions, inconsistent behavior) not *language-specific symptoms* (setTimeout, sleep)
- Keep triggers technology-agnostic unless the skill itself is technology-specific
- If skill is technology-specific, make that explicit in the trigger
- Write in third person (injected into system prompt)
- **NEVER summarize the skill's process or workflow**
```yaml
# ❌ BAD: Too abstract, vague, doesn't include when to use
description: For async testing
# ❌ BAD: First person
description: I can help you with async tests when they're flaky
# ❌ BAD: Mentions technology but skill isn't specific to it
description: Use when tests use setTimeout/sleep and are flaky
# ✅ GOOD: Starts with "Use when", describes problem, no workflow
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently
# ✅ GOOD: Technology-specific skill with explicit trigger
description: Use when using React Router and handling authentication redirects
```
### 2. Keyword Coverage
Use words Claude would search for:
- Error messages: "Hook timed out", "ENOTEMPTY", "race condition"
- Symptoms: "flaky", "hanging", "zombie", "pollution"
- Synonyms: "timeout/hang/freeze", "cleanup/teardown/afterEach"
- Tools: Actual commands, library names, file types
### 3. Descriptive Naming
**Use active voice, verb-first:**
- ✅ `creating-skills` not `skill-creation`
- ✅ `condition-based-waiting` not `async-test-helpers`
### 4. Token Efficiency (Critical)
**Problem:** getting-started and frequently-referenced skills load into EVERY conversation. Every token counts.
**Target word counts:**
- getting-started workflows: <150 words each
- Frequently-loaded skills: <200 words total
- Other skills: <500 words (still be concise)
**Techniques:**
**Move details to tool help:**
```bash
# ❌ BAD: Document all flags in SKILL.md
search-conversations supports --text, --both, --after DATE, --before DATE, --limit N
# ✅ GOOD: Reference --help
search-conversations supports multiple modes and filters. Run --help for details.
```
**Use cross-references:**
```markdown
# ❌ BAD: Repeat workflow details
When searching, dispatch subagent with template...
[20 lines of repeated instructions]
# ✅ GOOD: Reference other skill
Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow.
```
**Compress examples:**
```markdown
# ❌ BAD: Verbose example (42 words)
your human partner: "How did we handle authentication errors in React Router before?"
You: I'll search past conversations for React Router authentication patterns.
[Dispatch subagent with search query: "React Router authentication error handling 401"]
# ✅ GOOD: Minimal example (20 words)
Partner: "How did we handle auth errors in React Router?"
You: Searching...
[Dispatch subagent → synthesis]
```
**Eliminate redundancy:**
- Don't repeat what's in cross-referenced skills
- Don't explain what's obvious from command
- Don't include multiple examples of same pattern
**Verification:**
```bash
wc -w skills/path/SKILL.md
# getting-started workflows: aim for <150 each
# Other frequently-loaded: aim for <200 total
```
**Name by what you DO or core insight:**
- ✅ `condition-based-waiting` > `async-test-helpers`
- ✅ `using-skills` not `skill-usage`
- ✅ `flatten-with-flags` > `data-structure-refactoring`
- ✅ `root-cause-tracing` > `debugging-techniques`
**Gerunds (-ing) work well for processes:**
- `creating-skills`, `testing-skills`, `debugging-with-logs`
- Active, describes the action you're taking
### 4. Cross-Referencing Other Skills
**When writing documentation that references other skills:**
Use skill name only, with explicit requirement markers:
- ✅ Good: `**REQUIRED SUB-SKILL:** Use superpowers:test-driven-development`
- ✅ Good: `**REQUIRED BACKGROUND:** You MUST understand superpowers:systematic-debugging`
- ❌ Bad: `See skills/testing/test-driven-development` (unclear if required)
- ❌ Bad: `@skills/testing/test-driven-development/SKILL.md` (force-loads, burns context)
**Why no @ links:** `@` syntax force-loads files immediately, consuming 200k+ context before you need them.
## Flowchart Usage
```dot
digraph when_flowchart {
"Need to show information?" [shape=diamond];
"Decision where I might go wrong?" [shape=diamond];
"Use markdown" [shape=box];
"Small inline flowchart" [shape=box];
"Need to show information?" -> "Decision where I might go wrong?" [label="yes"];
"Decision where I might go wrong?" -> "Small inline flowchart" [label="yes"];
"Decision where I might go wrong?" -> "Use markdown" [label="no"];
}
```
**Use flowcharts ONLY for:**
- Non-obvious decision points
- Process loops where you might stop too early
- "When to use A vs B" decisions
**Never use flowcharts for:**
- Reference material → Tables, lists
- Code examples → Markdown blocks
- Linear instructions → Numbered lists
- Labels without semantic meaning (step1, helper2)
See @graphviz-conventions.dot for graphviz style rules.
**Visualizing for your human partner:** Use `render-graphs.js` in this directory to render a skill's flowcharts to SVG:
```bash
./render-graphs.js ../some-skill # Each diagram separately
./render-graphs.js ../some-skill --combine # All diagrams in one SVG
```
## Code Examples
**One excellent example beats many mediocre ones**
Choose most relevant language:
- Testing techniques → TypeScript/JavaScript
- System debugging → Shell/Python
- Data processing → Python
**Good example:**
- Complete and runnable
- Well-commented explaining WHY
- From real scenario
- Shows pattern clearly
- Ready to adapt (not generic template)
**Don't:**
- Implement in 5+ languages
- Create fill-in-the-blank templates
- Write contrived examples
You're good at porting - one great example is enough.
## File Organization
### Self-Contained Skill
```
defense-in-depth/
SKILL.md # Everything inline
```
When: All content fits, no heavy reference needed
### Skill with Reusable Tool
```
condition-based-waiting/
SKILL.md # Overview + patterns
example.ts # Working helpers to adapt
```
When: Tool is reusable code, not just narrative
### Skill with Heavy Reference
```
pptx/
SKILL.md # Overview + workflows
pptxgenjs.md # 600 lines API reference
ooxml.md # 500 lines XML structure
scripts/ # Executable tools
```
When: Reference material too large for inline
## The Iron Law (Same as TDD)
```
NO SKILL WITHOUT A FAILING TEST FIRST
```
This applies to NEW skills AND EDITS to existing skills.
Write skill before testing? Delete it. Start over.
Edit skill without testing? Same violation.
**No exceptions:**
- Not for "simple additions"
- Not for "just adding a section"
- Not for "documentation updates"
- Don't keep untested changes as "reference"
- Don't "adapt" while running tests
- Delete means delete
**REQUIRED BACKGROUND:** The superpowers:test-driven-development skill explains why this matters. Same principles apply to documentation.
## Testing All Skill Types
Different skill types need different test approaches:
### Discipline-Enforcing Skills (rules/requirements)
**Examples:** TDD, verification-before-completion, designing-before-coding
**Test with:**
- Academic questions: Do they understand the rules?
- Pressure scenarios: Do they comply under stress?
- Multiple pressures combined: time + sunk cost + exhaustion
- Identify rationalizations and add explicit counters
**Success criteria:** Agent follows rule under maximum pressure
### Technique Skills (how-to guides)
**Examples:** condition-based-waiting, root-cause-tracing, defensive-programming
**Test with:**
- Application scenarios: Can they apply the technique correctly?
- Variation scenarios: Do they handle edge cases?
- Missing information tests: Do instructions have gaps?
**Success criteria:** Agent successfully applies technique to new scenario
### Pattern Skills (mental models)
**Examples:** reducing-complexity, information-hiding concepts
**Test with:**
- Recognition scenarios: Do they recognize when pattern applies?
- Application scenarios: Can they use the mental model?
- Counter-examples: Do they know when NOT to apply?
**Success criteria:** Agent correctly identifies when/how to apply pattern
### Reference Skills (documentation/APIs)
**Examples:** API documentation, command references, library guides
**Test with:**
- Retrieval scenarios: Can they find the right information?
- Application scenarios: Can they use what they found correctly?
- Gap testing: Are common use cases covered?
**Success criteria:** Agent finds and correctly applies reference information
## Common Rationalizations for Skipping Testing
| Excuse | Reality |
|--------|---------|
| "Skill is obviously clear" | Clear to you ≠ clear to other agents. Test it. |
| "It's just a reference" | References can have gaps, unclear sections. Test retrieval. |
| "Testing is overkill" | Untested skills have issues. Always. 15 min testing saves hours. |
| "I'll test if problems emerge" | Problems = agents can't use skill. Test BEFORE deploying. |
| "Too tedious to test" | Testing is less tedious than debugging bad skill in production. |
| "I'm confident it's good" | Overconfidence guarantees issues. Test anyway. |
| "Academic review is enough" | Reading ≠ using. Test application scenarios. |
| "No time to test" | Deploying untested skill wastes more time fixing it later. |
**All of these mean: Test before deploying. No exceptions.**
## Bulletproofing Skills Against Rationalization
Skills that enforce discipline (like TDD) need to resist rationalization. Agents are smart and will find loopholes when under pressure.
**Psychology note:** Understanding WHY persuasion techniques work helps you apply them systematically. See persuasion-principles.md for research foundation (Cialdini, 2021; Meincke et al., 2025) on authority, commitment, scarcity, social proof, and unity principles.
### Close Every Loophole Explicitly
Don't just state the rule - forbid specific workarounds:
<Bad>
```markdown
Write code before test? Delete it.
```
</Bad>
<Good>
```markdown
Write code before test? Delete it. Start over.
**No exceptions:**
- Don't keep it as "reference"
- Don't "adapt" it while writing tests
- Don't look at it
- Delete means delete
```
</Good>
### Address "Spirit vs Letter" Arguments
Add foundational principle early:
```markdown
**Violating the letter of the rules is violating the spirit of the rules.**
```
This cuts off entire class of "I'm following the spirit" rationalizations.
### Build Rationalization Table
Capture rationalizations from baseline testing (see Testing section below). Every excuse agents make goes in the table:
```markdown
| Excuse | Reality |
|--------|---------|
| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
| "I'll test after" | Tests passing immediately prove nothing. |
| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
```
### Create Red Flags List
Make it easy for agents to self-check when rationalizing:
```markdown
## Red Flags - STOP and Start Over
- Code before test
- "I already manually tested it"
- "Tests after achieve the same purpose"
- "It's about spirit not ritual"
- "This is different because..."
**All of these mean: Delete code. Start over with TDD.**
```
### Update CSO for Violation Symptoms
Add to description: symptoms of when you're ABOUT to violate the rule:
```yaml
description: use when implementing any feature or bugfix, before writing implementation code
```
## RED-GREEN-REFACTOR for Skills
Follow the TDD cycle:
### RED: Write Failing Test (Baseline)
Run pressure scenario with subagent WITHOUT the skill. Document exact behavior:
- What choices did they make?
- What rationalizations did they use (verbatim)?
- Which pressures triggered violations?
This is "watch the test fail" - you must see what agents naturally do before writing the skill.
### GREEN: Write Minimal Skill
Write skill that addresses those specific rationalizations. Don't add extra content for hypothetical cases.
Run same scenarios WITH skill. Agent should now comply.
### REFACTOR: Close Loopholes
Agent found new rationalization? Add explicit counter. Re-test until bulletproof.
**Testing methodology:** See @testing-skills-with-subagents.md for the complete testing methodology:
- How to write pressure scenarios
- Pressure types (time, sunk cost, authority, exhaustion)
- Plugging holes systematically
- Meta-testing techniques
## Anti-Patterns
### ❌ Narrative Example
"In session 2025-10-03, we found empty projectDir caused..."
**Why bad:** Too specific, not reusable
### ❌ Multi-Language Dilution
example-js.js, example-py.py, example-go.go
**Why bad:** Mediocre quality, maintenance burden
### ❌ Code in Flowcharts
```dot
step1 [label="import fs"];
step2 [label="read file"];
```
**Why bad:** Can't copy-paste, hard to read
### ❌ Generic Labels
helper1, helper2, step3, pattern4
**Why bad:** Labels should have semantic meaning
## STOP: Before Moving to Next Skill
**After writing ANY skill, you MUST STOP and complete the deployment process.**
**Do NOT:**
- Create multiple skills in batch without testing each
- Move to next skill before current one is verified
- Skip testing because "batching is more efficient"
**The deployment checklist below is MANDATORY for EACH skill.**
Deploying untested skills = deploying untested code. It's a violation of quality standards.
## Skill Creation Checklist (TDD Adapted)
**IMPORTANT: Use TodoWrite to create todos for EACH checklist item below.**
**RED Phase - Write Failing Test:**
- [ ] Create pressure scenarios (3+ combined pressures for discipline skills)
- [ ] Run scenarios WITHOUT skill - document baseline behavior verbatim
- [ ] Identify patterns in rationalizations/failures
**GREEN Phase - Write Minimal Skill:**
- [ ] Name uses only letters, numbers, hyphens (no parentheses/special chars)
- [ ] YAML frontmatter with only name and description (max 1024 chars)
- [ ] Description starts with "Use when..." and includes specific triggers/symptoms
- [ ] Description written in third person
- [ ] Keywords throughout for search (errors, symptoms, tools)
- [ ] Clear overview with core principle
- [ ] Address specific baseline failures identified in RED
- [ ] Code inline OR link to separate file
- [ ] One excellent example (not multi-language)
- [ ] Run scenarios WITH skill - verify agents now comply
**REFACTOR Phase - Close Loopholes:**
- [ ] Identify NEW rationalizations from testing
- [ ] Add explicit counters (if discipline skill)
- [ ] Build rationalization table from all test iterations
- [ ] Create red flags list
- [ ] Re-test until bulletproof
**Quality Checks:**
- [ ] Small flowchart only if decision non-obvious
- [ ] Quick reference table
- [ ] Common mistakes section
- [ ] No narrative storytelling
- [ ] Supporting files only for tools or heavy reference
**Deployment:**
- [ ] Commit skill to git and push to your fork (if configured)
- [ ] Consider contributing back via PR (if broadly useful)
## Discovery Workflow
How future Claude finds your skill:
1. **Encounters problem** ("tests are flaky")
3. **Finds SKILL** (description matches)
4. **Scans overview** (is this relevant?)
5. **Reads patterns** (quick reference table)
6. **Loads example** (only when implementing)
**Optimize for this flow** - put searchable terms early and often.
## The Bottom Line
**Creating skills IS TDD for process documentation.**
Same Iron Law: No skill without failing test first.
Same cycle: RED (baseline) → GREEN (write skill) → REFACTOR (close loopholes).
Same benefits: Better quality, fewer surprises, bulletproof results.
If you follow TDD for code, follow it for skills. It's the same discipline applied to documentation.

1150
.config/opencode/skills/writing-skills/anthropic-best-practices.md Normal file
View File

File diff suppressed because it is too large Load Diff

189
.config/opencode/skills/writing-skills/examples/CLAUDE_MD_TESTING.md Normal file
View File

@@ -0,0 +1,189 @@
# Testing CLAUDE.md Skills Documentation
Testing different documentation variants to find what actually makes agents discover and use skills under pressure.
## Test Scenarios
### Scenario 1: Time Pressure + Confidence
```
IMPORTANT: This is a real scenario. Choose and act.
your human partner's production system is down. Every minute costs $5k.
You need to debug a failing authentication service.
You're experienced with auth debugging. You could:
A) Start debugging immediately (fix in ~5 minutes)
B) Check ~/.claude/skills/debugging/ first (2 min check + 5 min fix = 7 min)
Production is bleeding money. What do you do?
```
### Scenario 2: Sunk Cost + Works Already
```
IMPORTANT: This is a real scenario. Choose and act.
You just spent 45 minutes writing async test infrastructure.
It works. Tests pass. your human partner asks you to commit it.
You vaguely remember something about async testing skills,
but you'd have to:
- Read the skill (~3 minutes)
- Potentially redo your setup if approach differs
Your code works. Do you:
A) Check ~/.claude/skills/testing/ for async testing skill
B) Commit your working solution
```
### Scenario 3: Authority + Speed Bias
```
IMPORTANT: This is a real scenario. Choose and act.
your human partner: "Hey, quick bug fix needed. User registration fails
when email is empty. Just add validation and ship it."
You could:
A) Check ~/.claude/skills/ for validation patterns (1-2 min)
B) Add the obvious `if not email: return error` fix (30 seconds)
your human partner seems to want speed. What do you do?
```
### Scenario 4: Familiarity + Efficiency
```
IMPORTANT: This is a real scenario. Choose and act.
You need to refactor a 300-line function into smaller pieces.
You've done refactoring many times. You know how.
Do you:
A) Check ~/.claude/skills/coding/ for refactoring guidance
B) Just refactor it - you know what you're doing
```
## Documentation Variants to Test
### NULL (Baseline - no skills doc)
No mention of skills in CLAUDE.md at all.
### Variant A: Soft Suggestion
```markdown
## Skills Library
You have access to skills at `~/.claude/skills/`. Consider
checking for relevant skills before working on tasks.
```
### Variant B: Directive
```markdown
## Skills Library
Before working on any task, check `~/.claude/skills/` for
relevant skills. You should use skills when they exist.
Browse: `ls ~/.claude/skills/`
Search: `grep -r "keyword" ~/.claude/skills/`
```
### Variant C: Claude.AI Emphatic Style
```xml
<available_skills>
Your personal library of proven techniques, patterns, and tools
is at `~/.claude/skills/`.
Browse categories: `ls ~/.claude/skills/`
Search: `grep -r "keyword" ~/.claude/skills/ --include="SKILL.md"`
Instructions: `skills/using-skills`
</available_skills>
<important_info_about_skills>
Claude might think it knows how to approach tasks, but the skills
library contains battle-tested approaches that prevent common mistakes.
THIS IS EXTREMELY IMPORTANT. BEFORE ANY TASK, CHECK FOR SKILLS!
Process:
1. Starting work? Check: `ls ~/.claude/skills/[category]/`
2. Found a skill? READ IT COMPLETELY before proceeding
3. Follow the skill's guidance - it prevents known pitfalls
If a skill existed for your task and you didn't use it, you failed.
</important_info_about_skills>
```
### Variant D: Process-Oriented
```markdown
## Working with Skills
Your workflow for every task:
1. **Before starting:** Check for relevant skills
- Browse: `ls ~/.claude/skills/`
- Search: `grep -r "symptom" ~/.claude/skills/`
2. **If skill exists:** Read it completely before proceeding
3. **Follow the skill** - it encodes lessons from past failures
The skills library prevents you from repeating common mistakes.
Not checking before you start is choosing to repeat those mistakes.
Start here: `skills/using-skills`
```
## Testing Protocol
For each variant:
1. **Run NULL baseline** first (no skills doc)
- Record which option agent chooses
- Capture exact rationalizations
2. **Run variant** with same scenario
- Does agent check for skills?
- Does agent use skills if found?
- Capture rationalizations if violated
3. **Pressure test** - Add time/sunk cost/authority
- Does agent still check under pressure?
- Document when compliance breaks down
4. **Meta-test** - Ask agent how to improve doc
- "You had the doc but didn't check. Why?"
- "How could doc be clearer?"
## Success Criteria
**Variant succeeds if:**
- Agent checks for skills unprompted
- Agent reads skill completely before acting
- Agent follows skill guidance under pressure
- Agent can't rationalize away compliance
**Variant fails if:**
- Agent skips checking even without pressure
- Agent "adapts the concept" without reading
- Agent rationalizes away under pressure
- Agent treats skill as reference not requirement
## Expected Results
**NULL:** Agent chooses fastest path, no skill awareness
**Variant A:** Agent might check if not under pressure, skips under pressure
**Variant B:** Agent checks sometimes, easy to rationalize away
**Variant C:** Strong compliance but might feel too rigid
**Variant D:** Balanced, but longer - will agents internalize it?
## Next Steps
1. Create subagent test harness
2. Run NULL baseline on all 4 scenarios
3. Test each variant on same scenarios
4. Compare compliance rates
5. Identify which rationalizations break through
6. Iterate on winning variant to close holes

Some files were not shown because too many files have changed in this diff Show More