From 2be4a38e3652b99d74af2b7b539e351686dd8c56 Mon Sep 17 00:00:00 2001 From: Aaron Stainback Date: Fri, 24 Apr 2026 09:10:07 -0400 Subject: [PATCH] =?UTF-8?q?doc:=20cross-harness=20skill-discovery=20?= =?UTF-8?q?=E2=80=94=20verified-not-assumed=20+=20behaviour/data=20split?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The prior Gemini capability map claimed `.agents/skills/` was a cross-harness alias shared by Claude Code + Codex + Gemini. The human maintainer flagged that the factory had earlier problems with skills outside each harness's canonical home and asked for a direct test before committing to anything cross- harness. Ran live discovery probes on 2026-04-24 with a single skill placed at `.agents/skills/agents-only-prove/SKILL.md` in an isolated tmp workspace (no `.claude/`, `.codex/`, `.gemini/` skill dirs present), asked each harness whether it could see the skill by name: Claude Code 2.1.116 -> NO (skill absent from listed set) OpenAI Codex 0.124.0 -> YES (codex exec returned YES) Gemini CLI 0.39.1 -> YES (gemini -p returned YES) Updated the Gemini map: * Replaced the "cross-harness alias" assertion with a verified-status table + probe-method column. * Added a "Cross-harness skill-discovery reality" section with the verified matrix. * Added a "Generic vs. harness-specific skills" section documenting the behaviour / data split discipline the factory uses: each harness gets its own SKILL.md in its canonical directory (behaviour layer, tuned per harness), all three reference the same `docs/` content (data layer, shared). Thinner-than-holding-the-data but not so thin they just proxy elsewhere. * Stated the human-maintainer's 2026-04-24 policy call: until all three harnesses support a common home, keep each skill in its canonical home. No factory-code change; doc-only accuracy correction. The superseded PR #365 merged with the earlier content; this PR lands the cross-harness additions as a separate doc update so the drift between map and empirical behaviour is closed. --- docs/research/gemini-cli-capability-map.md | 84 ++++++++++++++++++---- 1 file changed, 69 insertions(+), 15 deletions(-) diff --git a/docs/research/gemini-cli-capability-map.md b/docs/research/gemini-cli-capability-map.md index bea9b85e..8996554f 100644 --- a/docs/research/gemini-cli-capability-map.md +++ b/docs/research/gemini-cli-capability-map.md @@ -68,14 +68,13 @@ gemini skills uninstall [--scope] ``` Per the Gemini CLI docs page -(`geminicli.com/docs/cli/skills/`), Gemini's skill format -*appears* to be the same **Agent Skills open standard** that -Anthropic's `.claude/skills/` uses — a directory containing a -`SKILL.md` with YAML frontmatter + body. Cross-harness -portability is plausible and is the reason `.agents/skills/` -exists as an alias, but the canonical spec + required -frontmatter fields have not been checked against Anthropic's -spec side-by-side in this pass (see Open questions below). +(`geminicli.com/docs/cli/skills/`), Gemini's skill format is +the same **Agent Skills open standard** as Anthropic's +`.claude/skills/` — a directory containing a `SKILL.md` with +YAML frontmatter + body. The SKILL.md shape is portable, but +**each harness uses its own discovery path**. See the +"Cross-harness skill-discovery reality" section below for +empirical results from a live 2026-04-24 probe. ### `gemini extensions` @@ -178,13 +177,68 @@ tier, the `.agents/skills/` alias takes precedence over ~/.agents/skills/ # cross-tool skill-sharing alias ``` -The `.agents/` convention is not Gemini-specific — it's a -cross-harness alias. Same directory works for multiple agent -harnesses that follow the Agent Skills open standard. Zeta has -neither `.gemini/` nor `.agents/` populated yet; the -human-maintainer account has one skill installed -(`microsoft-foundry` under `~/.agents/skills/`) from a prior -Antigravity / Google-workspace context. +The `.agents/` convention is an emerging cross-harness +proposal — but it is NOT universally honoured. See the next +section for the empirical status. Zeta has neither `.gemini/` +nor `.agents/` populated yet; the human-maintainer account has +one skill installed (`microsoft-foundry` under +`~/.agents/skills/`) from a prior Antigravity / Google- +workspace context. + +## Cross-harness skill-discovery reality + +Verified via live probes on 2026-04-24. Test setup: isolated +`/tmp/zeta-skill-test2/` workspace with a single skill +`.agents/skills/agents-only-prove/SKILL.md` (no `.claude/`, +`.codex/`, or `.gemini/` skill dirs present), then each +harness asked whether it could see the skill by name: + +| Harness | `.claude/skills/` | `.agents/skills/` | Probe method | +|---|---|---|---| +| Claude Code 2.1.116 | yes (canonical) | **NO** (verified) | `claude -p "...available skills..."` — skill absent from the listed set | +| OpenAI Codex 0.124.0 | n/a (uses `.codex/`) | **YES** (verified) | `codex exec "Do you see a skill named 'agents-only-prove'?"` returned `YES` | +| Gemini CLI 0.39.1 | n/a (uses `.gemini/`) | **YES** (verified) | `gemini --skip-trust -p "..."` returned `YES` | + +Implication: **until all three harnesses support a common +home, keep each skill in its harness's canonical directory** +(the human maintainer's 2026-04-24 policy call). The +`.agents/` path is real for Codex + Gemini today, and is +additive for the two that honour it; Claude Code's absence +from that set means `.agents/skills/` is NOT a single-copy +cross-harness solution right now. + +## Generic vs. harness-specific skills + +Two classes of skill, two placement rules: + +- **Generic skills** — domain capabilities any harness-agnostic + reader can execute (F# style guide, cartel detection math, + BACKLOG authoring discipline). Per the canonical-home policy, + each harness gets its own copy in its canonical directory: + `.claude/skills//`, `.codex/skills//`, + `.gemini/skills//`. Apply the **behaviour / data + split** the factory uses for skills: the SKILL.md bodies + carry the *behaviour* (what to do, per-harness tool calls, + per-harness phrasing tweaks) — thinner than holding the + underlying data, but not so thin they just proxy somewhere + else. The *data* (rule tables, worked examples, reference + material, citation blocks, domain definitions) lives in + shared `docs/` content that every SKILL.md references. Net + result: three near-duplicate behaviour bodies, one shared + data source. Maintenance burden drops to the behaviour + diffs only. +- **Harness-specific skills** — skills that wrap or extend + one harness's features (Claude Code hook helpers, Gemini + extension-validate wrappers, Codex `agents/openai.yaml` + authoring helpers). Place at the harness's canonical + directory ONLY. Do not duplicate — the body references + features other harnesses don't have. + +The factory's prior experience ("we tried earlier and had +issue with skills not in the canonical home for the harness") +reinforces the conservative placement rule. Revisit once +Claude Code joins the `.agents/skills/` convention (watch +the Claude Code changelog). Extensions live at: