doc: cross-harness skill-discovery verified + behaviour/data split#367
doc: cross-harness skill-discovery verified + behaviour/data split#367
Conversation
…/data split
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.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2be4a38e36
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| 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 |
There was a problem hiding this comment.
This new policy says skills must stay in each harness’s canonical directory, but the same document still tells readers to place factory skills in a single .agents/skills/... copy for Claude/Codex/Gemini (lines 290-292), which is the opposite recommendation. Following the older step will make Claude miss those skills (as your probe table already shows), so the doc currently gives contradictory operational guidance that can break cross-harness experiments.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Pull request overview
Updates the Gemini CLI capability map to reflect empirically verified cross-harness skill discovery behavior and to document the factory’s intended “behaviour / data split” approach for skills across harnesses.
Changes:
- Replaces prior speculation about
.agents/skills/being a universal alias with a verified cross-harness discovery matrix (probe on 2026-04-24). - Adds guidance on “generic vs. harness-specific” skill placement and the behaviour/data split for shared content.
- Adjusts the
gemini skillssection to reference the new discovery findings.
| (`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. |
There was a problem hiding this comment.
Doc now states Gemini's skill format "is the same Agent Skills open standard" as Anthropic's .claude/skills/, but later the "Open questions" section still says the canonical spec/required frontmatter fields were not verified (and only suspected identical). Please reconcile: either soften this claim (e.g., "appears" / "suspected") or add a concrete verification note and remove/update the open-question text so the doc is internally consistent.
| (`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. | |
| (`geminicli.com/docs/cli/skills/`), Gemini's skill format | |
| appears to align with the **Agent Skills open standard** used | |
| by Anthropic's `.claude/skills/` — a directory containing a | |
| `SKILL.md` with YAML frontmatter + body. The broad SKILL.md | |
| shape appears portable, but **each harness uses its own | |
| discovery path**, and this doc's live 2026-04-24 probe | |
| verified discovery behavior rather than every canonical | |
| frontmatter requirement. |
| 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. |
There was a problem hiding this comment.
This section correctly concludes .agents/skills/ is not a single-copy cross-harness solution because Claude Code doesn't discover it, but later in the doc ("Factory integration — shape suggestions") it still claims one copy under .agents/skills/ serves Claude Code + Codex + Gemini. Please update the later integration guidance (or adjust this implication) so the recommended placement policy is consistent throughout the document.
Summary
Follow-up to PR #365 (Gemini capability map) that closes the gap between what the map claimed and what the harnesses actually do.
What triggered this
The human maintainer caught the map asserting
.agents/skills/as a cross-harness alias without verification, noted the factory had earlier problems with skills placed outside each harness's canonical home, and asked for direct empirical test.Live probe (2026-04-24)
Setup: isolated
/tmp/zeta-skill-test2/with ONE skill file at.agents/skills/agents-only-prove/SKILL.mdand no other skill dirs. Then asked each harness whether it could see the skill by name.claude -p "..."— skill absent from listed setcodex exec "..."returnedYESgemini --skip-trust -p "..."returnedYESWhat the doc now says
docs/content for data. Thinner than holding the data inline, but not so thin they just proxy elsewhere.Test plan
.agents/skills/,.claude/skills/,.codex/skills/,.gemini/skills/are all valid paths on their respective harnesses)