Week 5: Skills (On-Demand Knowledge)¶

Commands vs. Skills¶

Commands¶

You invoke them: /foo
User-initiated: You decide when to use.
Stored in: opencode.jsonc

Skills¶

Agent invokes them: Automatically, when relevant.
Agent-initiated: The agent decides based on your question.
Stored in: .opencode/skills/<name>/SKILL.md

The Mental Model¶

Command: "I'll type /test when I need tests."

Skill: "If the agent sees the word 'security,' it should load my security checklist."

Skills are automatic leverage.

Skill Anatomy¶

.opencode/skills/release-notes/SKILL.md

Every SKILL.md has:

YAML Frontmatter
name: folder name (lowercase, hyphens)
description: when to use it (this is the search index!)
Markdown Content
Templates, checklists, patterns
What the agent reads when it loads you

Frontmatter Example¶

---
name: release-notes
description: Use when the user asks to draft release notes,
  changelog, or version summary for a new release.
---

The description is CRITICAL. It's how agents find your skill.

Good vs. Bad Descriptions¶

Bad¶

description: Release notes skill

Too vague. Agent won't know when to use it.

Good¶

description: Use when the user asks to draft release notes,
  changelog, or version summary for a new release.

Includes triggers: "draft," "release notes," "changelog," "version."

Skill Content¶

After frontmatter, write actionable markdown:

Templates (what good output looks like)
Checklists (steps the agent should follow)
Patterns (example code or structure)
Tips (common pitfalls to avoid)

Agents read this and use it to do better work.

Discovery: How It Works¶

User asks:

"Write release notes for v2.0."

Agent: 1. Scans available skills 2. Finds release-notes (description matches!) 3. Loads the SKILL.md file 4. Reads templates and structure 5. Generates release notes that match your format

No explicit invocation. No /skill command. Just automatic help.

Skill Search Locations¶

OpenCode looks for skills in this order:

Project: .opencode/skills/<name>/SKILL.md
Global: ~/.config/opencode/skills/<name>/SKILL.md
Git tree: Upward from current directory

Once found, the agent loads the content.

Skills vs. Commands vs. AGENTS.md¶

Artifact	Triggered By	Use When
Skill	Agent auto-detects (via description)	Repeatable patterns, domain wisdom, templates
Command	User types `/foo`	Task you do 3+ times/week
AGENTS.md	Agent reads at startup	Global context (stack, conventions, build steps)

Decision Tree¶

Does the agent need to act automatically? → Yes: Skill

Does the user type the same command weekly? → Yes: Command

Is this global context everyone needs to know? → Yes: AGENTS.md

Common Mistakes¶

Vague description → Agent can't find it
No templates in content → Agent improvises badly
Folder name ≠ name field → Skill won't load
Too long (>1000 words) → Use AGENTS.md instead
Writing a skill for one task → Overkill; use a note

Demo: Release Notes Skill¶

User asks: "Draft release notes for v1.4."

Skill loads:

---
name: release-notes
description: Use when the user asks to draft release notes...
---

## Structure
1. Summary
2. New Features
3. Breaking Changes
4. Bug Fixes
5. Security
6. Contributors

## Template
# v1.4.0 – [DATE]
[See lesson for full template]

Agent outputs: Structured release notes matching your format.

Lab Preview¶

Lab 5.1: Write 2 Personal Skills¶

Pick 2 tasks relevant to your stack
Author skill files with good descriptions
Test that the agent finds them

Lab 5.2: Debug a Broken Skill¶

You'll see a skill with a bad description
Diagnose why the agent doesn't use it
Rewrite the description to fix it

Key Takeaway¶

Skills are leverage at scale.

Write once.
Any agent, any question discovers it automatically.
Your team gets smarter without extra docs or commands.

Next Week: Custom Agents¶

We'll build agents from scratch using opencode agent create.

Skills are how agents specialize. Agents are how you delegate.