HARNESSES.md

 1# Harness Skills Capabilities Reference
 2
 3Source of truth for what each AI coding harness supports in terms of agent skills.
 4Used to inform provider configs in `scripts/lib/transformers/providers.js`.
 5
 6Last verified: 2026-04-28
 7
 8## Official Documentation
 9
10| Harness | Docs URL |
11|---------|----------|
12| Claude Code | https://code.claude.com/docs/en/skills |
13| Cursor | https://cursor.com/docs/context/skills |
14| Gemini CLI | https://geminicli.com/docs/cli/skills/ |
15| Codex CLI | https://developers.openai.com/codex/skills |
16| GitHub Copilot (Agents) | https://code.visualstudio.com/docs/copilot/customization/agent-skills |
17| Kiro | https://kiro.dev/docs/skills/ |
18| OpenCode | https://opencode.ai/docs/skills/ |
19| Pi | https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/skills.md |
20| Qoder | https://docs.qoder.com/extensions/skills |
21| Trae | TBD (no official skills docs found yet) |
22| Rovo Dev | https://support.atlassian.com/rovo/docs/extend-rovo-dev-cli-with-agent-skills |
23
24## Spec Compliance
25
26All harnesses follow the [Agent Skills specification](https://agentskills.io/specification) to varying degrees. The spec defines these frontmatter fields: `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`.
27
28Provider-specific extensions beyond the spec: `user-invocable`, `argument-hint`, `disable-model-invocation`, `allowed-tools` (extended syntax), `model`, `effort`, `context`, `agent`, `hooks`, `subtask`, `mcp`.
29
30## Frontmatter Support
31
32Fields marked with * are spec-standard. Others are provider extensions.
33
34| Field | Claude Code | Cursor | Gemini | Codex | Copilot | Kiro | OpenCode | Pi | Qoder | Rovo Dev |
35|-------|:-----------:|:------:|:------:|:-----:|:-------:|:----:|:--------:|:--:|:-----:|:--------:|
36| `name`* | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
37| `description`* | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
38| `license`* | Yes | Yes | Ignored | No | Yes | Yes | Yes | Yes | Yes | Yes |
39| `compatibility`* | Yes | Yes | Ignored | No | Yes | Yes | Yes | Yes | Yes | Yes |
40| `metadata`* | Yes | Yes | Ignored | No | Yes | Yes | Yes | Yes | Yes | Yes |
41| `allowed-tools`* | Yes | No | Ignored | No | No | No | Yes | Yes | Yes | Yes |
42| `user-invocable` | Yes | No | No | No | Yes | No | Yes | No | Yes | Yes |
43| `argument-hint` | Yes | No | No | No | Yes | No | Yes | No | Yes | Yes |
44| `disable-model-invocation` | Yes | Yes | No | No | Yes | No | Yes | Yes | TBD | TBD |
45| `model` | Yes | No | No | No | No | No | Yes | No | No | No |
46| `effort` | Yes | No | No | No | No | No | No | No | No | No |
47| `context` | Yes | No | No | No | No | No | No | No | No | No |
48| `agent` | Yes | No | No | No | No | No | Yes | No | No | No |
49| `hooks` | Yes | No | No | No | No | No | No | No | No | No |
50
51Notes:
52- Gemini CLI validates only `name` and `description`; other spec fields are parsed but ignored.
53- Codex CLI uses a separate `agents/openai.yaml` sidecar for skill metadata (icons, branding, MCP tools, invocation control). Native Codex custom agents are separate TOML files under `.codex/agents/` or `~/.codex/agents/`.
54- Kiro recognizes `user-invocable` and `disable-model-invocation` per community reports but does not formally document them.
55- Unknown fields are silently ignored by all harnesses.
56
57## Skill Directory Structure
58
59| Harness | Native directory | Also reads |
60|---------|-----------------|------------|
61| Claude Code | `.claude/skills/` | - |
62| Cursor | `.cursor/skills/` | `.agents/skills/`, `.claude/skills/` |
63| Gemini CLI | `.gemini/skills/` | `.agents/skills/` |
64| Codex CLI | `.agents/skills/` (primary) | - |
65| GitHub Copilot | `.github/skills/` | `.agents/skills/`, `.claude/skills/` |
66| Kiro | `.kiro/skills/` | - |
67| OpenCode | `.opencode/skills/` | `.agents/skills/`, `.claude/skills/` |
68| Pi | `.pi/skills/` | `.agents/skills/` |
69| Qoder | `.qoder/skills/` | `~/.qoder/skills/` (user-level) |
70| Trae China | `.trae-cn/skills/` | TBD |
71| Trae International | `.trae/skills/` | TBD |
72| Rovo Dev | `.rovodev/skills/` | `~/.rovodev/skills/` (user-level) |
73
74All harnesses support the `{skill-name}/SKILL.md` directory structure with optional `reference/`, `scripts/`, and `assets/` subdirectories.
75
76## Native Subagent Directory Structure
77
78| Harness | Native directory | File format |
79|---------|------------------|-------------|
80| Claude Code | `.claude/agents/` | Markdown with YAML frontmatter |
81| Codex CLI | `.codex/agents/` | TOML |
82
83Impeccable keeps canonical agent prompts under `skill/agents/` and emits provider-native files only for harnesses with documented subagent formats.
84
85## Placeholder / Variable Substitution
86
87Claude Code supports runtime variable substitution directly in SKILL.md bodies: `$ARGUMENTS`, `$0`-`$N`, `${CLAUDE_SKILL_DIR}`, `${CLAUDE_SESSION_ID}`. No other harness supports substitution in skills.
88
89Some harnesses have separate "custom commands" systems (distinct from skills) with their own substitution:
90
91| Harness | Command system | Substitution syntax |
92|---------|---------------|-------------------|
93| Gemini CLI | `.gemini/commands/` (TOML) | `{{args}}`, `!{shell}`, `@{file}` |
94| Codex CLI | `.codex/prompts/` | `$ARGNAME` |
95| OpenCode | `.opencode/commands/` | `$ARGUMENTS`, `$1`-`$N`, `` !`shell` `` |
96
97Our build system handles cross-provider placeholders at compile time via `replacePlaceholders()` for `{{model}}`, `{{config_file}}`, `{{ask_instruction}}`, and `{{available_commands}}`.