OpenCode Skills & Agents

A collection of reusable skills and agents for OpenCode - an AI-powered development assistant that runs in your terminal.

What This Does

When you add these files to your project, OpenCode will:

• Follow your coding conventions (formatting, patterns, etc.)
• Write commit messages in your preferred format
• Audit your code for security vulnerabilities
• Review code quality and suggest improvements
• Write and fix tests
• Write and maintain documentation
• Use proper patterns for your tech stack

Installation

Method 1: NPX (Recommended)

cd /path/to/your/project
npx ocs-stats

That's it! The .opencode folder will be created in your project.

Global install (shared across all projects):

npx ocs-stats --global

Method 2: Download ZIP

1. Click the green "Code" button at the top of this page
2. Select "Download ZIP"
3. Extract the ZIP file
4. Copy the templates/.opencode folder to your project root

your-project/
├── .opencode/     ← Paste this folder here
├── src/
├── package.json
└── ...

Method 3: Clone & Copy

git clone https://github.com/Zen0space/opencode-skills.git
cp -r opencode-skills/templates/.opencode /path/to/your/project/

Verify Installation

cd /path/to/your/project
opencode

OpenCode automatically loads any .opencode folder in your project root.

Check Your Progress

Use the agent name as a command to view progress:

npx ocs-stats security     # Security agent progress
npx ocs-stats testing      # Testing agent progress
npx ocs-stats code-review  # Code review progress
npx ocs-stats docs         # Docs agent progress

Example output:

╔══════════════════════════════════════╗
║        SECURITY AGENT                ║
╠══════════════════════════════════════╣
║  Level 1 - Novice                    ║
║  XP: [█████████░░░░░░░░] 85/150       ║
║  Progress: 57%                       ║
║                                      ║
║  Stats:                              ║
║  * Issues Fixed:  4                  ║
║  * Audits Done:   2                  ║
║  * Patterns Added: 1                 ║
║  * XP Penalties:  0                  ║
╚══════════════════════════════════════╝

Update Skills

npx ocs-stats update          # Smart merge update
npx ocs-stats update --check  # Check for updates without applying
npx ocs-stats update --force  # Force fresh install

What's Included

Agents

Switch between agents with Tab in OpenCode, or mention them with @agent-name.

| Agent | Description | |-------|-------------| | security | Security expert for auditing and fixing vulnerabilities | | testing | Testing expert for unit, integration, and E2E tests | | code-review | Code quality reviewer — finds bugs, patterns, and improvements | | docs | Documentation expert for READMEs, API docs, JSDoc, and guides |

Skills

| Skill | Description | |-------|-------------| | commit | Commit message conventions (type(scope): description format) | | code-review | Code review patterns and best practices | | docs | Documentation standards and patterns | | memories | Session memory for tracking work context and pending tasks | | mobile | Mobile development (React Native, Flutter, Swift) | | security | Security patterns, auth approach, and anti-patterns | | testing | Testing patterns (Vitest, Jest, React Testing Library, Playwright) | | webapp | Web development (React, Vue, Svelte, Angular) |

Customization

Understand Session Memory

The memories skill tracks your current work session:

• Current Focus: What you're actively working on
• Recent Work: Last changes made
• Pending Tasks: TODOs to complete
• Context Notes: Important decisions and gotchas

The agent reads and updates this file automatically. You can also edit it manually.

Update Commit Conventions (Optional)

Edit .opencode/skills/commit/SKILL.md if you use different commit formats.

Remove What You Don't Need

# Remove mobile skill if you're not building a mobile app
rm -rf .opencode/skills/mobile

# Remove an agent you don't need
rm -rf .opencode/agents/security
rm -rf .opencode/security

Agent XP System

All four agents share the same XP-based leveling system. XP is only awarded after work is completed — never for planning or reviewing alone.

Two-Phase Workflow

Every agent follows a strict two-step process:

• Phase 1 — Read & Plan: The agent analyzes your code and presents findings. No XP awarded.
• Phase 2 — Fix/Write: Only after you ask the agent to act, and the work is done and verified, does it earn XP.

Level Thresholds

| Level | Title | XP to Advance | |-------|-------|---------------| | 1 | Novice | 150 | | 2 | Apprentice | 300 | | 3 | Practitioner | 450 | | 4 | Expert | 1,500 | | 5 | Master | 3,000 | | 6 | Grandmaster | Max level |

Security Agent

XP Awards

| Action | XP | |--------|-----| | Fix critical vulnerability | +60 XP | | Fix high vulnerability | +35 XP | | Fix medium vulnerability | +15 XP | | Fix low vulnerability | +10 XP | | Add security pattern | +30 XP | | Document new vulnerability type | +20 XP | | Complete package audit | +75 XP |

Level-Specific Focus

| Level | Unlocks | |-------|---------| | 1 - Novice | Basic input validation, simple auth patterns, common anti-patterns | | 2 - Apprentice | + Auth/authorization flaws, session management issues | | 3 - Practitioner | + Data exposure risks, API security concerns | | 4 - Expert | + Complex vulnerability chains, race conditions | | 5 - Master | + Business logic vulnerabilities, advanced exploitation techniques | | 6 - Grandmaster | + Custom exploit development, architecture-level security flaws |

Preflight Checklist

Before risky operations (auth changes, DB schema, middleware), the agent:

1. Shows a dry-run preview
2. Confirms user permission
3. Documents rollback plan

Testing Agent

XP Awards

| Action | XP | |--------|-----| | Write passing unit test | +10 XP | | Write passing integration test | +15 XP | | Write passing E2E test | +20 XP | | Fix broken/flaky test | +10 XP | | Add new test pattern | +30 XP | | Complete test suite (single file) | +20 XP | | Complete test suite (package) | +100 XP |

Level-Specific Focus

| Level | Unlocks | |-------|---------| | 1 - Novice | Basic unit tests with AAA pattern, simple function testing | | 2 - Apprentice | + Integration tests, API testing, DB testing patterns | | 3 - Practitioner | + E2E testing with Playwright, browser automation | | 4 - Expert | + Advanced mocking, test utilities and factories | | 5 - Master | + Coverage strategies, flaky test prevention, performance testing | | 6 - Grandmaster | + Testing architecture, CI/CD integration, custom test frameworks |

Playwright Integration

When you need E2E testing:

1. The testing agent checks for Playwright MCP
2. If not configured, prompts you to enable it
3. Creates opencode.json with Playwright MCP config
4. Installs @playwright/test and browser binaries

Code Review Agent

XP Awards

| Action | XP | |--------|-----| | Fix critical issue | +60 XP | | Fix high issue | +35 XP | | Fix medium issue | +20 XP | | Fix low issue | +10 XP | | Add new pattern to skill | +30 XP |

Level-Specific Focus

| Level | Unlocks | |-------|---------| | 1 - Novice | Basic code quality, naming conventions, simple anti-patterns | | 2 - Apprentice | + Logic errors, edge cases, error handling, performance issues | | 3 - Practitioner | + Design patterns, SOLID principles, code duplication | | 4 - Expert | + Architecture concerns, scalability, complex refactoring | | 5 - Master | + System-wide patterns, cross-cutting concerns, performance profiling | | 6 - Grandmaster | + Strategic improvements, tech debt prioritization, team standards |

Docs Agent

XP Awards

| Action | XP | |--------|-----| | Write new doc section | +20 XP | | Improve existing docs | +15 XP | | Add code examples | +10 XP | | Fix doc typos/errors | +5 XP | | Create tutorial/guide | +40 XP | | Write API documentation | +25 XP | | Update README | +15 XP | | Add JSDoc comments | +10 XP | | Create changelog entry | +10 XP | | Add new pattern to skill | +30 XP |

Level-Specific Focus

| Level | Unlocks | |-------|---------| | 1 - Novice | Basic README sections, code comments, getting started guides | | 2 - Apprentice | + API docs, configuration docs, error message docs, JSDoc | | 3 - Practitioner | + Architecture docs, design decision records, complex tutorials | | 4 - Expert | + Contribution guidelines, release docs, migration guides | | 5 - Master | + Comprehensive style guides, documentation architecture | | 6 - Grandmaster | + Documentation strategy, knowledge base design, developer experience |

Hard Rules (All Agents)

All agents share these rules that cannot be overridden:

• No any types — agents will never write or suggest TypeScript's any type
• No useEffect by default — treated as a last resort; agents always find a cleaner approach first
• No git commits or pushes — agents cannot run git commit, git push, or any destructive git command

File Structure

.opencode/
├── agents/
│   ├── security.md          # Security audit agent
│   ├── testing.md           # Testing agent
│   ├── code-review.md       # Code review agent
│   └── docs.md              # Documentation agent
├── skills/
│   ├── code-review/SKILL.md # Code review patterns
│   ├── commit/SKILL.md      # Commit conventions
│   ├── docs/SKILL.md        # Documentation standards
│   ├── memories/SKILL.md    # Session memory (auto-updated)
│   ├── mobile/SKILL.md      # Mobile patterns (RN, Flutter, Swift)
│   ├── security/SKILL.md    # Security patterns
│   ├── testing/SKILL.md     # Testing patterns
│   └── webapp/SKILL.md      # Web patterns (React, Vue, Svelte, Angular)
├── security/
│   ├── xp.json              # XP tracking (auto-updated)
│   └── knowledge.md         # Accumulated findings (auto-updated)
├── testing/
│   ├── xp.json              # Testing XP tracking (auto-updated)
│   └── knowledge.md         # Testing patterns & lessons (auto-updated)
├── code-review/
│   ├── xp.json              # Code review XP tracking (auto-updated)
│   └── knowledge.md         # Review patterns & lessons (auto-updated)
└── docs/
    ├── xp.json              # Docs XP tracking (auto-updated)
    └── knowledge.md         # Documentation patterns & lessons (auto-updated)

For Contributors

opencode-skills/
├── package.json             # npm package config (v1.3.5)
├── bin/cli.js               # CLI entry point
├── src/                     # Source files
│   ├── init.js
│   ├── display.js
│   ├── merge.js
│   └── stats.js
├── templates/               # Files copied to user projects
│   ├── agents/
│   │   ├── security.md
│   │   ├── testing.md
│   │   ├── code-review.md
│   │   └── docs.md
│   ├── skills/
│   ├── security/
│   ├── testing/
│   ├── code-review/
│   └── docs/
├── CHANGELOG.md
├── README.md
└── LICENSE

Publishing to npm:

npm login
npm publish

CLI Reference

ocs-stats - Install OpenCode skills and agents

Usage:
  npx ocs-stats              Install to current project
  npx ocs-stats --global     Install globally (~/.opencode)
  npx ocs-stats update       Update skills (smart merge)
  npx ocs-stats update --check   Check for updates
  npx ocs-stats update --force   Force fresh install
  npx ocs-stats security     Show security agent progress
  npx ocs-stats testing      Show testing agent progress
  npx ocs-stats code-review  Show code-review agent progress
  npx ocs-stats docs         Show docs agent progress
  npx ocs-stats --help       Show help

Troubleshooting

OpenCode not finding my skills

• Make sure .opencode folder is in your project root (same level as package.json)
• Check that skill files are named SKILL.md (uppercase)

Skills not working as expected

• Open the SKILL.md file and verify the content
• Make sure the frontmatter (between ---) is valid YAML

Stats showing zeros or MAX LEVEL incorrectly

Make sure you're on v1.3.5 or later:

npx ocs-stats update

Want to reset an agent's XP?

Delete the tracking files and OpenCode will recreate them:

# Security
rm .opencode/security/xp.json
rm .opencode/security/knowledge.md

# Testing
rm .opencode/testing/xp.json
rm .opencode/testing/knowledge.md

# Code Review
rm .opencode/code-review/xp.json
rm .opencode/code-review/knowledge.md

# Docs
rm .opencode/docs/xp.json
rm .opencode/docs/knowledge.md

Contributing

Feel free to submit issues and pull requests to improve these skills and agents.

License

MIT License - see LICENSE for details.