Agent vs Skill in OpenCode

Home

TL;DR

Agent = separate persona with its own model, tools, and prompt (like hiring a specialist)
Skill = knowledge injection into your current session (like handing yourself a cheat sheet)

Comparison

	Agent (`agents/*.md`)	Skill (`skills/*/SKILL.md`)
Execution	Separate conversation or subagent task	Loaded into current session context
Own model	Yes — specify any model (e.g., haiku, opus)	No — uses your current session model
Own tools	Yes — grant `read`, `edit`, `bash` individually	No — uses your current session tools
Mode	`primary` (takes over) or dispatched via Task	In-context injection via `skill` tool
Cost	Can use cheaper models for simple tasks	Same cost as your current model
State	Isolated — its own conversation history	Shared — part of your session
Structure	Single `.md` file with YAML frontmatter	Directory with `SKILL.md` + references/workflows
Complexity	Simple to write (one file)	Can be elaborate (multi-file knowledge base)

When to Use an Agent

Different model makes sense — tutoring with haiku, heavy reasoning with opus
Isolated persona — the task needs a distinct personality or behavioral mode
Conversational/interactive — Socratic tutoring, pair programming, interviews
Background work — dispatch via Task tool for parallel subagent execution
Budget control — route cheap tasks to cheap models automatically
Tool isolation — restrict what the persona can do (e.g., read-only researcher)

Agent Examples (from our setup)

c-tutor — Socratic C tutor using haiku, takes over conversation
python-tutor — Socratic Python tutor using haiku, takes over conversation

Agent Template

---
mode: primary           # or omit for subagent dispatch
description: Short description of what this agent does
prompt: |
  You are a [persona]. Your goal is to [objective].

  Core Philosophy:
  1. [Principle 1]
  2. [Principle 2]

  Process:
  - [Step 1]
  - [Step 2]
model: openrouter/anthropic/claude-3.5-haiku
temperature: 0.2
tools:
  read: true
  edit: true
  bash: true
permissions:
  edit: true
---

When to Use a Skill

Domain knowledge injection — n8n patterns, Rails conventions, security checklists
Workflow enforcement — TDD cycles, code review checklists, commit conventions
Reference material — API docs, best practices, error catalogs
Same model, smarter — you want expert behavior without spawning a new process
Multi-file knowledge — reference docs, templates, workflow guides that are too big for an agent prompt
Reusable across agents — skills can be loaded by any agent or the primary session

Skill Examples (from our setup)

n8n-code-javascript — JS patterns for n8n Code nodes
create-agent-skills — guide for building new skills
dhh-rails-style — Rails conventions reference
agent-browser — browser automation workflows

Skill Directory Structure

skills/my-skill/
  SKILL.md              # Required: main entry point with instructions
  references/           # Optional: knowledge files
    topic-a.md
    topic-b.md
  workflows/            # Optional: step-by-step procedures
    create-thing.md
  templates/            # Optional: starter files
    basic-template.md

Decision Flowchart

Need a different model? ─── YES ──→ Agent
        │
        NO
        │
Need isolated conversation? ─── YES ──→ Agent
        │
        NO
        │
Need to restrict tools? ─── YES ──→ Agent
        │
        NO
        │
Is it reference knowledge? ─── YES ──→ Skill
        │
        NO
        │
Is it a workflow/checklist? ─── YES ──→ Skill
        │
        NO
        │
Is it a persona that talks back? ─── YES ──→ Agent
        │
        NO
        │
Default to Skill (lighter weight)

Recommendations

For Language/Subject Tutors → Agent

Tutors are inherently conversational. They need their own persona, they benefit from a cheaper model for long back-and-forth sessions, and they take over the conversation. The Socratic method requires a separate “mind” asking questions.

For Coding Standards/Best Practices → Skill

These are reference material. You want your current model to follow Rails conventions or n8n patterns while doing its normal work. No need for a separate persona — just inject the knowledge.

For Code Review → Skill

A review checklist loaded as a skill lets your current session follow the checklist. You could also make an agent if you want a separate “reviewer persona” with a different model, but skill is the lighter default.

For Background Research → Agent (subagent mode)

Spawn a researcher agent via Task tool to do parallel work. It gets its own context window, its own tools, and returns results to you. Skills don’t run in parallel — they load into your session.

For Security/Audit Workflows → Skill

Multi-step security checklists with references to OWASP, CVE patterns, etc. These are large knowledge bases that benefit from the multi-file skill structure.

Hybrid Pattern: Skill + Agent

Load a skill into an agent’s prompt for maximum effect. For example, an agent that’s a “security auditor” persona running on a cheaper model, with a security skill loaded as its knowledge base. This gives you model isolation + rich domain knowledge.

File Locations

~/.config/opencode/
  agents/              # All agent definitions
    c-tutor.md
    python-tutor.md
  skills/              # All skill directories
    n8n-code-javascript/
      SKILL.md
      references/
      workflows/
    create-agent-skills/
      SKILL.md
      ...

Tags: OpencodeAgentsSkillsClaudeAutomation