opencode-learn

An OpenCode plugin that enables agents to capture knowledge through a learn tool with subtask-based skill creation workflow.

Installation

Add to your opencode.json:

{
"plugins": ["opencode-learn"]
}

Peer dependencies (install separately):

• @opencode-ai/plugin - OpenCode plugin API
• @spoons-and-mirrors/subtask2 - Subtask lifecycle management

{
"plugins": [
"opencode-learn",
"@spoons-and-mirrors/subtask2"
]
}

How it works

1. System prompt injection primes the agent to proactively use the learn tool
2. Agent calls learn tool with a topic and optional additional context
3. Temp context file created with topic + conversation context
4. /create-skill subtask invoked via subtask2 with return: directive
5. User confirms location (project-local or global)
6. Skill file created at .opencode/skills/<name>/SKILL.md or ~/.config/opencode/skills/<name>/SKILL.md

Learn Tool API

learn({topic: string,// Required: The concept to capturecontext?: string// Optional: Additional context to include})

Example

Agent: I discovered a useful pattern for handling React async errors.
Let me capture this knowledge...
[Calls learn tool with topic: "React async error handling with ErrorBoundary"]
[Temp file created: ~/.cache/opencode-learn/abc123.json]
[/create-skill subtask invoked]
[Agent: I suggest project-local location. Where should I create this skill?]
[User: Project-local]
[Skill created at .opencode/skills/react-async-error-handling/SKILL.md]

Skill File Structure

---name: skill-namedescription: Knowledge captured about <topic>---# Overview
What this skill enables and why it's useful
# When to Use
Trigger conditions and scenarios
# Prerequisites
Required setup, knowledge, or tools
# Implementation
Step-by-step guide or pattern description
# Examples
Concrete use cases with code if applicable
# Notes
Tips, caveats, and gotchas

When the agent uses it

The agent will call the learn tool when encountering:

• Reusable patterns and concepts
• Workflow optimizations
• Problem-solving approaches that worked well
• Configuration patterns for tools/frameworks
• Architecture decisions and rationale
• Debugging techniques
• Integration patterns between systems

Error Handling

• Invalid skill name: Validation error returned immediately
• Temp file write failure: Error returned with details
• User cancels: Subtask exits cleanly

License

MIT