Skills

Optimize agent context setup.

Activates when

• starting a session
• output degrades
• switching tasks

Use it for

• Starting a new coding session
• Agent output quality is declining
• Switching between parts of a codebase
• Setting up a new project for AI-assisted development

Don't use it for

• One-off queries with no context needs
• Trivial changes with no dependencies
• Already in an active session with fresh context

2 guidesSKILL.md

Define the universal engineering philosophy for all platform skills: discovery, contracts, anti-slop, quality gates.

Activates when

• Loaded by all platform skills

Use it for

• Loaded by all platform skills. Never invoke directly.

Don't use it for

• Platform-specific implementation (platform skills add details to this foundation)

8 guidesSKILL.md

Capture user preferences once, persist across projects. Creates a user profile for personalization across skills.

Activates when

• first session
• setup preferences

Use it for

• Any skill starts and no ~/.config/opencode/user-profile.json
• user-profile.json > 90 days old
• User says "setup preferences", "remember stack", "configure defaults"

Don't use it for

• Profile exists and < 90 days old (Quick Verify instead)
• User says "skip" and profile exists
• Turbo Mode active with existing profile

2 guidesSKILL.md

Refine raw ideas into sharp, actionable concepts through divergent and convergent thinking.

Activates when

• an idea is vague or needs stress-testing

Use it for

• Idea is still vague or incomplete
• Need to stress-test assumptions before committing
• Want to explore alternatives before converging on one

Don't use it for

• Requirements are already clear and documented
• Trivial changes with obvious scope

2 guidesSKILL.md

Extract what the user actually wants through one-question-at-a-time interviewing.

Activates when

• a request is underspecified

Use it for

• Request is underspecified ("build me X" without "for whom" or "why now")
• User says "interview me", "grill me", "are we sure?"
• Agent catches itself about to silently fill in ambiguous requirements
• Before spec-driven-development for any non-trivial request

Don't use it for

• Requirements already clear and documented
• Trivial, well-defined tasks (one-line fix, typo correction)
• Override: NOINTENT: reason in commit body

2 guidesSKILL.md

Evaluate architecture options with 2-3 alternatives before building. Challenges assumptions, locks decisions into specs.

Activates when

• stack
• architecture
• pattern

Use it for

• Non-trivial project (multi-page, multi-module, backend needs)
• Choosing between frameworks, stacks, patterns
• User says "I want X" without justification
• Evaluating microservices vs monolith, SSR vs CSR, REST vs GraphQL
• Decision expensive to reverse
• Skip when: Stack locked in SPEC.md, pure implementation. One-off tweaks. Toy projects.

Don't use it for

• Implementation details after architecture is decided
• One-off tweaks or toy projects
• When the stack is already locked in SPEC.md

3 guidesSKILL.md

Manage deprecation and migration of old systems, APIs, and features. Covers sunset strategies, backward compatibility, timelines.

Activates when

• Removing or replacing an existing API endpoint

Use it for

• Removing or replacing an existing API endpoint
• Migrating users from one implementation to another
• Deciding whether to maintain or sunset existing code
• Planning backward-compatible transitions
• A third-party API or dependency your system relies on announces deprecation

Don't use it for

• Building new features (use feature implementation skills)
• Deployment (use shipping-and-launch)

2 guidesSKILL.md

Review every non-trivial decision with a fresh-context adversarial review.

Activates when

• correctness matters
• stakes are high
• code is unfamiliar

Use it for

• A decision is non-trivial when it introduces branching logic, crosses a module boundary, asserts unverifiable properties (thread safety, idempotence), has irreversible blast radius (production deploy, data migration, public API change), or depends on context the future reader cannot see.
• Apply when: about to make an architectural decision, commit non-trivial code, claim a non-obvious fact, or work in code you don't fully understand.

Don't use it for

• Mechanical operations (renaming, formatting)
• Clear, unambiguous instructions
• Reading or summarizing existing code
• One-line changes or pure tooling

2 guidesSKILL.md

Build features incrementally in thin vertical slices.

Activates when

• touching multiple files or when a task feels too large for one step

Use it for

• Implementing any multi-file change
• Building a new feature from a task breakdown
• Refactoring existing code
• Any time you're tempted to write >100 lines before testing

Don't use it for

• Single-file, single-function changes where scope is already minimal

2 guidesSKILL.md

Orchestrate multiple AI coding agents in parallel, pipeline, or swarm modes.

Activates when

• >2 agents or multi-file refactors

Use it for

• Task requires > 2 agents (parallel implementation, research+build+review)
• Multi-module refactor (non-overlapping files, independent modules)
• Spec-driven pipeline with phase gates (Spec → Implement → Test → Review)
• Competitive exploration (swarm mode for architecture decisions)

Don't use it for

• Single-file changes (one agent is sufficient)
• Tasks where files overlap (causes merge conflicts)
• Simple CRUD or linear workflows

1 guideSKILL.md

Decompose work into small, verifiable tasks with explicit acceptance criteria.

Activates when

• a spec needs breakdown into implementable steps

Use it for

• You have a spec and need to break it into implementable units
• A task feels too large or vague to start
• Work needs to be parallelized across multiple agents or sessions
• The implementation order isn't obvious

Don't use it for

• Single-file changes with obvious scope
• Spec already contains well-defined tasks

2 guidesSKILL.md

Ground every implementation decision in official documentation before writing code.

Activates when

• building with any framework where correctness matters

Use it for

• Using any framework, library, SDK, or API
• Implementing against a documented interface
• Migrating between versions of a dependency
• Any time correctness of API usage matters
• Using a new dependency for the first time (verify API surface before writing code)
• Upgrading a major version of a dependency (breaking changes expected — verify against new docs, not old knowledge)

Don't use it for

• Pure algorithm or data structure implementation
• Business logic with no external dependency
• Creative or design work

2 guidesSKILL.md

Create comprehensive specifications from user requests through research, critical analysis, and user alignment.

Activates when

• new project
• feature
• spec
• plan

Use it for

• Starting any new project or feature
• Ambiguous or one-sentence requirements that need clarification
• Changes touching >3 files or crossing module boundaries
• Architectural or technology decisions
• Any task estimated at >30 minutes

Don't use it for

• Single-line fixes, typo corrections, truly trivial changes (1 file, < 10 lines, no logic). For everything else, run the pipeline.

3 guidesSKILL.md

Build production-grade desktop apps with native OS integration. Default: Tauri v2. Adaptable: Electron, Flutter.

Activates when

• Build any desktop application with native OS integration

Use it for

• Build any desktop application with native OS integration.

Don't use it for

• Web-only apps (use frontend-web)
• Mobile apps (use frontend-mobile)
• CLI tools (use terminal workflow)

3 guidesSKILL.md

Build production-grade mobile apps with native design tokens and platform compliance.

Activates when

• mobile app
• React Native
• Flutter
• iOS
• Android

Use it for

• Build, design, or redesign any mobile app interface.

Don't use it for

• Web-only tasks (use frontend-web)
• Installable web apps (use frontend-pwa)
• Backend-only tasks

3 guidesSKILL.md

Build installable, offline-first web apps for all devices with native migration via Capacitor.

Activates when

• PWA
• offline
• installable
• hybrid

Use it for

• Web app with offline functionality
• Installable experience (add to homescreen)
• Cross-device (phone, tablet, foldable, TV, desktop)
• Future native distribution via Capacitor/Ionic

Don't use it for

• Simple marketing sites with no offline needs (use frontend-web)
• Pure native apps (use frontend-mobile)

4 guidesSKILL.md

Build production-quality UIs with component architecture, state management, and layout discipline.

Activates when

• web
• mobile
• desktop
• PWA

Use it for

• Building any user-facing component
• Designing component architecture or state management
• Implementing layouts, navigation, or responsive patterns
• Referenced automatically by platform skills

Don't use it for

• Platform-specific work (use the dedicated platform skill)
• API or backend work (use backend-api-mastery)

2 guidesSKILL.md

Build production-grade web interfaces.

Activates when

• website
• landing page
• web app
• Next

Use it for

• Build, design, or redesign any web interface.

Don't use it for

• Backend-only, CLI, non-visual software
• Native mobile (use frontend-mobile)
• Installable offline apps (use frontend-pwa)

8 guidesSKILL.md

Design stable APIs and module boundaries with clear contracts.

Activates when

• designing REST/GraphQL endpoints or defining type contracts between modules

Use it for

• Designing API contracts between frontend and backend
• Defining module boundaries in a codebase
• Creating type interfaces shared across packages
• Establishing communication protocols between services
• Adding a new public endpoint to an existing API
• Changing an existing API endpoint (versioning decision required)
• Introducing a new service that communicates with existing services
• Splitting a monolith into microservices (boundary discovery)
• Creating a client SDK or client library for an API
• Reviewing an existing API for backward compatibility issues
• Starting a new feature that touches more than one module (contract first, code second)

Don't use it for

• Deep backend implementation (use backend-api-mastery)
• Frontend-specific work (use frontend-web, etc.)
• Database schema design
• Purely operational API changes (add one field to existing endpoint, no versioning change)

2 guidesSKILL.md

Design production-grade APIs with intentional architecture before writing endpoints. Covers protocol, database, auth, validation, testing.

Activates when

• Building any API layer (REST, GraphQL, tRPC, WebSocket, gRPC)

Use it for

• Building any API layer (REST, GraphQL, tRPC, WebSocket, gRPC)
• Adding a database or persistence layer to a project
• Implementing authentication or authorization
• Designing error handling, validation, or rate limiting
• Creating data models, schemas, or migrations
• spec-driven-development (if SPEC.md indicates backend needs)
• architecture-analysis (if non-trivial backend is chosen)
• frontend-web or frontend-mobile (if frontend needs a backend to persist data)

Don't use it for

• The project is frontend-only with no persistence (static site, landing page)
• The backend is already designed and documented in API-DESIGN.md
• The task is purely operational (fix a bug in existing API, add one field)

5 guidesSKILL.md

Build production-grade CLI tools with argument parsing, exit codes, colored output, progress, and error handling.

Activates when

• CLI
• terminal
• shell script

Use it for

• Building a new CLI tool or command
• Adding a CLI interface to an existing project or service
• Refactoring ad-hoc scripts into a proper CLI (argument parsing, exit codes, composability)
• Creating developer tooling: scaffolds, code generators, linters, formatters, migration tools
• Building a multi-command tool (git-style subcommands: tool <noun> <verb>)
• Implementing automation that needs reliable exit codes and piped output (CI/CD, scripts)
• User says: "build a CLI", "terminal app", "command line tool", "make a tool that...", "create a command"

Don't use it for

• GUI applications (desktop, web, mobile)
• Simple one-off shell scripts (use a shell script directly)
• Full-screen TUI applications (emacs, vim-style interactive interfaces)

2 guidesSKILL.md

Test interfaces in real browsers: inspect DOM, capture console errors, analyze network requests, verify visual output. Available tools vary by platform.

Activates when

• Debugging browser-specific behavior

Use it for

• Debugging browser-specific behavior
• Verifying visual output with real runtime data
• Capturing console errors or network request issues
• Profiling frontend performance

Don't use it for

• Unit or integration testing (use test-driven-development)
• Backend testing
• Static analysis or linting
• Non-browser environments

1 guideSKILL.md

Debug systematically using root-cause analysis.

Activates when

• tests fail
• builds break
• behavior doesn't match

Use it for

• Test fails after a code change
• Build breaks or produces errors
• Runtime error in development or production
• Behavior doesn't match expectations
• Performance degrades unexpectedly
• User reports a bug

Don't use it for

• Code review or quality assessment (use code-review-and-quality)
• Building new features (use feature implementation skills)
• Speculative debugging without evidence
• First-time flaky test without reproduction steps

5 guidesSKILL.md

Stop speculative debugging after 3 same-bug strikes. Diagnose systematically before writing code.

Activates when

• repetitive fixes fail

Use it for

• Same test failing across 3+ consecutive commits (mechanical STRIKES_LOG trigger)
• Same component fixed twice with different root causes
• bug-tag: repeating in commit body for the same issue
• Escalated from debugging-and-error-recovery after repeated fix attempts

Don't use it for

• First occurrence of a bug (use debugging-and-error-recovery instead)
• One-off test flakiness or network-dependent failure
• Different components failing independently (not the same root cause)

0 guidesSKILL.md

Write tests first with RED-GREEN-REFACTOR cycle.

Activates when

• implementing logic
• fixing bugs
• proving code works

Use it for

• Implementing any new logic or behavior
• Fixing any bug (the Prove-It Pattern)
• Modifying existing functionality
• Adding edge case handling
• User says "add tests" or "make sure it works"

Don't use it for

• Pure configuration changes, documentation updates, or static content changes

6 guidesSKILL.md

Review code across 5 axes (correctness, readability, architecture, security, performance) before merging.

Activates when

• code from any author

Use it for

• Before merging any PR or change
• After completing a feature implementation
• When another agent or model produced code you need to evaluate
• When refactoring existing code
• After any bug fix (review both fix and regression test)

Don't use it for

• Work-in-progress code not ready for review
• Design or visual feedback (use critique-skill or polish)
• Performance or security investigation without code change (use dedicated skills)

3 guidesSKILL.md

Simplify code for clarity without changing behavior.

Activates when

• refactoring code that is harder to read or maintain

Use it for

• Code is correct but harder to read than necessary
• Abstractions don't earn their complexity
• Functions or components are too large
• Duplicated logic could be unified
• After code review reveals complexity issues

Don't use it for

• Behavior must change (use feature implementation skills)
• Only formatting or linting issues (use formatter/linter)
• The code is already as simple as it can be

2 guidesSKILL.md

Audit development environment (CLI tools, runtimes) before code. Proposes installations with justification.

Activates when

• starting a project

Use it for

• Starting new project (after spec, before build)
• User asks "what do I need to install" or "setup environment"
• Before build if docs/DEV-ENVIRONMENT.md missing or outdated
• Project requires testing, deployment, or design tools
• Invoked by: spec-driven-development Phase 7, shipping-and-launch, frontend-* (if MCPs absent)

Don't use it for

• Fresh DEV-ENVIRONMENT.md (<7 days) with all tools verified (skip audit)
• Pure documentation task with no tooling needs

4 guidesSKILL.md

Document architectural decisions, API changes, and features.

Activates when

• something needs a written record

Use it for

• Making a significant architectural decision
• Choosing between competing approaches
• Adding or changing a public API
• Shipping a feature that changes user-facing behavior
• Onboarding new team members or agents

Don't use it for

• Documenting obvious code or throwaway prototypes

3 guidesSKILL.md

Instrument code so production behavior is visible: structured logging, metrics, tracing, alerting.

Activates when

• shipping features that need evidence

Use it for

• Adding logging, metrics, tracing, or alerting
• Shipping features that run in production
• Production issues reported but you can't tell what happened
• Setting up monitoring dashboards
• After an incident postmortem (filling observability gaps discovered during analysis)
• Before a public launch or major feature release (ensuring launch readiness)

Don't use it for

• Deployment or rollback planning (use shipping-and-launch)
• Pre-production work

2 guidesSKILL.md

Optimize application performance beyond the frontend: Core Web Vitals, load times, server response, database queries, caching, profiling.

Activates when

• Performance budgets are being exceeded

Use it for

• Performance budgets are being exceeded
• Core Web Vitals need improvement
• Load times or Time-to-Interactive are too slow
• Profiling reveals backend or infrastructure bottlenecks
• After a major dependency upgrade or framework migration (regression risk)
• Preparing for a traffic event (launch, sale, campaign)

Don't use it for

• Frontend design performance (use optimize-skill)
• Premature optimization without measurements

2 guidesSKILL.md

Audit existing projects before new work.

Activates when

• entering a codebase for the first time or after a gap

Use it for

• Project has code AND no HEALTH-CHECK.md within 7 days.
• User asks for audit, health check, or technical debt review.
• Return after gap >3 days.
• Before "significant change" (>3 files or new feature).

Don't use it for

• Project initialized this session (already compliant)
• Single-line fix in an audited project with recent HEALTH-CHECK.md

2 guidesSKILL.md

Harden code against vulnerabilities: OWASP prevention, input validation, authentication, data storage, and third-party safety.

Activates when

• Handling user input or file uploads

Use it for

• Handling user input or file uploads
• Implementing authentication or session management
• Storing sensitive data (keys, tokens, PII)
• Integrating with third-party services
• Building any public-facing feature or API endpoint
• Processing payment or financial data
• Handling file uploads from untrusted sources

Don't use it for

• Accessibility or input validation mechanics (use hard-skill)
• Performance optimization (use performance-optimization or optimize-skill)

0 guidesSKILL.md

Fix responsive layout issues, missing mobile behavior, touch targets, and viewport handling.

Activates when

• layouts break between breakpoints

Use it for

• Layout breaks between defined breakpoints
• Mobile feels like an afterthought (tabs, full-width cards, tiny targets)
• Touch interactions don't work
• Horizontal scroll overflow
• User says "this doesn't work on my phone"
• After adding responsive review to a shipping pipeline

Don't use it for

• Creating new responsive layouts from scratch (use build skills)
• Animations (use delight or optimize)
• Typography scaling (use typeset)
• Performance (use optimize)

2 guidesSKILL.md

Audit code across 5 dimensions (accessibility, performance, theming, responsive, anti-patterns) with P0-P3 severity scoring.

Activates when

• shipping

Use it for

• Before shipping to production
• During a quality sprint
• When tech lead says "we should look at [accessibility/performance]"
• After a feature is functionally complete but not reviewed

Don't use it for

• Design quality evaluation (use critique-skill)
• One-off visual tweaks (use individual fix skills directly)
• Incomplete features (audit finds issues that are just unfinished)

4 guidesSKILL.md

Rewrite confusing UX copy so interfaces explain themselves: labels, buttons, errors, empty states, tooltips.

Activates when

• users don't understand fields

Use it for

• Writing feels templated or generic — no deliberate voice
• Users don't understand a field or flow
• Error messages blame the user or don't explain the fix
• Button copy is ambiguous ("Submit", "OK", "Click here")
• Empty states say "No items" with no context
• Tooltips restate the label
• Confirmation dialogs don't name consequences

Don't use it for

• Marketing or landing page copy (needs a writer)
• Voice/personality upgrades (use delight)
• Content strategy or information architecture

4 guidesSKILL.md

Evaluate interfaces with two-pass design review: scoring, persona tests, AI slop detection, Nielsen heuristics, and 25 anti-patterns.

Activates when

• Reviewing a design plan before any code is written (use Phase 0)

Use it for

• Reviewing a design plan before any code is written (use Phase 0)
• Page is functionally complete, before ship (use Phase 1-3)
• "Does this feel right?" — need an honest second opinion
• User flags AI tells, generic layout, or sloppy design
• Before handing off for polish pass

Don't use it for

• Technical quality or implementation bugs (use audit-skill)
• Incomplete or draft work (use shape or craft first)
• Running Phase 0 on built code (use Phase 1-3)
• Running Phase 1-3 on a plan with no code (use Phase 0)

3 guidesSKILL.md

Add micro-interactions, transitions, hover states, and feedback animations.

Activates when

• UX feels stiff or lifeless

Use it for

• Interface feels stiff or lifeless
• No feedback on hover, tap, or action completion
• User says "make it feel more responsive"
• Transitions feel jarring or instant (no duration)
• Loading states are blank or flicker
• After functionality is complete, before polish

Don't use it for

• Performance optimization (use optimize — then delight on top)
• Structural changes (use build skills)
• Replacing missing states (use harden first)

4 guidesSKILL.md

Fix critical and high-severity accessibility, input, and state issues deterministically. Cross-platform: web, mobile, desktop, PWA.

Activates when

• After audit finds P0/P1 items

Use it for

• After audit finds P0/P1 items
• User says "make this accessible"
• User says "handle edge cases better"
• Before shipping to production
• After automated a11y scan (axe-core, Lighthouse) reveals violations

Don't use it for

• Design decisions (use polish, redesign)
• Performance fixes (use optimize)
• Copy rewriting (use clarify)
• New features (use build skills)

4 guidesSKILL.md

Fix performance issues: bundle size, animations, reflows, lazy loading, image optimization, render blocking.

Activates when

• profiling reveals bottlenecks

Use it for

• After profiling reveals a specific bottleneck
• User says "this page is slow"
• Lighthouse / PageSpeed score is below target
• User says "animations jank" or "scrolling stutters"
• Bundle size exceeds budget (500KB critical path JS)
• Images are loading at full resolution on mobile

Don't use it for

• Speculative optimization (measure first)
• Design changes that happen to improve performance
• Pre-optimization during initial build (build clean first, optimize later)

4 guidesSKILL.md

Fix design detail issues: spacing, alignment, consistency, token compliance.

Activates when

• audit or when visual inconsistencies are spotted

Use it for

• After audit finds P1-P2 theming/consistency issues
• When components look "off" but structurally work
• User says "make this look more polished"
• During design QA before shipping
• When design tokens exist but aren't applied consistently

Don't use it for

• Technical issues (use harden)
• UX flow issues (use redesign, distill)
• Structural redesign (use redesign)
• Copy rewriting (use clarify)

2 guidesSKILL.md

Fix typography and reading rhythm issues: typeface, weight, size, line-height, spacing, type ramp.

Activates when

• text feels cramped or inconsistent

Use it for

• Text feels cramped or airy
• Headings and body don't feel co-ordinated
• Type sizes don't follow a consistent ramp
• Line-height is inconsistent between similar texts
• Font weights vary without reason
• Letter-spacing is random or missing
• After changing type scale or introducing a new variant

Don't use it for

• Choosing a new typeface (design decision, not polish)
• Rewriting copy (use clarify)
• Color/token issues (use polish)
• Spacing/layout issues (use polish)

2 guidesSKILL.md

Design raw mechanical interfaces with Swiss typographic print and military terminal aesthetics: rigid grids, extreme type scale, utilitarian color.

Activates when

• user chooses brutalist / military / industrial / tactical design direction

Use it for

• Use when: user chooses brutalist / military / industrial / tactical design direction.
• Architect web interfaces synthesizing mid-century Swiss design, industrial manuals, and retro-futuristic aerospace terminals.

Don't use it for

• Soft, polished, or consumer UIs
• Interfaces requiring rounded corners or gradients

0 guidesSKILL.md

Design editorial product UI inspired by Notion and Linear: warm monochrome palette, typographic contrast, flat bento grids, muted pastel accents.

Activates when

• Product UIs, documentation sites, SaaS dashboards, editorial layouts

Use it for

• Product UIs, documentation sites, SaaS dashboards, editorial layouts. Not for playful consumer brands or experimental agency sites.

Don't use it for

• Industrial, brutalist, or deliberately raw aesthetics
• Playful consumer brands or experimental agency sites

0 guidesSKILL.md

Prevent placeholders, truncated code, and half-finished agent outputs.

Activates when

• the agent ships incomplete work

Use it for

• Before delivering any code output to a user
• After completing an implementation phase (before marking done)
• When context limits force truncated responses
• After any code generation that involves multiple files

Don't use it for

• One-off draft or throwaway code
• Exploratory or research-only output
• Output that will be immediately deleted or overwritten

2 guidesSKILL.md

Improve existing codebases systematically: scan the UI, diagnose issues across 8 categories, fix in priority order. Never breaks existing functionality.

Activates when

• upgrading visual design of existing codebase

Use it for

• Use when: upgrading visual design of existing codebase. Not for greenfield projects.

Don't use it for

• Greenfield projects (use build skills instead)
• Framework migrations or stack changes
• Performance optimization without visual changes

0 guidesSKILL.md

Design polished, calm, premium UIs with soft contrast, generous whitespace, premium fonts, and spring motion.

Activates when

• user chooses premium agency / luxury / calm design direction

Use it for

• Use when: user chooses premium agency / luxury / calm design direction.
• Engineer $150k+ agency-level digital experiences. Haptic depth, cinematic spatial rhythm, obsessive micro-interactions.

Don't use it for

• Industrial, brutalist, or raw mechanical aesthetics
• Minimalist editorial or documentation UIs

0 guidesSKILL.md

Initialize and configure Git before writing code. Decides mono vs multi-repo, creates .gitignore/.env.example, sets branching strategy.

Activates when

• After SPEC.md and DESIGN.md exist but before BUILD phase begins

Use it for

• After SPEC.md and DESIGN.md exist but before BUILD phase begins
• When the user says "start the project", "setup repo", "git init"
• Before npm install, create-next-app, or any tool that generates files

Don't use it for

• The project already has a Git repository with .gitignore and .env.example
• The task is purely committing changes in an existing repo (use git-workflow-and-versioning)

6 guidesSKILL.md

Manage git workflow practices: branching, committing, resolving conflicts, parallel streams.

Activates when

• making any code change

Use it for

• Making any code change (every change flows through git)
• Committing, pushing, merging, or rebasing
• Resolving merge conflicts
• Organizing parallel work streams
• Setting up a new project's git workflow

Don't use it for

• Repository initialization or .gitignore setup (use git-init-and-versioning)
• Deployment or release branching and tagging (use fullstack-shipping)
• Code review or PR approval decisions (use code-review-and-quality)

3 guidesSKILL.md

Automate CI/CD pipeline setup, quality gates, and deployment.

Activates when

• configuring test runners or build pipelines

Use it for

• Setting up or modifying CI/CD pipelines
• Configuring automated quality gates
• Automating build and deployment processes
• Adding test runners to CI

Don't use it for

• Full deployment strategy with monitoring and rollback (use fullstack-shipping)
• Pre-deployment launch checklist

2 guidesSKILL.md

Build, test, and deploy with production-grade CI/CD, testing, orchestration, and monitoring.

Activates when

• deploy
• ship
• launch
• pipeline
• production

Use it for

• Preparing to deploy any project to production or staging
• Setting up CI/CD pipelines for the first time
• Adding testing infrastructure to an existing project
• Planning a release or launch
• Configuring monitoring, alerting, or rollback strategies
• The user says "go live", "ship it", "deploy to production"
• frontend-web or frontend-mobile Phase 7 (QA gates before delivery)
• backend-api-mastery Phase 7 (documentation & versioning before release)
• spec-driven-development Phase 8 (implement gate before deployment)

Don't use it for

• Local development or prototyping without production intent
• Hotfixes where CI/CD is already established and the fix is trivial
• Documentation-only changes with no code impact

3 guidesSKILL.md

Instrument a repo with mechanical gates so an agent cannot commit untested code. Installs local hooks, a TDD gate, and a required CI check, then proves the gate fires.

Activates when

• A user says their AI agent ships untested, unreviewed, or broken code

Use it for

• A user says their AI agent ships untested, unreviewed, or broken code.
• They want a TDD gate, a pre-commit gate, or a required CI status check.
• They ask to "add enforcement", "block bad commits", or "make the agent prove it works".
• A repo has prompts (CLAUDE.md, .cursorrules, AGENTS.md) but no mechanical enforcement.

Don't use it for

• The repo already has active gates — verify first (see *Verification*).
• Non-git projects: no VCS means no hooks; enforcement is convention-only.
• One-off scripts where a gate is pure noise.

2 guidesSKILL.md

Prepare production launches with checklists, monitoring, staged rollout, and rollback strategies.

Activates when

• any significant deployment

Use it for

• Deploying a feature to production for the first time
• Releasing a significant change to users
• Migrating data or infrastructure
• Any deployment that carries risk (all of them)

Don't use it for

• Local development or prototyping
• Pre-production CI/CD setup (use ci-cd-and-automation)

2 guidesSKILL.md

Log empirical quality metrics across projects: build pass rate, rework, coverage, discovery time, gate pass rate. Runs automatically in the background.

Activates when

• Automatically in background after every significant action

Use it for

• Automatically in background after every significant action. No direct invocation needed.

Don't use it for

• Manual data collection or ad-hoc queries (runs automatically)
• Direct invocation (background skill only)

2 guidesSKILL.md

Edit or create OpenCode's own configuration.

Activates when

• configuring OpenCode itself

Use it for

• Creating or editing opencode.json / opencode.jsonc
• Adding, modifying, or removing MCP servers
• Changing agent permission rules
• Installing or disabling plugins
• Editing skill paths or agent definitions

Don't use it for

• Your application code (use the appropriate platform skill)
• Any project that is not configuring OpenCode itself

2 guidesSKILL.md

Audit and fix project issues via self-improvement loop: detect, diagnose, propose, execute with human approval. Max 3 iterations per session.

Activates when

• After a session when several commits have been made

Use it for

• After a session when several commits have been made
• When user says "run self-improvement loop" or "audit the project"
• At session start if audit-project.sh has not been run in 7+ days

Don't use it for

• One-off edits or active development (use feature implementation skills)
• First-time project setup

4 guidesSKILL.md

Generate new agent skills from a workflow description: SKILL.md with frontmatter, workflow, examples, and eval cases.

Activates when

• creating from a description

Use it for

• Need a new skill and don't want to write SKILL.md from scratch
• Have a clear description of the workflow the skill should execute
• Want a skill with eval cases included from the start
• Rapid prototyping of new capabilities

Don't use it for

• Modifying an existing skill (use skill-improver)
• One-off tasks that won't be reused as skills
• Creating skills for trivial workflows (better to write manually)

2 guidesSKILL.md

Analyze failing eval cases and propose improvements. Reads eval results, identifies failure patterns, outputs a diff. Do NOT auto-apply.

Activates when

• run-evals.sh shows trigger failures for a skill

Use it for

• run-evals.sh shows trigger failures for a skill
• run-golden.sh shows output quality issues
• run-adversarial.sh shows robustness gaps
• A skill's description is too narrow or too broad
• Eval coverage is partial and needs expansion

Don't use it for

• Creating a new skill (use skill-creator)
• The skill has no eval cases yet (add them first)
• The fix is obvious (just edit the SKILL.md)
• The eval failure is from a bug in the eval case itself

2 guidesSKILL.md