opencode-agent-creator-skill: The Markdown Factory for Building Better Agents
A meta-skill that turns OpenCode into an agent-making system, with schemas, workflows, permission patterns, and self-audits instead of ad hoc prompts.
- This repo treats agent creation as a documentation problem, not a coding problem.
- Its real product is a workflow that turns freeform requests into schema-compliant, least-privilege agent files.
- The unusual bet is that Markdown, templates, and guardrails can act like a compiler when the runtime is an LLM.
- The design favors repeatability and auditability over cleverness, which is exactly what production AI tooling usually lacks.
A Skill That Writes Skills
The weird thing about opencode-agent-creator-skill is that it does not try to be a generator in the usual sense. It does not lean on a script to stamp out files. It uses Markdown, YAML frontmatter, and workflow documents to teach an LLM how to manufacture other agent definitions.
That makes the repo feel less like a tool and more like a process spec. The LLM is the runtime. The repository is the contract.
That is the thesis worth keeping in view. The project is not saying code is bad. It is saying that when the target system is already conversational and probabilistic, the safest generator may be a documented procedure with constraints, examples, and review steps.
The Architecture Is Documentation
The file tree is the product. SKILL.md acts as the orchestrator. templates/ holds reusable blueprints. references/ defines schema, tool policy, and anti-patterns. workflows/ describes the sequence of actions the LLM should follow when creating, auditing, or upgrading an agent.
That structure matters because there is no hidden application layer doing the hard work behind the curtain. The logic is expressed in documents the model can read and follow. In practice, the repo turns file organization into behavior.
SKILL.md
├─ templates/
│ ├─ db-admin.md
│ ├─ security-auditor.md
│ └─ ...
├─ references/
│ ├─ frontmatter-spec.md
│ ├─ permission-patterns.md
│ └─ anti-patterns.md
└─ workflows/
├─ create-new-agent.md
├─ audit-agent.md
└─ upgrade-agent.mdWhy Markdown Beats a Script Here
A script can generate files fast. A workflow can ask questions, interpret gaps, and adapt to nuance. That difference is the whole argument here.
| Approach | Strength | Weak spot | Best use |
|---|---|---|---|
| Ad hoc prompt-based agents | Quick to start | Drifts fast, hard to reproduce | Exploration and prototypes |
| Scripted code generation | Deterministic output | Rigid when requirements are fuzzy | Stable, narrow transforms |
| Documentation-driven workflow | Readable, auditable, adaptable | Depends on the model following instructions | Agent creation with context and policy |
The Guardrails: Context, Permissions, and Audit Loops
This is where the project stops being clever and starts looking mature. The research points to a context-first principle, strict frontmatter schema, permission patterns that prefer least privilege, and a self-correction loop that grades outputs against a rubric.
The point is not just safety. It is consistency. Open-ended agent creation tends to fail in the same ways: too many tools, vague behavior, inconsistent file formats, and hand-wavy instructions that are impossible to audit later.
This plugin adds an `agent-create` tool that lets the LLM create reusable, specialized agents without leaving your conversation.
That quote describes the broader category well. This repo’s twist is to make that creation path explicit, documented, and reviewable. Instead of trusting the model to improvise a good agent spec, it forces the model through a sequence: gather context, choose a template, apply schema, constrain tools, then audit the result.
| Guardrail | Unsafe pattern | Safer pattern |
|---|---|---|
| Context handling | Act on partial instructions | Pause and request missing details |
| Tool access | Give the agent broad defaults | Declare a narrow allow list |
| Schema | Let metadata drift | Use a fixed frontmatter shape with examples |
| Quality control | Accept first-pass output | Run an audit and self-correction loop |
What It Means to Build Professional-Grade Agents
The larger idea here is not about one repository. It is about what happens when teams stop treating agents like prompts and start treating them like artifacts. Artifacts have schemas. They have permissions. They have review steps. They have naming conventions and upgrade paths.
That shift matters because agent systems fail in organizational ways, not just technical ones. The problem is rarely that the model cannot write text. The problem is that no one has agreed on the shape of the text, who can invoke which tools, or how to tell if the output is safe enough to ship.
This repo answers with process. Not glamorous process. The kind that keeps things understandable when more people touch the system.
| Maturity signal | What it means |
|---|---|
| Templates as first-class assets | Reusable roles instead of one-off prompts |
| References as policy | Behavior is documented, not tribal |
| Workflows as state machines | Creation follows a predictable path |
| Audit loops | The system can correct itself before it is trusted |
