opencodekit 0.18.1 → 0.18.3

package/dist/template/.opencode/skill/mockup-to-code/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: mockup-to-code
 description: Use when converting UI mockups, screenshots, Figma/Sketch designs, wireframes, or building component libraries from design systems into production-ready code
+version: 1.0.0
+tags: [ui, workflow]
+dependencies: []
 ---
 
 # Mockup to Code Skill
 
-Convert UI mockups, screenshots, and designs into production-ready code.
-
 ## When to Use
 
 - Converting Figma/Sketch mockups to React/Vue/HTML
@@ -14,6 +15,11 @@ Convert UI mockups, screenshots, and designs into production-ready code.
 - Building component libraries from design systems
 - Rapid prototyping from wireframes
 
+## When NOT to Use
+
+- No visual reference or mockup to implement.
+
+
 ## Core Workflow
 
 ### Phase 1: Design Analysis
@@ -158,6 +164,6 @@ Save implementations to `.opencode/memory/design/implementations/`
 
 | Need              | Skill                 |
 | ----------------- | --------------------- |
-| Aesthetic quality | `frontend-design` |
+| Aesthetic quality | `frontend-design`     |
 | Accessibility     | `accessibility-audit` |
 | Design tokens     | `design-system-audit` |

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

@@ -5,11 +5,21 @@ mcp:
   mqdh:
     command: "${MQDH_MCP_PATH}"
     args: []
+version: 1.0.0
+tags: [integration, mcp]
+dependencies: []
 ---
 
 # Meta Quest Developer Hub MCP
 
-Access Meta Horizon OS development tools via the MQDH MCP server. This MCP is **bundled with the Meta Quest Developer Hub application** (v6.2.1+).
+## When to Use
+
+- When you need Meta Quest docs, ADB tooling, or device management via MQDH MCP.
+
+## When NOT to Use
+
+- When you are not working on Meta Quest/VR development or MQDH is unavailable.
+
 
 ## Prerequisites
 

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

@@ -1,6 +1,9 @@
 ---
 name: obsidian
 description: Use when working with Obsidian vault via MCP - read/write notes, search, tag management, and vault operations
+version: 1.0.0
+tags: [integration, documentation]
+dependencies: []
 mcp:
   server: @mauricio.wolff/mcp-obsidian
   args: ["{env:OBSIDIAN_VAULT_PATH}"]
@@ -8,7 +11,14 @@ mcp:
 
 # Obsidian Vault (MCP)
 
-MCP server for safe Obsidian vault access. Read/write notes, search, manage tags.
+## When to Use
+
+- When you need MCP-based read/write/search operations in an Obsidian vault.
+
+## When NOT to Use
+
+- When the task does not involve an Obsidian vault or MCP access.
+
 
 ## Available Tools
 

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

@@ -1,11 +1,21 @@
 ---
 name: opensrc
 description: Fetch source code for npm, PyPI, or crates.io packages and GitHub/GitLab repos to provide AI agents with implementation context beyond types and docs. Use when needing to understand how a library works internally, debug dependency issues, or explore package implementations.
+version: 1.0.0
+tags: [research, integration]
+dependencies: []
 ---
 
 # opensrc
 
-CLI tool to fetch source code for packages/repos, giving AI coding agents deeper implementation context.
+## When to Use
+
+- When you need actual dependency source code to understand behavior or debug issues.
+
+## When NOT to Use
+
+- When API docs or local type definitions are sufficient for the task.
+
 
 ## When to Use
 
@@ -39,12 +49,12 @@ npx opensrc owner/repo@v1.0.0
 
 ## Commands
 
-| Command | Description |
-|---------|-------------|
+| Command                 | Description                     |
+| ----------------------- | ------------------------------- |
 | `opensrc <packages...>` | Fetch source for packages/repos |
-| `opensrc list` | List all fetched sources |
-| `opensrc remove <name>` | Remove specific source |
-| `opensrc clean` | Remove all sources |
+| `opensrc list`          | List all fetched sources        |
+| `opensrc remove <name>` | Remove specific source          |
+| `opensrc clean`         | Remove all sources              |
 
 ## Output Structure
 
@@ -63,6 +73,7 @@ opensrc/
 ## File Modifications
 
 On first run, opensrc prompts to modify:
+
 - `.gitignore` - adds `opensrc/` to ignore list
 - `tsconfig.json` - excludes `opensrc/` from compilation
 - `AGENTS.md` - adds section pointing agents to source code
@@ -110,6 +121,7 @@ npx opensrc zod pypi:pydantic vercel/ai
 ## References
 
 For detailed information:
+
 - [CLI Usage & Options](references/cli-usage.md) - Full command reference
 - [Architecture](references/architecture.md) - Code structure and extension
 - [Registry Support](references/registry-support.md) - npm, PyPI, crates.io details

package/dist/template/.opencode/skill/pdf-extract/SKILL.md

@@ -1,11 +1,21 @@
 ---
 name: pdf-extract
 description: Extract text, images, tables, and metadata from PDF files. Choose the right library based on extraction needs - text only, structured data, or complex layouts.
+version: 1.0.0
+tags: [research, integration]
+dependencies: []
 ---
 
 # PDF Content Extraction
 
-Extract content from PDF files using the best library for your specific use case.
+## When to Use
+
+- When you need to extract text, images, tables, or metadata from PDF files.
+
+## When NOT to Use
+
+- When the source data is already available in a non-PDF, structured format.
+
 
 ## Quick Decision Guide
 

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

@@ -1,11 +1,21 @@
 ---
 name: playwright
 description: Browser automation for testing, screenshots, form validation, and UX verification. Uses Playwright CLI for token-efficient automation, with MCP fallback for complex exploratory workflows.
+version: 1.0.0
+tags: [automation, mcp, testing]
+dependencies: []
 ---
 
 # Playwright Browser Automation
 
-Browser automation via **Playwright CLI** (primary) and **Playwright MCP** (fallback for complex workflows).
+## When to Use
+
+- When you need automated browser testing, screenshots, or form workflows via Playwright CLI/MCP.
+
+## When NOT to Use
+
+- When you specifically need to control your existing Chrome session (use playwriter instead).
+
 
 ## Quick Decision
 

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

@@ -5,11 +5,21 @@ mcp:
   playwriter:
     command: npx
     args: ["playwriter@latest"]
+version: 1.0.0
+tags: [automation, mcp]
+dependencies: []
 ---
 
 # Playwriter Browser Automation (MCP)
 
-Control your actual Chrome browser via extension. Unlike traditional browser MCP tools that spawn isolated instances, Playwriter:
+## When to Use
+
+- When you need to automate your existing Chrome browser session via the Playwriter extension.
+
+## When NOT to Use
+
+- When you need a fresh, isolated browser instance without your local extensions/cookies.
+
 
 - **Uses your existing browser** - extensions, sessions, cookies all work
 - **Single `execute` tool** - send Playwright code snippets directly

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

@@ -1,11 +1,21 @@
 ---
 name: polar
 description: Polar payment platform integration for monetization, subscriptions, and license keys. Use when implementing checkout, managing products, or building customer portals.
+version: 1.0.0
+tags: [integration, mcp]
+dependencies: []
 ---
 
 # Polar Integration
 
-Polar is a merchant-of-record platform for digital products, subscriptions, and license keys.
+## When to Use
+
+- When implementing Polar checkout, subscriptions, or license key flows.
+
+## When NOT to Use
+
+- When payments are handled by a different platform.
+
 
 ## What I Do
 

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

@@ -1,17 +1,26 @@
 ---
 name: prd
 description: Create Product Requirements Documents (PRDs) that define the end state of a feature. Use when planning new features, migrations, or refactors. Generates structured PRDs with acceptance criteria.
+version: 1.0.0
+tags: [planning, documentation]
+dependencies: []
 ---
 
 # PRD Creation Skill
 
-Create Product Requirements Documents suitable for RFC review by Principal Engineers, Designers, and Product Owners.
+## When to Use
+
+- After a design is validated and you need formal requirements and acceptance criteria
+- Before breaking work into tasks or plans for features, migrations, or refactors
+
+## When NOT to Use
+
+- When you already have an approved PRD and only need task conversion
+- For small, mechanical changes where a PRD would be overhead
+
 
-The PRD describes WHAT to build and WHY, not HOW or in WHAT ORDER.
 
-**Part of:** `development-lifecycle` skill (Phase 2: Specification)
 
-**Template:** `.opencode/memory/_templates/prd.md`
 
 ## Beads-Native Output (Recommended)
 

package/dist/template/.opencode/skill/prd-task/SKILL.md

@@ -3,15 +3,25 @@ name: prd-task
 description: Convert a Beads PRD markdown file to executable JSON tasks for autonomous execution. Use after writing `.beads/artifacts/<bead-id>/prd.md`.
 references:
   - references/prd-schema.json
+version: 1.0.0
+tags: [planning, workflow]
+dependencies: [prd]
 ---
 
 # PRD Task Skill (Beads-Native)
 
-Convert a markdown PRD into executable JSON format for autonomous task completion.
+## When to Use
+
+- After a PRD is complete at `.beads/artifacts/<bead-id>/prd.md` and you need executable tasks
+- When you need to generate `prd.json` and initialize `progress.txt` for a bead
+
+## When NOT to Use
+
+- Before a PRD exists or when requirements are still being gathered
+- If you only need a human-readable plan (use writing-plans instead)
+
 
-The PRD defines the **end state** via tasks with verification steps. The agent decides HOW to get there.
 
-**Part of:** `development-lifecycle` skill (Phase 3: Task Conversion)
 
 ## Beads-Native File Locations (Recommended)
 

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

@@ -1,18 +1,13 @@
 ---
 name: ralph
 description: Use when running autonomous agent loops for extended task completion without human intervention - handles PRD-driven development, migration tasks, or batch operations
-license: MIT
-compatibility: opencode
-metadata:
-  source: https://ghuntley.com/ralph/
-  category: automation
-  updated: 2026-01-10
+version: 1.0.0
+tags: [workflow, automation]
+dependencies: []
 ---
 
 # Ralph Wiggum - Autonomous Agent Loop
 
-A workflow pattern for extended autonomous work sessions where the agent iterates through tasks until completion.
-
 ## When to Use
 
 - **PRD-driven development**: Work through a product requirements document task by task
@@ -27,6 +22,7 @@ A workflow pattern for extended autonomous work sessions where the agent iterate
 - Exploratory work where the goal isn't clear
 - Critical production changes (requires human oversight)
 
+
 ## Quick Start
 
 Invoke the workflow with:

package/dist/template/.opencode/skill/react-best-practices/SKILL.md

@@ -1,19 +1,26 @@
 ---
-name: vercel-react-best-practices
+name: react-best-practices
 description: React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
-license: MIT
-metadata:
-  author: vercel
-  version: "1.0.0"
+version: 1.0.0
+tags: [ui, code-quality]
+dependencies: []
 ---
 
 # Vercel React Best Practices
 
-Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 45 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
+## When to Use
+
+- Applying performance guidelines to React/Next.js components or pages.
+
+## When NOT to Use
+
+- Non-React codebases or UI-free/backend-only changes.
+
 
 ## When to Apply
 
 Reference these guidelines when:
+
 - Writing new React components or Next.js pages
 - Implementing data fetching (client or server-side)
 - Reviewing code for performance issues
@@ -22,16 +29,16 @@ Reference these guidelines when:
 
 ## Rule Categories by Priority
 
-| Priority | Category | Impact | Prefix |
-|----------|----------|--------|--------|
-| 1 | Eliminating Waterfalls | CRITICAL | `async-` |
-| 2 | Bundle Size Optimization | CRITICAL | `bundle-` |
-| 3 | Server-Side Performance | HIGH | `server-` |
-| 4 | Client-Side Data Fetching | MEDIUM-HIGH | `client-` |
-| 5 | Re-render Optimization | MEDIUM | `rerender-` |
-| 6 | Rendering Performance | MEDIUM | `rendering-` |
-| 7 | JavaScript Performance | LOW-MEDIUM | `js-` |
-| 8 | Advanced Patterns | LOW | `advanced-` |
+| Priority | Category                  | Impact      | Prefix       |
+| -------- | ------------------------- | ----------- | ------------ |
+| 1        | Eliminating Waterfalls    | CRITICAL    | `async-`     |
+| 2        | Bundle Size Optimization  | CRITICAL    | `bundle-`    |
+| 3        | Server-Side Performance   | HIGH        | `server-`    |
+| 4        | Client-Side Data Fetching | MEDIUM-HIGH | `client-`    |
+| 5        | Re-render Optimization    | MEDIUM      | `rerender-`  |
+| 6        | Rendering Performance     | MEDIUM      | `rendering-` |
+| 7        | JavaScript Performance    | LOW-MEDIUM  | `js-`        |
+| 8        | Advanced Patterns         | LOW         | `advanced-`  |
 
 ## Quick Reference
 
@@ -115,6 +122,7 @@ rules/_sections.md
 ```
 
 Each rule file contains:
+
 - Brief explanation of why it matters
 - Incorrect code example with explanation
 - Correct code example with explanation

package/dist/template/.opencode/skill/receiving-code-review/SKILL.md

@@ -1,10 +1,23 @@
 ---
 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
+version: 1.0.0
+tags: [workflow, code-quality]
+dependencies: []
 ---
 
 # Code Review Reception
 
+## When to Use
+
+- You received review feedback and need to evaluate it before implementing
+- Feedback seems unclear, questionable, or potentially wrong for this codebase
+
+## When NOT to Use
+
+- You already verified and accepted the feedback and are ready to implement
+- You need to request a review (use requesting-code-review)
+
 ## Overview
 
 Code review requires technical evaluation, not emotional performance.
@@ -24,6 +37,15 @@ WHEN receiving code review feedback:
 6. IMPLEMENT: One item at a time, test each
 ```
 
+## Review Intake Checklist
+
+- [ ] Read the full feedback without reacting
+- [ ] Restate requirements in your own words
+- [ ] Verify against codebase reality
+- [ ] Evaluate technical correctness for this stack
+- [ ] Respond with acknowledgment or reasoned pushback
+- [ ] Implement one item at a time with tests
+
 ## Forbidden Responses
 
 **NEVER:**

package/dist/template/.opencode/skill/requesting-code-review/SKILL.md

@@ -1,13 +1,24 @@
 ---
 name: requesting-code-review
 description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements - dispatches 5 parallel specialized review agents for comprehensive multi-angle review
+version: 1.0.0
+tags: [workflow, code-quality]
+dependencies: []
 ---
 
 # Requesting Code Review
 
-Dispatch 5 parallel specialized review agents. One generic reviewer is not review — it's a checkbox.
+## When to Use
+
+- After completing a feature/task batch and before moving on
+- Before merging to main or shipping changes
+
+## When NOT to Use
+
+- During TDD RED commits or other intentionally failing states
+- When you only need a targeted answer to a specific question
+
 
-**Core principle:** All 5 angles, every time. No tiers, no exit ramps.
 
 ## When to Request Review
 
@@ -25,6 +36,11 @@ Dispatch 5 parallel specialized review agents. One generic reviewer is not revie
 
 ### Step 1: Get git context
 
+#### Review Setup Checklist
+
+- [ ] Determine BASE_SHA and HEAD_SHA
+- [ ] Ensure requirements summary or plan link is available
+
 ```bash
 BASE_SHA=$(git rev-parse origin/main 2>/dev/null || git rev-parse HEAD~1)
 HEAD_SHA=$(git rev-parse HEAD)
@@ -139,6 +155,12 @@ Return: CRITICAL / IMPORTANT / MINOR findings with file:line references.`,
 
 ### Step 3: Synthesize findings
 
+#### Synthesis Checklist
+
+- [ ] Count Critical / Important / Minor findings
+- [ ] List file:line references for each issue
+- [ ] Mark readiness: proceed vs fix required
+
 After all 5 agents return:
 
 ```markdown
@@ -164,6 +186,12 @@ After all 5 agents return:
 
 ### Step 4: Act on findings
 
+#### Remediation Checklist
+
+- [ ] Fix all Critical issues before proceeding
+- [ ] Fix Important issues in this PR
+- [ ] Record Minor issues for later
+
 | Severity      | Action                                   |
 | ------------- | ---------------------------------------- |
 | **Critical**  | Fix immediately before any other work    |

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

@@ -5,11 +5,21 @@ references:
   - send-email
   - receive-email
   - react-email
+version: 1.0.0
+tags: [integration, mcp]
+dependencies: []
 ---
 
 # Resend Email Platform
 
-Consolidated skill for building email systems with Resend. Use decision trees below to find the right approach, then load detailed references.
+## When to Use
+
+- When integrating Resend for sending/receiving emails or building React Email templates.
+
+## When NOT to Use
+
+- When email delivery is handled by a different provider or not required.
+
 
 ## How to Use This Skill
 

package/dist/template/.opencode/skill/root-cause-tracing/SKILL.md

@@ -1,39 +1,28 @@
 ---
 name: root-cause-tracing
 description: Use when errors occur deep in execution and you need to trace back to find the original trigger - systematically traces bugs backward through call stack, adding instrumentation when needed, to identify source of invalid data or incorrect behavior
+version: 1.0.0
+tags: [debugging, workflow]
+dependencies: []
 ---
 
 # Root Cause Tracing
 
-## Overview
+## When to Use
 
-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.
+- Errors occur deep in a call stack and the immediate failure is just a symptom
+- You need to trace where invalid data or state originated
 
-**Core principle:** Trace backward through the call chain until you find the original trigger, then fix at the source.
+## When NOT to Use
 
-## When to Use
+- The error is at the entry point and the root cause is obvious
+- You’re doing feature work with no failures to trace
 
-```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";
-}
-```
+## Overview
 
-**Use when:**
+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.
 
-- 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
+**Core principle:** Trace backward through the call chain until you find the original trigger, then fix at the source.
 
 ## The Tracing Process
 

package/dist/template/.opencode/skill/session-management/SKILL.md

@@ -1,11 +1,21 @@
 ---
 name: session-management
 description: Use when context is growing large, switching tasks, or needing previous session context - covers thresholds, session tools, and workflow patterns
+version: 1.0.0
+tags: [context, workflow]
+dependencies: []
 ---
 
 # Session Management
 
-**Philosophy**: Short sessions (<150k tokens) beat long bloated ones. Agents get worse with too much context. Cost is exponential.
+## When to Use
+
+- Managing context growth, switching tasks, or resuming past sessions.
+
+## When NOT to Use
+
+- Single, short tasks that don't require session transitions.
+
 
 ## Context Thresholds
 

package/dist/template/.opencode/skill/sharing-skills/SKILL.md

@@ -1,10 +1,21 @@
 ---
 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.

package/dist/template/.opencode/skill/skill-creator/SKILL.md

@@ -1,21 +1,22 @@
 ---
 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
 
-Guide for creating effective skills that extend agent capabilities.
-
-> **CRITICAL: YAML FRONTMATTER REQUIRED**
-> Every SKILL.md **MUST** begin with YAML frontmatter on line 1.
->
-> ```yaml
-> ---
-> name: skill-name
-> description: One-line description of what this skill does
-> ---
-> ```
+## 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