Agent Skills & Instructions

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• workers/kdco-registry/files/skill/code-review/SKILL.md
• workers/kdco-registry/files/agent/coder.md
• examples/registry-starter/AGENTS.md
• workers/kdco-registry/files/plugin/workspace-plugin.ts
• workers/kdco-registry/files/skill/plan-protocol/SKILL.md
• workers/kdco-registry/files/skill/code-philosophy/SKILL.md
• workers/kdco-registry/files/agent/reviewer.md

Agent Skills & Instructions form the behavioral foundation of the OCX ecosystem. Skills (ocx:skill) are specialized Markdown-based instructions that teach AI assistants how to perform specific tasks, such as code reviews or following architectural protocols. Instructions are often injected dynamically via plugins to enforce project-specific constraints or orchestrator-specialist boundaries.

This system ensures that various AI agents—such as the Coder, Scribe, and Reviewer—operate under a unified set of methodologies, such as the "5 Laws of Elegant Defense." By separating role definitions (ocx:agent) from reusable behaviors (ocx:skill), the project enables a modular architecture where skills can be loaded on-demand based on the task context.

Sources: examples/registry-starter/AGENTS.md:120-128, workers/kdco-registry/files/plugin/workspace-plugin.ts:250-258

Component Architecture

The OCX registry supports multiple component types that define AI behavior. While Agents define roles and permissions, Skills provide the detailed procedural knowledge.

Component Type	Purpose	File Format
ocx:skill	Detailed instructions for specific AI behaviors	Markdown (SKILL.md)
ocx:agent	Specialized AI role definitions with permissions	Markdown
ocx:plugin	TypeScript code extending OpenCode via tools and hooks	TypeScript

Sources: examples/registry-starter/AGENTS.md:113-118

Skill and Agent Interaction Flow

The following diagram illustrates how an orchestrator agent delegates tasks to specialized agents, who then load specific skills based on the task type.

The workflow ensures that agents do not perform actions without the necessary methodological context provided by skills.
Sources: workers/kdco-registry/files/agent/coder.md:11-15, workers/kdco-registry/files/agent/reviewer.md:10-18

Core Philosophies

The project enforces two primary sets of "Laws" or "Pillars" through skill injection to maintain code quality and UI consistency.

The 5 Laws of Elegant Defense (code-philosophy)

These laws guide internal logic and data flow to ensure code is flat, readable, and safe.

1. Early Exit: Handle edge cases and errors at the top of functions to reduce nesting.
2. Parse, Don't Validate: Parse inputs at boundaries to transform unknown data into trusted, typed states.
3. Atomic Predictability: Functions should be pure (Same Input = Same Output) without hidden mutations.
4. Fail Fast, Fail Loud: Halt immediately with descriptive errors for invalid states.
5. Intentional Naming: Variables and functions must be named so clearly that logic reads like English.

Sources: workers/kdco-registry/files/skill/code-philosophy/SKILL.md:14-34, examples/registry-starter/AGENTS.md:17-54

The 5 Pillars of Intentional UI (frontend-philosophy)

Focused on visual and atmospheric standards, including Typography, Color, Motion, Composition, and Atmosphere.
Sources: workers/kdco-registry/files/agent/coder.md:61-66

Plan Protocol & Management

The plan-protocol skill and the workspace-plugin manage implementation plans. This system enforces a structured lifecycle for complex tasks using a YAML-frontmatter-based Markdown format.

Plan Structure Validation

The workspace-plugin.ts uses Zod schemas to validate plan structure at the boundary (plan_save).

const PlanSchema = z.object({
	frontmatter: z.object({
		status: z.enum(["not-started", "in-progress", "complete", "blocked"]),
		phase: z.number().int().positive(),
		updated: z.string().regex(/^\d{4}-\d{2}-\d{2}$/)
	}),
	goal: z.string().min(10),
	phases: z.array(PhaseSchema).min(1),
})

Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:10-45

Implementation State Machine

Plans and phases follow a strict state machine to prevent ambiguous progress tracking.

Rules require that only one phase may be [IN_PROGRESS] and exactly one task may have the ← CURRENT marker at any time.
Sources: workers/kdco-registry/files/skill/plan-protocol/SKILL.md:73-89

Code Review Methodology

The code-review skill provides a systematic approach across four distinct layers. The Reviewer agent is mandated to load this skill before reporting completion.

Review Layers

1. Correctness: Logic errors, edge cases, and type safety.
2. Security: Input validation, sanitization, and no hardcoded secrets.
3. Performance: Query patterns (N+1), caching, and memory leaks.
4. Style & Maintainability: Adherence to project conventions and complexity management.

Sources: workers/kdco-registry/files/skill/code-review/SKILL.md:14-35

Severity & Confidence

Findings must be classified by severity and meet a confidence threshold.

Severity	Icon	Criteria
Critical	🔴	Security vulnerabilities or crashes; Must fix before merge.
Major	🟠	Bugs or performance issues; Should fix.
Minor	🟡	Code smells or maintainability issues.
Nitpick	🟢	Style or naming suggestions; Optional.

Threshold: Only report findings with ≥80% confidence. Uncertain issues must be explicitly stated as such.
Sources: workers/kdco-registry/files/skill/code-review/SKILL.md:37-56

Instruction Injection via Plugins

The workspace-plugin dynamically injects rules based on the active agent. This is handled via the experimental.chat.system.transform hook.

Targeted Rule Sets

• PLAN_RULES: Strict boundaries between explore (internal files), researcher (external docs), and scribe (prose). It also mandates loading the plan-protocol skill.
• BUILD_RULES: Defines the orchestrator mandate, requiring the user to delegate all implementation to the coder and verification to specialists.
• Date Awareness: Injects the current date to prevent agents from using outdated training data for API lookups.

Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:316-465

Summary

Agent Skills & Instructions provide the governance layer for the OCX multi-agent system. By combining strict architectural laws (The 5 Laws), standardized planning protocols, and layered review methodologies, the system ensures that AI-generated code and documentation remain consistent, secure, and maintainable. Specialist agents like the coder and reviewer act as autonomous executors of these skills, while plugins like workspace-plugin serve as the enforcement mechanism for these behavioral constraints.