packages/web/src/content/docs/tools.mdx 215:### skill 217:Load a [skill](/docs/skills) (a `SKILL.md` file) and return its content in the conversation. 223: "skill": "allow" packages/web/src/content/docs/skills.mdx 2:title: "Agent Skills" 3:description: "Define reusable behavior via SKILL.md definitions" 6:Agent skills let OpenCode discover reusable instructions from your repo or home directory. 7:Skills are loaded on-demand via the native `skill` tool—agents see available skills and can load the full content when needed. 13:Create one folder per skill name and put a `SKILL.md` inside it. 16:- Project config: `.opencode/skill//SKILL.md` 17:- Global config: `~/.config/opencode/skill//SKILL.md` 18:- Project Claude-compatible: `.claude/skills//SKILL.md` 19:- Global Claude-compatible: `~/.claude/skills//SKILL.md` 26:It loads any matching `skill/*/SKILL.md` in `.opencode/` and any matching `.claude/skills/*/SKILL.md` along the way. 28:Global definitions are also loaded from `~/.config/opencode/skill/*/SKILL.md` and `~/.claude/skills/*/SKILL.md`. 34:Each `SKILL.md` must start with YAML frontmatter. 55:- Match the directory name that contains `SKILL.md` 74:Create `.opencode/skill/git-release/SKILL.md` like this: 103:OpenCode lists available skills in the `skill` tool description. 104:Each entry includes the skill name and description: 107: 108: 111: 112: 115:The agent loads a skill by calling the tool: 118:skill({ name: "git-release" }) 125:Control which skills agents can access using pattern-based permissions in `opencode.json`: 130: "skill": { 142:| `allow` | Skill loads immediately | 143:| `deny` | Skill hidden from agent, access rejected | 159: skill: 171: "skill": { 182:## Disable the skill tool 184:Completely disable skills for agents that shouldn't use them: 191: skill: false 202: "skill": false 209:When disabled, the `` section is omitted entirely. 215:If a skill does not show up: 217:1. Verify `SKILL.md` is spelled in all caps 219:3. Ensure skill names are unique across all locations 220:4. Check permissions—skills with `deny` are hidden from agents packages/web/src/content/docs/permissions.mdx 93:- `skill` — loading a skill (matches the skill name) packages/web/src/content/docs/ecosystem.mdx 38:| [opencode-skillful](https://github.com/zenobi-us/opencode-skillful) | Allow OpenCode agents to lazy load prompts on demand with skill discovery and injection | packages/web/src/content/docs/cli.mdx 569:| `OPENCODE_DISABLE_CLAUDE_CODE` | boolean | Disable reading from `.claude` (prompt + skills) | 571:| `OPENCODE_DISABLE_CLAUDE_CODE_SKILLS` | boolean | Disable loading `.claude/skills` | packages/web/astro.config.mjs 81: "skills", packages/opencode/test/skill/skill.test.ts 2:import { Skill } from "../../src/skill" 8:async function createGlobalSkill(homeDir: string) { 9: const skillDir = path.join(homeDir, ".claude", "skills", "global-test-skill") 10: await fs.mkdir(skillDir, { recursive: true }) 12: path.join(skillDir, "SKILL.md"), 14:name: global-test-skill 15:description: A global skill from ~/.claude/skills for testing. 18:# Global Test Skill 20:This skill is loaded from the global home directory. 25:test("discovers skills from .opencode/skill/ directory", async () => { 29: const skillDir = path.join(dir, ".opencode", "skill", "test-skill") 31: path.join(skillDir, "SKILL.md"), 33:name: test-skill 34:description: A test skill for verification. 37:# Test Skill 48: const skills = await Skill.all() 49: expect(skills.length).toBe(1) 50: const testSkill = skills.find((s) => s.name === "test-skill") 51: expect(testSkill).toBeDefined() 52: expect(testSkill!.description).toBe("A test skill for verification.") 53: expect(testSkill!.location).toContain("skill/test-skill/SKILL.md") 58:test("discovers multiple skills from .opencode/skill/ directory", async () => { 62: const skillDir1 = path.join(dir, ".opencode", "skill", "skill-one") 63: const skillDir2 = path.join(dir, ".opencode", "skill", "skill-two") 65: path.join(skillDir1, "SKILL.md"), 67:name: skill-one 68:description: First test skill. 71:# Skill One 75: path.join(skillDir2, "SKILL.md"), 77:name: skill-two 78:description: Second test skill. 81:# Skill Two 90: const skills = await Skill.all() 91: expect(skills.length).toBe(2) 92: expect(skills.find((s) => s.name === "skill-one")).toBeDefined() 93: expect(skills.find((s) => s.name === "skill-two")).toBeDefined() 98:test("skips skills with missing frontmatter", async () => { 102: const skillDir = path.join(dir, ".opencode", "skill", "no-frontmatter") 104: path.join(skillDir, "SKILL.md"), 116: const skills = await Skill.all() 117: expect(skills).toEqual([]) 122:test("discovers skills from .claude/skills/ directory", async () => { 126: const skillDir = path.join(dir, ".claude", "skills", "claude-skill") 128: path.join(skillDir, "SKILL.md"), 130:name: claude-skill 131:description: A skill in the .claude/skills directory. 134:# Claude Skill 143: const skills = await Skill.all() 144: expect(skills.length).toBe(1) 145: const claudeSkill = skills.find((s) => s.name === "claude-skill") 146: expect(claudeSkill).toBeDefined() 147: expect(claudeSkill!.location).toContain(".claude/skills/claude-skill/SKILL.md") 152:test("discovers global skills from ~/.claude/skills/ directory", async () => { 159: await createGlobalSkill(tmp.path) 163: const skills = await Skill.all() 164: expect(skills.length).toBe(1) 165: expect(skills[0].name).toBe("global-test-skill") 166: expect(skills[0].description).toBe("A global skill from ~/.claude/skills for testing.") 167: expect(skills[0].location).toContain(".claude/skills/global-test-skill/SKILL.md") 175:test("returns empty array when no skills exist", async () => { 181: const skills = await Skill.all() 182: expect(skills).toEqual([]) packages/opencode/test/preload.ts 15:// This prevents tests from picking up real user configs/skills from ~/.claude/skills packages/opencode/src/tool/skill.ts 4:import { Skill } from "../skill" 9: name: z.string().describe("The skill identifier from available_skills (e.g., 'code-review' or 'category/helper')"), 12:export const SkillTool = Tool.define("skill", async (ctx) => { 13: const skills = await Skill.all() 15: // Filter skills by agent permissions if agent provided 17: const accessibleSkills = agent 18: ? skills.filter((skill) => { 19: const rule = PermissionNext.evaluate("skill", skill.name, agent.permission) 22: : skills 25: accessibleSkills.length === 0 26: ? "Load a skill to get detailed instructions for a specific task. No skills are currently available." 28: "Load a skill to get detailed instructions for a specific task.", 29: "Skills provide specialized knowledge and step-by-step guidance.", 30: "Use this when a task matches an available skill's description.", 31: "", 32: ...accessibleSkills.flatMap((skill) => [ 33: ` `, 34: ` ${skill.name}`, 35: ` ${skill.description}`, 36: ` `, 38: "", 45: const skill = await Skill.get(params.name) 47: if (!skill) { 48: const available = await Skill.all().then((x) => Object.keys(x).join(", ")) 49: throw new Error(`Skill "${params.name}" not found. Available skills: ${available || "none"}`) 53: permission: "skill", 58: // Load and parse skill content 59: const parsed = await ConfigMarkdown.parse(skill.location) 60: const dir = path.dirname(skill.location) 63: const output = [`## Skill: ${skill.name}`, "", `**Base directory**: ${dir}`, "", parsed.content.trim()].join("\n") 66: title: `Loaded skill: ${skill.name}`, 69: name: skill.name, packages/opencode/src/tool/registry.ts 13:import { SkillTool } from "./skill" 109: SkillTool, packages/opencode/src/skill/skill.ts 12:export namespace Skill { 13: const log = Log.create({ service: "skill" }) 22: "SkillInvalidError", 31: "SkillNameMismatchError", 39: const OPENCODE_SKILL_GLOB = new Bun.Glob("{skill,skills}/**/SKILL.md") 40: const CLAUDE_SKILL_GLOB = new Bun.Glob("skills/**/SKILL.md") 43: const skills: Record = {} 45: const addSkill = async (match: string) => { 54: // Warn on duplicate skill names 55: if (skills[parsed.data.name]) { 56: log.warn("duplicate skill name", { 58: existing: skills[parsed.data.name].location, 63: skills[parsed.data.name] = { 70: // Scan .claude/skills/ directories (project-level) 78: // Also include global ~/.claude/skills/ 84: if (!Flag.OPENCODE_DISABLE_CLAUDE_CODE_SKILLS) { 87: CLAUDE_SKILL_GLOB.scan({ 95: log.error("failed .claude directory scan for skills", { dir, error }) 100: await addSkill(match) 105: // Scan .opencode/skill/ directories 107: for await (const match of OPENCODE_SKILL_GLOB.scan({ 113: await addSkill(match) 117: return skills packages/opencode/src/skill/index.ts 1:export * from "./skill" packages/opencode/src/flag/flag.ts 19: export const OPENCODE_DISABLE_CLAUDE_CODE_SKILLS = 20: OPENCODE_DISABLE_CLAUDE_CODE || truthy("OPENCODE_DISABLE_CLAUDE_CODE_SKILLS") packages/opencode/src/session/compaction.ts 44: const PRUNE_PROTECTED_TOOLS = ["skill"] packages/opencode/src/cli/cmd/debug/skill.ts 2:import { Skill } from "../../../skill" 6:export const SkillCommand = cmd({ 7: command: "skill", 8: describe: "list all available skills", 12: const skills = await Skill.all() 13: process.stdout.write(JSON.stringify(skills, null, 2) + EOL) packages/opencode/src/cli/cmd/debug/index.ts 9:import { SkillCommand } from "./skill" 23: .command(SkillCommand)