oh-my-opencode-slim/src/skills/codemap.md

src/skills/

Responsibility

• Owns metadata-driven OpenCode custom skills shipped with this package
• Maintains the skill contract artifacts (SKILL.md, README.md, per-skill helper files) that are copied into ${configDir}/skills at install time
• Preserves a canonical registry boundary: runtime code consumes skill definitions as data, not as executable plugin dependencies
• Skills are partitioned into orchestrator-only workflows and general-purpose skills for broad reuse

Design

Skill Registry

• CUSTOM_SKILLS in src/cli/custom-skills-registry.ts is the authoritative skill manifest for bundled skills
• Each entry maps folder name + sourcePath to an install-time consumer
• Skills are categorized by purpose and access scope:

Skill	Type	Purpose
codemap/	General-purpose	Repository mapping and codebase documentation skill
clonedeps/	General-purpose	Workflow skill for dependency source mirroring and inspection
simplify/	General-purpose	Readability and maintainability guidance skill
deepwork/	Orchestrator-only	Heavy coding sessions, multi-phase implementation, and risky refactors
verification-planning/	Orchestrator-only	Project-specific evidence planning and verification affordances before non-trivial implementation
reflect/	Orchestrator-only	Learning from repeated work and suggesting reusable improvements
worktrees/	Orchestrator-only	Safe Git worktree lanes for parallel, risky, or isolated work
oh-my-opencode-slim/	Orchestrator-only	Plugin configuration and self-improvement guidance

Installation Pipeline

• install.ts runs installCustomSkill() which recursively copies bundled skill directories into the OpenCode skills directory
• During plugin release, the files whitelist in package.json must include src/skills so src/skills/** survive npm pack
• OpenCode plugin startup discovers these installed folders and reads each SKILL.md as a prompt-level contract

Runtime Consumption

• Files are considered static runtime payload
• No plugin TS module in src/ imports these files directly
• They are loaded by OpenCode via filesystem installation at runtime

Flow

1. Skill Discovery: src/cli/custom-skills-registry.ts defines CUSTOM_SKILLS array with skill metadata
2. Installation: bun run install delegates to src/cli/install.ts, where installCustomSkills() gates copying of each CUSTOM_SKILLS entry
3. Validation: installCustomSkill() computes packageRoot, validates sourcePath, then performs a recursive directory copy via copyDirRecursive()
4. Distribution: During plugin release, package.json files whitelist ensures src/skills/** are included in the published tarball
5. Runtime Discovery: OpenCode plugin startup discovers installed skill folders and reads each SKILL.md as a prompt-level contract

Integration

Build & Release Dependencies

• src/cli/custom-skills-registry.ts: Source-of-truth registry consumed by installer and permission helpers
• src/cli/install.ts: Contains installCustomSkills() and installCustomSkill() functions
• verify-release-artifact.ts: Enforces artifact completeness by asserting key bundled skill payloads are present in the tarball:
  • src/skills/simplify/SKILL.md
  • src/skills/codemap/SKILL.md
  • src/skills/clonedeps/SKILL.md
  • src/skills/deepwork/SKILL.md
  • src/skills/verification-planning/SKILL.md
  • src/skills/reflect/SKILL.md
  • src/skills/worktrees/SKILL.md
  • src/skills/oh-my-opencode-slim/SKILL.md
• package.json scripts (verify:release, build) rely on these assets to ensure install-time skill availability

Permission System

• src/cli/skills.ts:getSkillPermissionsForAgent() auto-populates permission rules for bundled skills when agent policy is derived from built-in recommendations
• Bundled skills are treated as data payloads with explicit permission boundaries defined in the skill manifests

Skill Contracts

Each skill directory contains:

• SKILL.md: Skill contract defining name, description, and usage contract
• README.md: Documentation and examples for the skill
• Optional helper files and subdirectories for skill-specific functionality

These artifacts are copied verbatim to the OpenCode skills directory during installation and serve as the skill's interface definition.