Skip to content
Hands-on Coding Assistants

Part 4 — Build the Harness Chapter 20

Agent Skills & Modular Expertise

In this chapter

A command works when you already know which prompt to run. A skill makes a procedure available for the agent to load when the task calls for it. In this exercise the procedure is to turn a feature request into a spec without quietly filling in product decisions.

Start a fresh branch from lab-start. In a Plan session, ask for a draft for this request.

A user wants to download their tasks to open in a spreadsheet.
Draft a Task API feature spec. Identify what still needs a decision.

Save the answer in your exercise notes. There is no checked-in spec for that feature. File format, columns, and records included in the export are still choices the owner needs to make.

Add the procedure

Create .opencode/skills/spec-writer/SKILL.md. The name and description advertise it to the model. The body is loaded when the skill is selected.

---
name: spec-writer
description: Draft a Task API feature spec with observable criteria and explicit open decisions.
---

Read the feature request and the relevant route in src/app.ts.
Return a draft with Goal, Acceptance criteria, Verification, and
Open questions. Under Verification, give a concrete input and
expected outcome for each decided criterion. Ask about the visible
effect of rejection wherever the feature can change stored state.
Leave unanswered product decisions in Open questions.

Start a new Plan session with the same model. Submit the same task with Use @spec-writer. at the beginning. Inspect the tool activity for a completed skill call with ID spec-writer. Compare the two drafts. Is the new one clear about what a caller can observe? Did it decide on CSV without being asked? The activity tells you whether OpenCode loaded the skill. The answer tells you whether the loaded procedure was useful.

Check the permission boundary

Add this last rule to the permissions array for one test session.

{ "action": "skill", "resource": "spec-writer", "effect": "deny" }

Open a fresh session and try the skill again. The skill should be unavailable to that agent or the attempt should be denied. It can still answer from the prompt and files it sees. Look for a successful load before crediting the skill with the result. Remove the denial when you finish and confirm the skill loads again.

Review the text and any scripts or resources a skill would ask the agent to use before sharing it. Keep the skill in this repository while its procedure depends on the Task API.

References

  • OpenCode maintainers. Skills, including loading. Official OpenCode 2 documentation for skill discovery, loading, and permission checks.