Summary
OpenSpec installs its workflows into each AI tool twice. It writes a skill and a tool-specific command file. We want to install skills only, using the Agent Skills standard (SKILL.md folders). The shared .agents/skills/ folder comes first wherever a tool reads it.
We audited all 49 tools OpenSpec supports. 48 of 49 already load Agent Skills. The only exception is Amazon Q Developer, which AWS is retiring.
This issue proposes a direction, not a fix. It lays out the audit, a phased plan, and what we still need to find out before we commit.
Why
- One format instead of 35. Today we keep 34 command adapters, each with its own file layout and syntax (Markdown, TOML, prefixed names). Every new tool means another adapter. Skills are one format that works everywhere.
- The ecosystem has moved. Skills used to be a Claude-only feature. Now nearly every coding agent supports them, and most read a shared
.agents/skills/ folder.
- Fewer files in user repos. A project set up for several tools gets one shared skills folder instead of a commands folder per tool.
- Adding a tool gets cheap. A tool that reads
.agents/skills/ needs no tool-specific code at all. The Universal target already proves this.
Where we are today
|
Count |
| Tools OpenSpec supports |
49 (plus the Universal .agents target) |
| Tools that get command files today |
34 |
| Tools that are already skills-only |
15 |
Default install (delivery) |
both: skills and commands |
Tools OpenSpec already points at .agents/skills |
5 (Amp, Antigravity, Codex, GSD, Zed) |
Users can already choose skills only (delivery: skills), so the building blocks exist. This proposal makes skills only the default, and later the only option.
Audit: Agent Skills support per tool
Checked against official docs, changelogs and source code on 2026-10-01.
| Group |
Tools |
Install target |
✅ Reads project .agents/skills/ (30) |
Amp, Antigravity, Auggie, Code Studio, Codex, Command Code, CoStrict, Crush, Cursor, DeepSeek Harness, Devin Desktop, Factory Droid, Gemini CLI, GitHub Copilot, GSD, Junie, Kilo Code, Kimi Code, MiniMax Code, Mistral Vibe, Oh My Pi, OpenCode, Pi, Qwen Code, Rovo Dev CLI, SourceCraft, Warp, Zed Agent, ZCode, Zoo Code |
.agents/skills/ |
| ⚠️ Partial or unclear (5) |
ForgeCode, Grok Build (both read only the user ~/.agents/skills), Hermes Agent (needs trust or config), Lingma (changelog and docs disagree), Veai (reads other tools' folders, .agents not named) |
Own folder for now |
| 📁 Skills in own folder only (13) |
AtomCode, Claude Code, Cline, CodeArts, CodeBuddy, Continue, EasyCode, GigaCode, IBM Bob, iFlow, Kiro, Qoder, Trae |
.<tool>/skills/ |
| ❌ No skills support (1) |
Amazon Q Developer |
None (Kiro replaces it) |
Full table (49 tools)
| Tool |
Gets commands today |
Reads .agents/skills |
Native skills folder |
Notes |
| Amazon Q Developer |
Yes |
❌ No skills |
none |
IDE plugin reads rules only. End of support 2027-04-30, replaced by Kiro |
| Amp |
No |
✅ |
.agents/skills |
|
| Antigravity |
Yes |
✅ project only |
.agents/skills |
Legacy .agent/skills still works |
| AtomCode |
Yes |
📁 |
.atomcode/skills |
|
| Auggie |
Yes |
✅ |
.augment/skills |
.agents has the lowest precedence |
| IBM Bob |
Yes |
📁 |
.bob/skills |
|
| Claude Code |
Yes |
📁 |
.claude/skills |
Request to read .agents closed as not planned |
| Cline |
Yes |
📁 |
.cline/skills |
Open bug: .agents/skills not loaded |
| Command Code |
Yes |
✅ |
.commandcode/skills |
Compatibility path |
| CodeArts |
No |
📁 |
.codeartsdoer/skills |
|
| Codex |
No |
✅ |
.agents/skills |
Native folder |
| DeepSeek Harness |
No |
✅ |
.dsh/skills |
|
| Devin Desktop |
Yes |
✅ |
.devin/skills |
|
| ForgeCode |
No |
⚠️ user only |
.forge/skills |
|
| CodeBuddy Code |
Yes |
📁 |
.codebuddy/skills |
|
| Code Studio |
Yes |
✅ |
.codestudio/skills |
Rebrand to BoldCreate (.boldcreate) in progress |
| Continue |
Yes |
📁 |
.continue/skills |
Also reads .claude/skills |
| CoStrict |
Yes |
✅ |
.roo/skills |
We write .cospec, which it never reads for skills |
| Crush |
Yes |
✅ |
.crush/skills |
|
| Cursor |
Yes |
✅ |
.cursor/skills |
|
| EasyCode |
Yes |
📁 |
.easycode/skills |
User folder is ~/.easycode-user/skills |
| Factory Droid |
Yes |
✅ |
.factory/skills |
Docs label .agents as "legacy" |
| Gemini CLI |
Yes |
✅ |
.gemini/skills |
|
| GitHub Copilot |
Yes |
✅ |
.github/skills |
|
| GigaCode |
Yes |
📁 |
.gigacode/skills |
|
| Grok Build |
No |
⚠️ user only |
.grok/skills |
|
| GSD |
No |
✅ |
.agents/skills |
Only folder |
| Hermes Agent |
No |
⚠️ trust or config |
.hermes/skills |
|
| iFlow |
Yes |
📁 |
.iflow/skills |
|
| Junie |
Yes |
✅ |
.junie/skills |
|
| Kilo Code |
Yes |
✅ |
.kilo/skills |
Legacy .kilocode/skills still loads |
| Kimi Code |
No |
✅ |
.kimi-code/skills |
|
| Kiro |
Yes |
📁 |
.kiro/skills |
|
| Lingma |
Yes |
⚠️ conflicting |
.lingma/skills |
|
| MiniMax Code |
No |
✅ |
.minimax/skills |
OpenSpec installs globally today |
| Mistral Vibe |
No |
✅ trusted folders |
.vibe/skills |
|
| Oh My Pi |
Yes |
✅ |
.omp/skills |
|
| OpenCode |
Yes |
✅ |
.opencode/skills |
|
| Pi |
Yes |
✅ trust prompt |
.pi/skills |
|
| SourceCraft |
Yes |
✅ |
.codeassistant/skills |
|
| Qoder |
Yes |
📁 |
.qoder/skills |
|
| Qwen Code |
Yes |
✅ source only |
.qwen/skills |
Docs out of date |
| Rovo Dev CLI |
No |
✅ |
.rovodev/skills |
|
| Zoo Code |
Yes |
✅ source only |
.roo/skills |
Upstream Roo Code never added it |
| Trae |
Yes |
📁 |
.trae/skills |
|
| Veai |
No |
⚠️ maybe |
.veai/skills |
|
| Warp |
No |
✅ recommended |
.agents/skills |
|
| Zed Agent |
No |
✅ |
.agents/skills |
Only folder |
| ZCode |
Yes |
✅ source only |
.zcode/skills |
Docs out of date |
Proposed direction
Where skills get installed
.agents/skills/ when the tool reads it at project level..<tool>/skills/ when the tool only reads its own folder.- The user-level folder only when a tool has no project folder.
When a user picks several tools that all read .agents/skills/, OpenSpec writes one copy.
Phased rollout
| Phase |
What changes |
What users see |
| Now (minor) |
Fix the bugs below. Test unclear tools by hand. |
Nothing changes |
| Next major |
Default becomes skills only. Commands still work as an opt-in and show a deprecation notice. |
New installs get skills. Existing users get a notice and a migration path |
| Later (timing TBD) |
Decide whether to remove command generation, based on feedback and usage |
To be decided |
We are not proposing to remove commands in the next major. We deprecate them there and keep them working until we have a removal plan we're confident in.
Problems the audit found today
These are bugs whatever we decide here:
- CoStrict: we write skills to
.cospec/, which CoStrict never reads for skills. It reads .roo/skills and .agents/skills.
- Amazon Q Developer:
.amazonq/skills loads nowhere. The product is being retired in favor of Kiro.
- Hermes: our setup note says Hermes only loads
~/.hermes/skills, but its docs now say it scans project folders too.
Open questions and unknowns
User experience
- How do users trigger a workflow? Users run commands like
/opsx:propose today. Each tool triggers skills differently: some by slash name, some by $name, some only automatically. We need a per-tool answer before dropping commands.
- The names change. Skill names (
openspec-propose) differ from command names (opsx:propose). Docs, tutorials and muscle memory all use the command spelling.
- Do commands do anything skills can't? For example, argument passing or tool-specific front matter. We should list any gaps.
Install behavior
- Duplicates. Many tools read both
.agents/skills and their own folder. Upgraded projects could load the same skill twice, with tool-specific precedence deciding which copy wins.
- Trust gates. Pi, Mistral Vibe and Hermes only read
.agents/skills in trusted folders. Will first-run users think the install failed?
- Cleanup on upgrade. How do we remove old command files safely without touching files the user edited?
Evidence gaps
- Support found only in source, not docs: Qwen Code, Zoo Code and ZCode. Lingma's docs contradict each other. Veai and Trae are unclear. We should test these by hand.
.agents is not formally standardized. agentskills.io defines the SKILL.md format but no canonical folder. Factory already calls .agents "legacy" and Claude Code declined it. What happens if a tool drops it?- Tool churn. Code Studio is mid-rebrand and Amazon Q is being retired. How do we keep this audit current?
Release
- Removal criteria. What tells us it's safe to remove commands entirely? Usage data, open issues, a fixed number of releases?
- Amazon Q users. Do we drop the target, point those users to Kiro, or keep commands for it only?
Out of scope
- Changing the content of OpenSpec's workflows.
- Changing how tools are detected during
openspec init.
- Implementation details. Those come in a change proposal once the open questions are answered.
Summary
OpenSpec installs its workflows into each AI tool twice. It writes a skill and a tool-specific command file. We want to install skills only, using the Agent Skills standard (
SKILL.mdfolders). The shared.agents/skills/folder comes first wherever a tool reads it.We audited all 49 tools OpenSpec supports. 48 of 49 already load Agent Skills. The only exception is Amazon Q Developer, which AWS is retiring.
This issue proposes a direction, not a fix. It lays out the audit, a phased plan, and what we still need to find out before we commit.
Why
.agents/skills/folder..agents/skills/needs no tool-specific code at all. The Universal target already proves this.Where we are today
.agentstarget)delivery)both: skills and commands.agents/skillsUsers can already choose skills only (
delivery: skills), so the building blocks exist. This proposal makes skills only the default, and later the only option.Audit: Agent Skills support per tool
Checked against official docs, changelogs and source code on 2026-10-01.
.agents/skills/(30).agents/skills/~/.agents/skills), Hermes Agent (needs trust or config), Lingma (changelog and docs disagree), Veai (reads other tools' folders,.agentsnot named).<tool>/skills/Full table (49 tools)
.agents/skills.agents/skills.agents/skills.agent/skillsstill works.atomcode/skills.augment/skills.agentshas the lowest precedence.bob/skills.claude/skills.agentsclosed as not planned.cline/skills.agents/skillsnot loaded.commandcode/skills.codeartsdoer/skills.agents/skills.dsh/skills.devin/skills.forge/skills.codebuddy/skills.codestudio/skills.boldcreate) in progress.continue/skills.claude/skills.roo/skills.cospec, which it never reads for skills.crush/skills.cursor/skills.easycode/skills~/.easycode-user/skills.factory/skills.agentsas "legacy".gemini/skills.github/skills.gigacode/skills.grok/skills.agents/skills.hermes/skills.iflow/skills.junie/skills.kilo/skills.kilocode/skillsstill loads.kimi-code/skills.kiro/skills.lingma/skills.minimax/skills.vibe/skills.omp/skills.opencode/skills.pi/skills.codeassistant/skills.qoder/skills.qwen/skills.rovodev/skills.roo/skills.trae/skills.veai/skills.agents/skills.agents/skills.zcode/skillsProposed direction
Where skills get installed
.agents/skills/when the tool reads it at project level..<tool>/skills/when the tool only reads its own folder.When a user picks several tools that all read
.agents/skills/, OpenSpec writes one copy.Phased rollout
We are not proposing to remove commands in the next major. We deprecate them there and keep them working until we have a removal plan we're confident in.
Problems the audit found today
These are bugs whatever we decide here:
.cospec/, which CoStrict never reads for skills. It reads.roo/skillsand.agents/skills..amazonq/skillsloads nowhere. The product is being retired in favor of Kiro.~/.hermes/skills, but its docs now say it scans project folders too.Open questions and unknowns
User experience
/opsx:proposetoday. Each tool triggers skills differently: some by slash name, some by$name, some only automatically. We need a per-tool answer before dropping commands.openspec-propose) differ from command names (opsx:propose). Docs, tutorials and muscle memory all use the command spelling.Install behavior
.agents/skillsand their own folder. Upgraded projects could load the same skill twice, with tool-specific precedence deciding which copy wins..agents/skillsin trusted folders. Will first-run users think the install failed?Evidence gaps
.agentsis not formally standardized. agentskills.io defines theSKILL.mdformat but no canonical folder. Factory already calls.agents"legacy" and Claude Code declined it. What happens if a tool drops it?Release
Out of scope
openspec init.