Proposal: use a standard `.agent/skills` folder for all agents that support it

[iki]

Here's the proposal of standard .agent/skills folder and growing list of agents that support it: agentskills/agentskills#15

[1code-async]

Task completed.

I wasn't able to post the comment due to GitHub permissions (Resource not accessible by integration). Below is the full comment I composed for issue #689:

---

Issue Analysis

The proposal at agentskills/agentskills#15 advocates for a standard .agent/skills/ (or .agents/skills/) directory that all AI agent frameworks would scan, eliminating the current fragmentation where each tool uses its own path.

Current Implementation

The codebase supports 22 AI tools, each with its own skillsDir configured in src/core/config.ts:20-42. Skills follow the pattern <projectRoot>/<skillsDir>/skills/<skillName>/SKILL.md, with the /skills/ suffix appended at runtime in src/core/shared/tool-detection.ts:72:

.claude/skills/<skillName>/SKILL.md    → Claude Code
.cursor/skills/<skillName>/SKILL.md    → Cursor
.github/skills/<skillName>/SKILL.md    → GitHub Copilot
.agent/skills/<skillName>/SKILL.md     → Antigravity (only tool currently using .agent/)
... (22 tools total)

Notably, Antigravity already uses .agent as its skillsDir (config.ts:22), so .agent/skills/ is already a recognized path — just scoped to one tool.

What Would Need to Change

1. src/core/config.ts — Add .agent (or .agents) as a universal path or fallback alongside tool-specific directories.
2. src/core/shared/tool-detection.ts — Update getToolSkillStatus() and getToolStates() to also scan a shared standard directory.
3. src/core/init.ts — InitCommand would need to optionally write skills to the standard directory.
4. src/core/update.ts — Update logic should handle skills in both standard and tool-specific locations.
5. Command adapters (src/core/command-generation/adapters/) — 22 adapter files would need awareness of the shared path.

Related Issues

Several existing issues touch on overlapping concerns:

• #20820 — Reserve skills/ for user-managed skills, relocate internal to system/
• #16345 — Support standard .github/skills/ directory
• #18621 — Add option to configure skills path
• #18212 — Support custom agents in .claude/agents/
• #20805 / #18192 / #10238 — Recursive skill discovery
• #13032 — Hierarchical skill tree loading

Design Considerations

A key decision would be whether to replace tool-specific directories, add .agent/skills/ as an additional scan path, or symlink from tool-specific paths — each with different trade-offs for backwards compatibility and multi-tool projects. The growing list of agents already adopting this convention (Amp, Goose, Codex, Gemini CLI, RooCode, Cursor, etc.) adds significant weight to standardization.

---

View full conversation

Powered by 1Code

[iki]

A key decision would be whether to replace tool-specific directories, add .agent/skills/ as an additional scan path, or symlink from tool-specific paths — each with different trade-offs for backwards compatibility and multi-tool projects. The growing list of agents already adopting this convention (Amp, Goose, Codex, Gemini CLI, RooCode, Cursor, etc.) adds significant weight to standardization.

I'm using symlinks to .agent/skills, but only from agents that still use it (while they are working on .agent/skills support), e.g. .github and .claude. For agents that already support it, symlink is not needed, e.g. .augment and .gemini.

The growing list of agents that support it can be tracked at the proposal issue link above

[casualuser]

A key decision would be whether to replace tool-specific directories, add .agent/skills/ as an additional scan path, or symlink from tool-specific paths — each with different trade-offs for backwards compatibility and multi-tool projects. The growing list of agents already adopting this convention (Amp, Goose, Codex, Gemini CLI, RooCode, Cursor, etc.) adds significant weight to standardization.

I'm using symlinks to .agent/skills, but only from agents that still use it (while they are working on .agent/skills support), e.g. .github and .claude. For agents that already support it, symlink is not needed, e.g. .augment and .gemini.

The growing list of agents that support it can be tracked at the proposal issue link above

can we get this symlink behaviour/option implemented and available?

doing the same manually and bored with it a bit
can you share with me your solution if you automated it and tested?

[jim60105]

Just a reminder, the widely supported one is .agents/skills, not .agent/skills.

[EthraZa]

I just made a test and find out that Antigravity (1.20.6) and Gemini-cli (0.35.0) both look at .agents/ (plural) folder.
Only Antigravity look at .agent/ (singular) folder and only Gemini cli look at .gemini/ folder.

I found out too that, if I use .agents/ (plural) since it looks like the real standard, the openspec cli (1.2.0) does not identify it as an installation folder. It identify only .agent/ (singular) for Antigravity and only .gemini/ for Gemini cli.

[barisgit]

Any progress on this? .agents/skills is becoming canonical (both in project scope and global ~/.agents/skills scope). By using this except for special cases (like claude code that refuses to follow any standard) this should work for most agents.

[CKGrafico]

Looks like the best option would be to include at least a “Global” choice (or something similar) in the selection list.

[clay-good]

This is now implemented, using the plural .agents/skills convention that the discussion converged on, so I’m closing the proposal as completed.

Merged implementation: #1303, commit 1aa0f2abfc19f2487f5b8566e6eb3bf15f41c20a: #1303

What is available on current main:

openspec init --tools agents

This installs the active OpenSpec workflow skills under:

.agents/skills/openspec-*/SKILL.md

It is intentionally a shared, vendor-neutral, skills-only target. It does not replace tool-specific integrations and does not create cross-vendor command files, because command formats differ between tools.

Proof in the current repository:

• The agents target is enabled with skillsDir: '.agents' and detection scoped to .agents/skills:

  OpenSpec/src/core/config.ts

  Lines 57 to 64 in 45cca5d

  	// Vendor-neutral target for assistants that read the shared `.agents` root.
  	// Detection keys off `.agents/skills` rather than the bare root: frameworks use
  	// `.agents/` for more than skills, so the root alone says nothing about skills.
  	// A project that does keep skills there is a project this target fits, the same
  	// way `.claude/` selects Claude Code — the signal is the user's setup, not
  	// OpenSpec's own files.
  	{ name: 'Shared .agents skills', value: 'agents', available: true, successLabel: 'shared .agents skills', skillsDir: '.agents', detectionPaths: ['.agents/skills'] }
  	];

• The supported-tools guide documents the generated path:

  OpenSpec/docs/supported-tools.md

  Lines 99 to 102 in 45cca5d

  	| Trae (`trae`) | `.trae/skills/openspec-*/SKILL.md` | `.trae/commands/opsx-<id>.md` |
  	| ZCode (`zcode`) | `.zcode/skills/openspec-*/SKILL.md` | `.zcode/commands/opsx/<id>.md` |
  	| Shared `.agents` skills (`agents`) | `.agents/skills/openspec-*/SKILL.md` | Not generated (no command adapter; use skill-based `/openspec-*` invocations) |

• The guide explains when to choose the shared target instead of a tool-specific one:

  OpenSpec/docs/supported-tools.md

  Lines 109 to 137 in 45cca5d

  	### When to pick the shared `.agents` target
  	`agents` is the vendor-neutral option: it writes skills to `.agents/skills/`, the
  	shared root many agent tools read, instead of a tool-specific directory.
  	| Situation | Pick |
  	|-----------|------|
  	| Your tool has its own row above | Its own ID — you get that tool's integration, including slash commands where it supports them |
  	| Several agents on one repo, all reading `.agents/skills` | `agents` — one skill tree instead of one per tool |
  	| Your tool isn't listed yet but reads `.agents/skills` | `agents` |
  	Selecting it alongside a tool-specific ID is fine; each writes to its own root.
  	OpenSpec also offers it automatically once a project has a `.agents/skills/`
  	directory — a bare `.agents/` is not enough, since tools use that root for rules
  	and subagent definitions too. Note `.agents` is not `.agent`: the singular
  	directory belongs to Antigravity.
  	Two things to know:
  	- **Skills only.** No command adapter exists, so no `opsx-*` command files are
  	written; with a commands-inclusive delivery mode `openspec init` lists `agents`
  	among the tools it reports under `Commands skipped for: … (no adapter)`.
  	Invoke the workflows by skill name —
  	most assistants that read `.agents/skills` spell that `/openspec-propose`, the form
  	OpenSpec's setup hint prints. The target is vendor-neutral, so check your
  	assistant's own docs if it uses another form.
  	- **No `AGENTS.md` is created or edited.** The target is the `.agents/` directory.
  	If your root `AGENTS.md` still carries OpenSpec marker blocks from an older
  	version, `openspec update` strips them — see the [Migration Guide](migration-guide.md).

I reran the focused CLI and init coverage on current main; the shared-target cases pass. A live initialization produces Created: Shared .agents skills, writes the expected skill tree, and reports commands as skipped because no universal command adapter exists.

Thanks for raising this early and for the follow-up discussion that clarified .agents plural as the convention to implement.