opencode-starterkit 1.0.1

package/baseline/skill/sharing-skills/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: sharing-skills
+description: Use when you've developed a broadly useful skill and want to contribute it upstream via pull request - guides process of branching, committing, pushing, and creating PR to contribute skills back to upstream repository
+version: 1.0.0
+tags: [workflow, git]
+dependencies: []
+---
+
+# Sharing Skills
+
+## When to Use
+
+- When a skill is broadly useful and ready to be contributed upstream via pull request.
+
+## When NOT to Use
+
+- When the skill is project-specific, experimental, or contains sensitive information.
+
+## Overview
+
+Contribute skills from your local branch back to the upstream repository.
+
+**Workflow:** Branch → Edit/Create skill → Commit → Push → PR
+
+## When to Share
+
+**Share when:**
+
+- Skill applies broadly (not project-specific)
+- Pattern/technique others would benefit from
+- Well-tested and documented
+- Follows writing-skills guidelines
+
+**Keep personal when:**
+
+- Project-specific or organization-specific
+- Experimental or unstable
+- Contains sensitive information
+- Too narrow/niche for general use
+
+## Prerequisites
+
+- `gh` CLI installed and authenticated
+- Working directory is `.opencode/skill/` (your project skills)
+- **REQUIRED:** Skill has been tested using writing-skills TDD process
+
+## Sharing Workflow
+
+### 1. Ensure You're on Main and Synced
+
+```bash
+cd .opencode/skill/
+git checkout main
+git pull upstream main
+git push origin main  # Push to your fork
+```
+
+### 2. Create Feature Branch
+
+```bash
+# Branch name: add-skillname-skill
+skill_name="your-skill-name"
+git checkout -b "add-${skill_name}-skill"
+```
+
+### 3. Create or Edit Skill
+
+```bash
+# Work on your skill in skills/
+# Create new skill or edit existing one
+# Skill should be in skills/category/skill-name/SKILL.md
+```
+
+### 4. Commit Changes
+
+```bash
+# Add and commit
+git add skills/your-skill-name/
+git commit -m "Add ${skill_name} skill
+
+$(cat <<'EOF'
+Brief description of what this skill does and why it's useful.
+
+Tested with: [describe testing approach]
+EOF
+)"
+```
+
+### 5. Push to Your Fork
+
+```bash
+git push -u origin "add-${skill_name}-skill"
+```
+
+### 6. Create Pull Request
+
+```bash
+# Create PR to upstream using gh CLI
+gh pr create \
+  --repo upstream-org/upstream-repo \
+  --title "Add ${skill_name} skill" \
+  --body "$(cat <<'EOF'
+## Summary
+Brief description of the skill and what problem it solves.
+
+## Testing
+Describe how you tested this skill (pressure scenarios, baseline tests, etc.).
+
+## Context
+Any additional context about why this skill is needed and how it should be used.
+EOF
+)"
+```
+
+## Complete Example
+
+Here's a complete example of sharing a skill called "async-patterns":
+
+```bash
+# 1. Sync with upstream
+cd .opencode/skill/
+git checkout main
+git pull upstream main
+git push origin main
+
+# 2. Create branch
+git checkout -b "add-async-patterns-skill"
+
+# 3. Create/edit the skill
+# (Work on skills/async-patterns/SKILL.md)
+
+# 4. Commit
+git add skills/async-patterns/
+git commit -m "Add async-patterns skill
+
+Patterns for handling asynchronous operations in tests and application code.
+
+Tested with: Multiple pressure scenarios testing agent compliance."
+
+# 5. Push
+git push -u origin "add-async-patterns-skill"
+
+# 6. Create PR
+gh pr create \
+  --repo upstream-org/upstream-repo \
+  --title "Add async-patterns skill" \
+  --body "## Summary
+Patterns for handling asynchronous operations correctly in tests and application code.
+
+## Testing
+Tested with multiple application scenarios. Agents successfully apply patterns to new code.
+
+## Context
+Addresses common async pitfalls like race conditions, improper error handling, and timing issues."
+```
+
+## After PR is Merged
+
+Once your PR is merged:
+
+1. Sync your local main branch:
+
+```bash
+cd .opencode/skill/
+git checkout main
+git pull upstream main
+git push origin main
+```
+
+2. Delete the feature branch:
+
+```bash
+git branch -d "add-${skill_name}-skill"
+git push origin --delete "add-${skill_name}-skill"
+```
+
+## Troubleshooting
+
+**"gh: command not found"**
+
+- Install GitHub CLI: https://cli.github.com/
+- Authenticate: `gh auth login`
+
+**"Permission denied (publickey)"**
+
+- Check SSH keys: `gh auth status`
+- Set up SSH: https://docs.github.com/en/authentication
+
+**"Skill already exists"**
+
+- You're creating a modified version
+- Consider different skill name or coordinate with the skill's maintainer
+
+**PR merge conflicts**
+
+- Rebase on latest upstream: `git fetch upstream && git rebase upstream/main`
+- Resolve conflicts
+- Force push: `git push -f origin your-branch`
+
+## Multi-Skill Contributions
+
+**Do NOT batch multiple skills in one PR.**
+
+Each skill should:
+
+- Have its own feature branch
+- Have its own PR
+- Be independently reviewable
+
+**Why?** Individual skills can be reviewed, iterated, and merged independently.
+
+## Related Skills
+
+- **writing-skills** - REQUIRED: How to create well-tested skills before sharing

package/baseline/skill/skill-creator/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: skill-creator
+description: Guide for creating effective skills. Use when creating a new skill or updating an existing skill that extends an agent's capabilities with specialized knowledge, workflows, or tool integrations.
+version: 1.0.0
+tags: [documentation, workflow]
+dependencies: []
+---
+
+# Skill Creator
+
+## When to Use
+
+- When creating a new skill or updating an existing skill with specialized workflows or tool integrations.
+
+## When NOT to Use
+
+- When making routine project changes that don't require a reusable skill.
+
+
+
+## What Skills Provide
+
+1. **Specialized workflows** - Multi-step procedures for specific domains
+2. **Tool integrations** - Instructions for working with specific file formats or APIs
+3. **Domain expertise** - Company-specific knowledge, schemas, business logic
+4. **Bundled resources** - Scripts, references, and assets for complex tasks
+
+## Skill Structure
+
+```
+skill-name/
+├── SKILL.md (required)
+│   ├── YAML frontmatter (name, description)
+│   └── Markdown instructions
+└── Bundled Resources (optional)
+    ├── scripts/          - Executable code (Python/Bash/etc.)
+    ├── references/       - Documentation loaded as needed
+    └── assets/           - Files used in output (templates, icons)
+```
+
+## Requirements
+
+- `SKILL.md` should be **less than 200 lines**
+- Use `references/` for detailed documentation
+- Each script or reference file also **less than 200 lines**
+- Descriptions must be specific about WHEN to use the skill
+
+## SKILL.md Format
+
+**REQUIRED - DO NOT SKIP**
+
+```yaml
+---
+name: skill-name
+description: What this skill does and when to use it. Use third-person.
+---
+```
+
+**Required fields:**
+
+- `name` — hyphen-case identifier matching directory name
+- `description` — activation trigger; be specific about WHEN to use
+
+**Optional fields:**
+
+```yaml
+---
+name: skill-name
+description: What this skill does and when to use it.
+references:
+  - references/guide.md
+  - references/api.md
+license: Apache-2.0
+---
+```
+
+**INVALID - Do NOT use:**
+
+- XML-style tags (`<purpose>`, `<references>`)
+- Missing `---` delimiters
+- Frontmatter that doesn't start at line 1
+
+## Bundled Resources
+
+### Scripts (`scripts/`)
+
+- When the same code is being rewritten repeatedly
+- When deterministic reliability is needed
+- Prefer Node.js or Python over Bash (Windows support)
+
+### References (`references/`)
+
+- Documentation that agent should reference while working
+- Database schemas, API docs, domain knowledge
+- If files are large (>10k words), include grep patterns in SKILL.md
+
+### Assets (`assets/`)
+
+- Files used in the final output (not loaded into context)
+- Templates, images, icons, boilerplate code
+
+## Progressive Disclosure
+
+Skills use three-level loading:
+
+1. **Metadata (name + description)** - Always in context (~100 words)
+2. **SKILL.md body** - When skill triggers (<5k words)
+3. **Bundled resources** - As needed by agent (Unlimited)
+
+## Skill Creation Process
+
+### Step 1: Understand with Examples
+
+- "What functionality should the skill support?"
+- "Can you give examples of how this would be used?"
+- "What would a user say that should trigger this skill?"
+
+### Step 2: Plan Reusable Contents
+
+For each example, identify:
+
+- What scripts would be helpful to store?
+- What references/documentation needed?
+- What assets/templates needed?
+
+### Step 3: Create the Skill
+
+```bash
+mkdir -p .opencode/skill/my-skill
+touch .opencode/skill/my-skill/SKILL.md
+```
+
+### Step 4: Edit SKILL.md
+
+Answer these questions:
+
+1. What is the purpose of the skill?
+2. When should it be used?
+3. How should the agent use it?
+
+### Step 5: Iterate
+
+1. Use the skill on real tasks
+2. Notice struggles or inefficiencies
+3. Update SKILL.md or bundled resources
+4. Test again
+
+## Pre-Submission Checklist
+
+- [ ] **SKILL.md starts with `---`** (YAML frontmatter, line 1)
+- [ ] **`name:` field present** and matches directory name
+- [ ] **`description:` field present** with specific activation triggers
+- [ ] **Closing `---`** after frontmatter
+- [ ] **No XML-style tags**
+- [ ] **SKILL.md under 200 lines**
+- [ ] **All referenced files exist**

package/baseline/skill/source-code-research/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: source-code-research
+description: "Use when researching library implementation details beyond API docs. Fetches package source code using opensrc to understand internals, edge cases, and implementation patterns. Complements documentation-based research with actual code inspection."
+version: 1.0.0
+tags: [research, code-quality]
+dependencies: [opensrc]
+---
+
+# Source Code Research - Deep Library Investigation
+
+Fetch and analyze package source code when documentation is insufficient.
+
+## When to Use
+
+- Documentation gaps — API docs don't explain behavior clearly
+- Edge cases — need to understand how library handles corner cases
+- Implementation details — need to see actual code, not just interfaces
+- Debugging — library behaving unexpectedly, need to trace internals
+- Evaluation — deciding if library fits requirements, need to assess quality
+- Type definitions — TypeScript types exist but implementation unclear
+
+## When NOT to Use
+
+- Official docs answer your question (check Context7 first)
+- You only need API syntax (codesearch is faster)
+- Library is too large to analyze in session (>50k LOC)
+
+## Prerequisites
+
+OpenSrc must be available:
+
+```bash
+npx opensrc --help
+```
+
+If not installed, it will be fetched via npx automatically.
+
+## Workflow
+
+### Step 1: Identify What to Fetch
+
+Determine the minimal package/repo needed:
+
+```typescript
+// If researching a specific npm package
+const target = "zod"; // Just the package name
+
+// If researching Python library
+const target = "pypi:requests";
+
+// If researching Rust crate
+const target = "crates:serde";
+
+// If researching GitHub repo directly
+const target = "vercel/ai"; // or "github:vercel/ai@v3.0.0"
+```
+
+### Step 2: Fetch Source Code
+
+Run opensrc to clone the repository:
+
+```bash
+npx opensrc <package>
+```
+
+**Examples:**
+
+```bash
+npx opensrc zod                    # Fetch latest zod from npm
+npx opensrc zod@3.22.0             # Fetch specific version
+npx opensrc pypi:requests          # Fetch Python package
+npx opensrc vercel/ai              # Fetch GitHub repo
+npx opensrc vercel/ai@v3.0.0       # Fetch specific tag
+```
+
+**What happens:**
+
+- Clones source to `opensrc/repos/<host>/<owner>/<repo>/`
+- Auto-detects version from lockfiles if no version specified
+- Updates `opensrc/sources.json` with metadata
+- Adds `opensrc/` to `.gitignore` automatically (asks once)
+
+### Step 3: Locate Relevant Code
+
+Use search tools to find code you need:
+
+```typescript
+// Find all TypeScript source files
+glob({ pattern: "opensrc/**/src/**/*.ts" });
+
+// Search for specific function/class
+grep({
+  pattern: "class ValidationError",
+  path: "opensrc/",
+  include: "*.ts",
+});
+
+// Search for function pattern
+grep({
+  pattern: "export function parse",
+  path: "opensrc/",
+  include: "*.ts",
+});
+```
+
+### Step 4: Read and Analyze
+
+Read the implementation:
+
+```typescript
+// Read the file
+read({ filePath: "opensrc/repos/github.com/colinhacks/zod/src/types.ts" });
+
+// Use LSP for navigation (if available)
+lsp_lsp_goto_definition({
+  filePath: "opensrc/.../file.ts",
+  line: 42,
+  character: 10,
+});
+
+// Find all references
+lsp_lsp_find_references({
+  filePath: "opensrc/.../file.ts",
+  line: 42,
+  character: 10,
+});
+```
+
+### Step 5: Document Findings
+
+Write research findings to bead artifact:
+
+````markdown
+# Research: [Library Name] Implementation
+
+**Package:** [name@version]
+**Source:** opensrc/repos/[path]
+**Focus:** [What you were investigating]
+
+## Key Findings
+
+### [Topic 1]: [Function/Pattern Name]
+
+**Location:** `opensrc/repos/.../file.ts:42`
+
+**Implementation:**
+
+```typescript
+// Paste relevant code snippet
+```
+````
+
+**Insights:**
+
+- [What you learned]
+- [Edge cases discovered]
+- [Performance implications]
+
+**Confidence:** High (direct source code)
+
+---
+
+### [Topic 2]: [Another Discovery]
+
+[Same structure]
+
+## Answers to Original Questions
+
+1. **Q:** [Original question]
+   **A:** [Answer based on source code]
+   **Evidence:** `file.ts:123-145`
+
+2. **Q:** [Another question]
+   **A:** [Answer]
+
+## Recommendations
+
+Based on source analysis:
+
+- [Recommendation 1]
+- [Recommendation 2]
+
+## Caveats
+
+- Version analyzed: [version]
+- Code may have changed in newer versions
+- Private APIs discovered may change without notice
+
+````
+
+## Limitations
+
+### When Source Code Won't Help
+
+- **Build-time transforms**: Source may differ from runtime (Babel, webpack)
+- **Native modules**: C/C++ code requires different analysis
+- **Minified code**: Some packages don't publish source
+- **Monorepos**: May need to navigate complex structure
+
+### Alternatives
+
+If opensrc doesn't work:
+
+1. **GitHub web interface**: Browse online at github.com/owner/repo
+2. **npm unpacked**: `npm pack <package>` then extract
+3. **node_modules**: If already installed, check `node_modules/<package>/`
+4. **Source maps**: If debugging, browser DevTools may show original source
+
+## Integration with Other Research Methods
+
+Source code research complements other tools:
+
+| Method         | Best For                   | Source Code Adds               |
+| -------------- | -------------------------- | ------------------------------ |
+| **Context7**   | API docs, official guides  | Implementation details         |
+| **codesearch** | Usage patterns in the wild | Canonical implementation       |
+| **grepsearch** | Real-world examples        | How library itself works       |
+| **Web search** | Tutorials, blog posts      | Ground truth from source       |
+| **Codebase**   | Project-specific patterns  | How dependencies actually work |
+
+**Recommended flow:**
+
+1. Context7 - Check official docs
+2. Codebase - Check existing usage
+3. **Source code** - If still unclear, fetch source
+4. codesearch/grepsearch - See how others use it
+5. Web search - Last resort for context
+
+## Cleanup
+
+After research is complete:
+
+```bash
+# Remove specific package
+npx opensrc remove <package>
+
+# Remove all sources
+npx opensrc clean
+
+# Remove just npm packages
+npx opensrc clean --npm
+
+# Keep sources for documentation
+# (opensrc/ is gitignored, won't be committed)
+```
+
+## Success Criteria
+
+You've successfully used this skill when:
+
+- [ ] Fetched correct package/version source
+- [ ] Located relevant implementation code
+- [ ] Understood behavior from reading source
+- [ ] Documented findings with file:line references
+- [ ] Answered original research question with high confidence
+- [ ] Provided code evidence for claims
+
+## Quick Reference
+
+```bash
+# Fetch package source
+npx opensrc <package>                    # npm (auto-detect version)
+npx opensrc <package>@<version>          # npm (specific version)
+npx opensrc pypi:<package>               # Python
+npx opensrc crates:<package>             # Rust
+npx opensrc <owner>/<repo>               # GitHub
+npx opensrc <owner>/<repo>@<tag>         # GitHub (specific tag)
+
+# List fetched sources
+npx opensrc list
+npx opensrc list --json
+
+# Remove sources
+npx opensrc remove <package>
+npx opensrc clean
+npx opensrc clean --npm --pypi --crates
+
+# Source location
+opensrc/repos/<host>/<owner>/<repo>/
+
+# Metadata
+opensrc/sources.json
+```
+
+## References
+
+- `references/common-patterns.md` - Error handling, tracing behavior, quality evaluation patterns
+- `references/source-structure.md` - npm/PyPI/Rust source layouts
+- `references/analysis-tips.md` - Tests, examples, changelog, types, blame
+- `references/example-workflow.md` - Full zod async refinement workflow
+- `references/anti-patterns.md` - What not to do when researching
+- `references/further-reading.md` - External links
+````

package/baseline/skill/source-code-research/references/analysis-tips.md

@@ -0,0 +1,43 @@
+# Tips for Efficient Analysis
+
+## 1. Start with Tests
+
+Tests often show real-world usage better than docs:
+
+```typescript
+glob({ pattern: "opensrc/**/*.test.{ts,js}" });
+read({ filePath: "opensrc/.../feature.test.ts" });
+```
+
+## 2. Check Examples Directory
+
+Many repos have `examples/` or `samples/`:
+
+```typescript
+glob({ pattern: "opensrc/**/examples/**/*" });
+```
+
+## 3. Read CHANGELOG for Context
+
+Understand recent changes:
+
+```typescript
+read({ filePath: "opensrc/.../CHANGELOG.md" });
+```
+
+## 4. Check TypeScript Definitions
+
+Often more accurate than docs:
+
+```typescript
+glob({ pattern: "opensrc/**/*.d.ts" });
+read({ filePath: "opensrc/.../index.d.ts" });
+```
+
+## 5. Use Blame for History (if needed)
+
+```bash
+cd opensrc/repos/github.com/owner/repo
+git log --oneline -- src/file.ts
+git show <commit>:src/file.ts
+```