How the OpenCode Skill Execution Model Functions in agent-skills

The OpenCode skill execution model in addyosmani/agent-skills automatically discovers, selects, and executes appropriate skills by detecting user intent and invoking the skill tool against structured SKILL.md files.

The addyosmani/agent-skills repository implements a skill-driven execution architecture that transforms natural language requests into structured development workflows. This OpenCode skill execution model eliminates manual slash commands by automatically mapping user intent to predefined skills stored in the skills/ directory, following strict lifecycle rules defined in AGENTS.md.

How the OpenCode Skill Execution Model Works

The execution model follows a six-step pipeline defined in AGENTS.md and docs/opencode-setup.md. Each step ensures that user requests translate into predictable, reproducible skill executions.

Step 1: Intent Detection

When a user submits a request, the agent scans the input to determine if any skill applies—even with minimal probability. According to AGENTS.md (lines 49-52), the system determines if any skill applies "even [with] 1% chance," ensuring broad pattern matching for feature requests, bug fixes, and other development tasks.

Step 2: Skill Discovery

All available skills reside in the skills/<skill-name>/SKILL.md structure. As documented in docs/opencode-setup.md (lines 48-55), the system discovers skills by reading markdown files from this directory tree. Each SKILL.md file contains the full specification for that skill's behavior and workflow.

Step 3: Automatic Skill Invocation

Once the agent identifies a matching skill, it automatically invokes the skill tool with the detected skill name. The opencode-setup.md documentation (lines 56-60) specifies that the agent must "Detect when a skill applies → Invoke the skill tool," handling the transition from intent recognition to execution without user intervention.

Step 4: Enforced Workflow Execution

Each skill enforces a strict lifecycle that the agent must follow. The AGENTS.md file (lines 51-53) mandates that agents "Follow the skill workflow strictly," ensuring standardized execution across different skill types. Workflows typically progress through phases like specification, planning, building, verification, review, and shipping.

Step 5: Lifecycle Mapping to Implicit Commands

The model maps implicit lifecycle commands to concrete skill implementations. As defined in AGENTS.md (lines 32-44), commands such as DEFINE, PLAN, BUILD, VERIFY, REVIEW, and SHIP automatically trigger specific skills like spec-driven-development or planning-and-task-breakdown. This mapping eliminates the need for users to remember specific slash commands.

Step 6: No Manual Command Requirements

Users never type explicit slash commands like /spec or /plan. The opencode-setup.md documentation (lines 73-74) emphasizes that "The user does not need to explicitly request skills," making the interface conversational rather than command-driven.

OpenCode Skill Execution Examples

The following examples demonstrate how the model processes different request types using the skill tool and enforced workflows.

Feature Development Request

When a user requests new functionality, the execution model automatically triggers the incremental implementation workflow.

User: Add authentication to this app

Agent execution flow:

1. Detect intent → Matches the feature pattern in AGENTS.md.
2. Select skill → Chooses incremental-implementation from the skills/ directory.
3. Run skill → Executes the skill tool, loading skills/incremental-implementation/SKILL.md.
4. Follow workflow → Progresses through spec → plan → implementation → tests → verification → review → ship.

Bug Fix Request

For debugging scenarios, the model selects appropriate recovery skills.

User: Fix the crash when opening settings

Agent execution flow:

1. Detects bug-fix intent from the natural language input.
2. Selects debugging-and-error-recovery from available skills.
3. Calls skill debugging-and-error-recovery via the built-in tool.
4. Executes the prescribed debugging workflow: reproduce → isolate → fix → test → verify.

Note: The actual skill calls are handled by OpenCode's built-in tool; no manual shell commands are required from the user.

Key Configuration Files

Understanding the OpenCode skill execution model requires familiarity with these specific files in the repository:

• AGENTS.md — Core definition of the OpenCode integration, containing intent-to-skill mapping rules and the execution model specification (lines 32-53).
• docs/opencode-setup.md — Practical implementation guide describing skill discovery mechanics and automatic invocation protocols (lines 48-74).
• skills/<skill-name>/SKILL.md — Individual skill specifications that the skill tool loads and executes (e.g., incremental-implementation, debugging-and-error-recovery).
• skills/<skill-name>/scripts/*.sh — Optional bash scripts implementing concrete actions for specific skills, such as test runners or build commands.

Summary

• The OpenCode skill execution model automatically bridges natural language requests and structured development workflows in the agent-skills repository.
• Intent detection runs continuously, checking if any skill applies to user input with even minimal probability.
• Skills are discovered from skills/<skill-name>/SKILL.md files and invoked automatically via the skill tool.
• The model enforces a strict workflow lifecycle (spec → plan → build → verify → review → ship) without requiring manual slash commands.
• Lifecycle mapping converts implicit commands like DEFINE and BUILD into concrete skill executions defined in AGENTS.md.

Frequently Asked Questions

How does OpenCode determine which skill to execute?

OpenCode scans user input to detect intent patterns defined in AGENTS.md, checking if any skill applies even with a minimal probability threshold. When a match is found, the agent automatically selects the corresponding skill from the skills/ directory and invokes it via the skill tool without requiring explicit user confirmation.

Are manual slash commands required to trigger skills?

No. According to docs/opencode-setup.md (lines 73-74), users do not need to explicitly request skills or type slash commands like /spec or /plan. The agent handles skill invocation automatically through the skill tool based on natural language intent detection.

What is the difference between AGENTS.md and individual SKILL.md files?

AGENTS.md defines the core execution model, intent detection rules, and lifecycle mapping for the OpenCode integration. Individual SKILL.md files (located in skills/<skill-name>/) contain the specific implementation details, workflows, and execution steps for each particular skill.

Can developers add custom skills to the OpenCode execution model?

Yes. Developers can create new directories under skills/<skill-name>/ containing a SKILL.md file and optional scripts in a scripts/ subdirectory. The automatic discovery mechanism described in docs/opencode-setup.md will detect these new skills as long as they follow the established directory structure and markdown format.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}