opencodekit 0.18.0 → 0.18.2

package/dist/template/.opencode/skill/source-code-research/SKILL.md

@@ -1,29 +1,25 @@
 ---
 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"
-license: MIT
+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 This Skill
+## When to Use
 
-Use source code research when:
+- 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
 
-- **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
-
-**Don't use when:**
+## When NOT to Use
 
 - Official docs answer your question (check Context7 first)
 - You only need API syntax (codesearch is faster)
@@ -192,154 +188,6 @@ Based on source analysis:
 
 ````
 
-## Common Patterns
-
-### Pattern 1: Understanding Error Handling
-
-```typescript
-// 1. Fetch package
-// bash: npx opensrc zod
-
-// 2. Find error classes
-grep({ pattern: "class.*Error", path: "opensrc/", include: "*.ts" });
-
-// 3. Read error implementation
-read({ filePath: "opensrc/repos/.../errors.ts" });
-
-// 4. Find where errors are thrown
-grep({ pattern: "throw new", path: "opensrc/", include: "*.ts" });
-````
-
-### Pattern 2: Tracing Function Behavior
-
-```typescript
-// 1. Fetch source
-// bash: npx opensrc react-hook-form
-
-// 2. Find function definition
-grep({
-  pattern: "export function useForm",
-  path: "opensrc/",
-  include: "*.ts",
-});
-
-// 3. Read implementation
-read({ filePath: "opensrc/.../useForm.ts" });
-
-// 4. Find dependencies
-grep({ pattern: "import.*from", path: "opensrc/.../useForm.ts" });
-```
-
-### Pattern 3: Evaluating Library Quality
-
-```typescript
-// 1. Fetch source
-// bash: npx opensrc candidate-library
-
-// 2. Check test coverage
-glob({ pattern: "opensrc/**/*.test.ts" });
-glob({ pattern: "opensrc/**/*.spec.ts" });
-
-// 3. Read tests for usage patterns
-read({ filePath: "opensrc/.../feature.test.ts" });
-
-// 4. Check for TypeScript usage
-glob({ pattern: "opensrc/**/tsconfig.json" });
-
-// 5. Review package.json for dependencies
-read({ filePath: "opensrc/.../package.json" });
-```
-
-## Source Structure Guide
-
-### npm Packages
-
-```
-opensrc/
-└── repos/
-    └── github.com/              # npm packages resolve to GitHub
-        └── owner/
-            └── repo/
-                ├── src/         # Source code (usually)
-                ├── dist/        # Built output (ignore)
-                ├── test/        # Tests (useful for examples)
-                ├── package.json # Dependencies, scripts
-                └── README.md    # Often has examples
-```
-
-### Python Packages (PyPI)
-
-```
-opensrc/
-└── repos/
-    └── github.com/              # Most PyPI packages on GitHub
-        └── owner/
-            └── repo/
-                ├── src/         # or package_name/
-                ├── tests/       # Python tests
-                ├── setup.py     # Package config
-                └── pyproject.toml
-```
-
-### Rust Crates
-
-```
-opensrc/
-└── repos/
-    └── github.com/
-        └── owner/
-            └── repo/
-                ├── src/
-                │   └── lib.rs   # Main library file
-                ├── tests/
-                ├── Cargo.toml   # Dependencies
-                └── examples/    # Usage examples
-```
-
-## 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
-```
-
 ## Limitations
 
 ### When Source Code Won't Help
@@ -396,67 +244,6 @@ npx opensrc clean --npm
 # (opensrc/ is gitignored, won't be committed)
 ```
 
-## Example: Complete Workflow
-
-**Scenario:** Need to understand how zod handles async refinements.
-
-```bash
-# 1. Fetch source
-npx opensrc zod
-```
-
-```typescript
-// 2. Find refinement code
-grep({
-  pattern: "refine.*async",
-  path: "opensrc/",
-  include: "*.ts",
-});
-
-// 3. Locate implementation
-ast_grep({
-  pattern: "refine($$$) { $$$ }",
-  path: "opensrc/repos/github.com/colinhacks/zod/",
-});
-
-// 4. Read the implementation
-read({
-  filePath: "opensrc/repos/github.com/colinhacks/zod/src/types.ts",
-  offset: 500,
-  limit: 100,
-});
-
-// 5. Check tests for usage examples
-glob({
-  pattern: "opensrc/**/zod/**/*.test.ts",
-});
-
-read({
-  filePath: "opensrc/repos/.../async.test.ts",
-});
-
-// 6. Document findings
-write({
-  filePath: ".beads/artifacts/br-xxx/research.md",
-  content: `# Zod Async Refinements
-
-**Finding:** Async refinements use \`parseAsync()\` not \`parse()\`
-
-**Evidence:** \`src/types.ts:842-856\`
-
-Async refinements return Promise<Output> and require:
-- Use \`.parseAsync()\` method
-- Refinement function must return Promise<boolean>
-- Errors handled via Promise rejection
-
-**Code snippet:**
-[paste relevant code]
-
-**Recommendation:** Use \`.refine(async (val) => {...})\` with \`.parseAsync()\`
-`,
-});
-```
-
 ## Success Criteria
 
 You've successfully used this skill when:
@@ -468,43 +255,6 @@ You've successfully used this skill when:
 - [ ] Answered original research question with high confidence
 - [ ] Provided code evidence for claims
 
-## Anti-Patterns
-
-### ❌ Don't: Fetch Entire Ecosystem
-
-```bash
-# Bad: Fetching everything
-npx opensrc react
-npx opensrc react-dom
-npx opensrc react-router
-npx opensrc react-query
-# ... (too much code)
-```
-
-**Do:** Fetch only what you need to answer specific question.
-
-### ❌ Don't: Read Random Files
-
-```typescript
-// Bad: Reading without purpose
-read({ filePath: "opensrc/.../index.ts" });
-read({ filePath: "opensrc/.../utils.ts" });
-read({ filePath: "opensrc/.../helpers.ts" });
-// ... (unfocused exploration)
-```
-
-**Do:** Use grep to find relevant code first, then read.
-
-### ❌ Don't: Ignore Version Mismatch
-
-```bash
-# Bad: Fetching latest when project uses old version
-npx opensrc zod  # Fetches 3.23.x
-# But project uses zod@3.20.0 (different behavior)
-```
-
-**Do:** Specify version matching your lockfile, or let opensrc auto-detect.
-
 ## Quick Reference
 
 ```bash
@@ -532,8 +282,12 @@ opensrc/repos/<host>/<owner>/<repo>/
 opensrc/sources.json
 ```
 
-## Further Reading
+## References
 
-- OpenSrc Docs: https://github.com/vercel-labs/opensrc
-- When to read source vs docs: https://danluu.com/read-code/
-- Code reading techniques: https://www.codeproject.com/Articles/10/Code-Reading
+- `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/dist/template/.opencode/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
+```

package/dist/template/.opencode/skill/source-code-research/references/anti-patterns.md

@@ -0,0 +1,36 @@
+# Anti-Patterns
+
+## ❌ Don't: Fetch Entire Ecosystem
+
+```bash
+# Bad: Fetching everything
+npx opensrc react
+npx opensrc react-dom
+npx opensrc react-router
+npx opensrc react-query
+# ... (too much code)
+```
+
+**Do:** Fetch only what you need to answer specific question.
+
+## ❌ Don't: Read Random Files
+
+```typescript
+// Bad: Reading without purpose
+read({ filePath: "opensrc/.../index.ts" });
+read({ filePath: "opensrc/.../utils.ts" });
+read({ filePath: "opensrc/.../helpers.ts" });
+// ... (unfocused exploration)
+```
+
+**Do:** Use grep to find relevant code first, then read.
+
+## ❌ Don't: Ignore Version Mismatch
+
+```bash
+# Bad: Fetching latest when project uses old version
+npx opensrc zod  # Fetches 3.23.x
+# But project uses zod@3.20.0 (different behavior)
+```
+
+**Do:** Specify version matching your lockfile, or let opensrc auto-detect.

package/dist/template/.opencode/skill/source-code-research/references/common-patterns.md

@@ -0,0 +1,57 @@
+# Common Patterns
+
+## Pattern 1: Understanding Error Handling
+
+```typescript
+// 1. Fetch package
+// bash: npx opensrc zod
+
+// 2. Find error classes
+grep({ pattern: "class.*Error", path: "opensrc/", include: "*.ts" });
+
+// 3. Read error implementation
+read({ filePath: "opensrc/repos/.../errors.ts" });
+
+// 4. Find where errors are thrown
+grep({ pattern: "throw new", path: "opensrc/", include: "*.ts" });
+```
+
+## Pattern 2: Tracing Function Behavior
+
+```typescript
+// 1. Fetch source
+// bash: npx opensrc react-hook-form
+
+// 2. Find function definition
+grep({
+  pattern: "export function useForm",
+  path: "opensrc/",
+  include: "*.ts",
+});
+
+// 3. Read implementation
+read({ filePath: "opensrc/.../useForm.ts" });
+
+// 4. Find dependencies
+grep({ pattern: "import.*from", path: "opensrc/.../useForm.ts" });
+```
+
+## Pattern 3: Evaluating Library Quality
+
+```typescript
+// 1. Fetch source
+// bash: npx opensrc candidate-library
+
+// 2. Check test coverage
+glob({ pattern: "opensrc/**/*.test.ts" });
+glob({ pattern: "opensrc/**/*.spec.ts" });
+
+// 3. Read tests for usage patterns
+read({ filePath: "opensrc/.../feature.test.ts" });
+
+// 4. Check for TypeScript usage
+glob({ pattern: "opensrc/**/tsconfig.json" });
+
+// 5. Review package.json for dependencies
+read({ filePath: "opensrc/.../package.json" });
+```

package/dist/template/.opencode/skill/source-code-research/references/example-workflow.md

@@ -0,0 +1,60 @@
+# Example: Complete Workflow
+
+**Scenario:** Need to understand how zod handles async refinements.
+
+```bash
+# 1. Fetch source
+npx opensrc zod
+```
+
+```typescript
+// 2. Find refinement code
+grep({
+  pattern: "refine.*async",
+  path: "opensrc/",
+  include: "*.ts",
+});
+
+// 3. Locate implementation
+ast_grep({
+  pattern: "refine($$$) { $$$ }",
+  path: "opensrc/repos/github.com/colinhacks/zod/",
+});
+
+// 4. Read the implementation
+read({
+  filePath: "opensrc/repos/github.com/colinhacks/zod/src/types.ts",
+  offset: 500,
+  limit: 100,
+});
+
+// 5. Check tests for usage examples
+glob({
+  pattern: "opensrc/**/zod/**/*.test.ts",
+});
+
+read({
+  filePath: "opensrc/repos/.../async.test.ts",
+});
+
+// 6. Document findings
+write({
+  filePath: ".beads/artifacts/br-xxx/research.md",
+  content: `# Zod Async Refinements
+
+**Finding:** Async refinements use \`parseAsync()\` not \`parse()\`
+
+**Evidence:** \`src/types.ts:842-856\`
+
+Async refinements return Promise<Output> and require:
+- Use \`.parseAsync()\` method
+- Refinement function must return Promise<boolean>
+- Errors handled via Promise rejection
+
+**Code snippet:**
+[paste relevant code]
+
+**Recommendation:** Use \`.refine(async (val) => {...})\` with \`.parseAsync()\`
+`,
+});
+```

package/dist/template/.opencode/skill/source-code-research/references/further-reading.md

@@ -0,0 +1,5 @@
+# Further Reading
+
+- OpenSrc Docs: https://github.com/vercel-labs/opensrc
+- When to read source vs docs: https://danluu.com/read-code/
+- Code reading techniques: https://www.codeproject.com/Articles/10/Code-Reading

package/dist/template/.opencode/skill/source-code-research/references/source-structure.md

@@ -0,0 +1,45 @@
+# Source Structure Guide
+
+## npm Packages
+
+```
+opensrc/
+└── repos/
+    └── github.com/              # npm packages resolve to GitHub
+        └── owner/
+            └── repo/
+                ├── src/         # Source code (usually)
+                ├── dist/        # Built output (ignore)
+                ├── test/        # Tests (useful for examples)
+                ├── package.json # Dependencies, scripts
+                └── README.md    # Often has examples
+```
+
+## Python Packages (PyPI)
+
+```
+opensrc/
+└── repos/
+    └── github.com/              # Most PyPI packages on GitHub
+        └── owner/
+            └── repo/
+                ├── src/         # or package_name/
+                ├── tests/       # Python tests
+                ├── setup.py     # Package config
+                └── pyproject.toml
+```
+
+## Rust Crates
+
+```
+opensrc/
+└── repos/
+    └── github.com/
+        └── owner/
+            └── repo/
+                ├── src/
+                │   └── lib.rs   # Main library file
+                ├── tests/
+                ├── Cargo.toml   # Dependencies
+                └── examples/    # Usage examples
+```

package/dist/template/.opencode/skill/stitch/SKILL.md

@@ -1,11 +1,21 @@
 ---
 name: stitch
 description: Google Stitch MCP for AI-powered UI design. Extract design context, generate code from designs, and create screens from descriptions. Use when working with Stitch designs and UI generation.
+version: 1.0.0
+tags: [design, mcp, ui]
+dependencies: []
 ---
 
 # Google Stitch MCP
 
-Access Google Stitch UI designs directly through the Model Context Protocol.
+## When to Use
+
+- When you need to generate or inspect Google Stitch UI designs via MCP.
+
+## When NOT to Use
+
+- When you don't have Stitch access or don't need Stitch-generated UI.
+
 
 ## Overview
 

package/dist/template/.opencode/skill/structured-edit/SKILL.md

@@ -1,10 +1,23 @@
 ---
 name: structured-edit
 description: Use when editing files to reduce str_replace failures - combines LSP location with read-verify-edit pattern for reliable edits
+version: 1.0.0
+tags: [code-quality, workflow]
+dependencies: []
 ---
 
 # Structured Edit Protocol
 
+## When to Use
+
+- Editing files where exact string matches are error-prone (e.g., str_replace failures)
+- Making targeted changes that require precise location and verification
+
+## When NOT to Use
+
+- One-line edits where a direct edit is safe and unambiguous
+- Large refactors better served by full rewrites or file splits
+
 ## Overview
 
 The `str_replace` edit tool is the #1 source of failures in LLM coding. Models reproduce content with subtle differences (whitespace, encoding, line endings) causing "string not found" errors.

package/dist/template/.opencode/skill/subagent-driven-development/SKILL.md

@@ -1,13 +1,24 @@
 ---
 name: subagent-driven-development
 description: Use when executing implementation plans with independent tasks in the current session - dispatches fresh subagent for each task with code review between tasks, enabling fast iteration with quality gates
+version: 1.0.0
+tags: [workflow, agent-coordination]
+dependencies: [executing-plans]
 ---
 
 # Subagent-Driven Development
 
-Execute plan by dispatching fresh subagent per task, with code review after each.
+## When to Use
+
+- Executing a plan with mostly independent tasks in the same session
+- You want a fresh subagent per task plus review checkpoints
+
+## When NOT to Use
+
+- The plan requires review or revisions first (use executing-plans)
+- Tasks are tightly coupled and need manual sequencing
+
 
-**Core principle:** Fresh subagent per task + review between tasks = high quality, fast iteration
 
 ## Overview
 
@@ -18,18 +29,6 @@ Execute plan by dispatching fresh subagent per task, with code review after each
 - Code review after each task (catch issues early)
 - Faster iteration (no human-in-loop between tasks)
 
-**When to use:**
-
-- Staying in this session
-- Tasks are mostly independent
-- Want continuous progress with quality gates
-
-**When NOT to use:**
-
-- Need to review plan first (use executing-plans)
-- Tasks are tightly coupled (manual execution better)
-- Plan needs revision (brainstorm first)
-
 ## The Process
 
 ### 1. Load Plan

package/dist/template/.opencode/skill/supabase/SKILL.md

@@ -1,11 +1,21 @@
 ---
 name: supabase
 description: Comprehensive Supabase platform MCP for database operations, edge functions, development tools, debugging, and project management. Use when working with Supabase projects, databases, or APIs.
+version: 1.0.0
+tags: [integration, mcp]
+dependencies: []
 ---
 
 # Supabase Platform (MCP)
 
-Supabase MCP server for database operations, edge functions, project management, and debugging.
+## When to Use
+
+- When you need to manage Supabase projects, databases, or edge functions via MCP.
+
+## When NOT to Use
+
+- When the backend is not Supabase or MCP access is unavailable.
+
 
 ## Available Tools