fix(skills): route [[skill]] + plugin skills natively for Codex/Gemini (ADR-012)

[szjanikowski]

Follow-up to #65, closing the known follow-up that ADR-012 itself flagged.

Problem

A skill reaches an agent three ways: the variant snapshot (agents_skills/, gemini_skills/), [[skill]] by-reference in variant.toml, and a [nasde.plugin]'s own skills/. PR #65 fixed only the snapshot path. The other two still went through plugin_registration.stage_skill_dir, which hardcodes /app/.claude/skills/<name>/:

• For Claude that's correct (cwd discovery root).
• For a Codex/Gemini variant the skill landed where the CLI never scans ($HOME/.agents/skills, ~/.gemini/skills), so it was never natively registered — the same silent "skill-as-document" failure as the original bug.

Uncaught today (no non-Claude variant in the repo uses [[skill]]/plugin), but a latent trap for exactly the core use case: migrating a by-reference skill (the ADR-009 way to avoid copy drift) between agents.

Fix

Both paths now resolve to skill directories (collect_referenced_skill_dirs / collect_plugin_skill_dirs — the dir-list counterparts of the unchanged Claude-only stage_referenced_skills / register_plugin_skills). For Codex/Gemini those dirs route through Harbor's native config.agent.skills, unioned with the snapshot dirs inside _refresh_agent_skills under the single _nasde_derived_skills marker (so stale-drop + hand-authored preservation work across both sources).

• Claude keeps its unchanged sandbox_files path; a Claude agent drops extra_skill_dirs at merge time to avoid double-injecting.
• The frontmatter warning now fires on this path too.
• A new basename-collision warning: Harbor's resolve_skills is last-wins by dir.name, so two derived dirs sharing a basename would silently collapse — nasde now warns.

Branch is one place: _refresh_agent_skills keys on each agent's own import_path, so a hand-written mixed multi-agent config stays correct.

New example variants

codex-nasde-dev-with-arch and gemini-nasde-dev-with-arch exercise [[skill]] by-reference (→ live .claude/skills/nasde-dev) on a non-Claude agent — a permanent repro + skill-migration demo. (Also adds the long-missing Codex variant to nasde-dev-skill.)

Verification

• E2E (Codex variant codex-nasde-dev-with-arch with [[skill]], --without-eval): the trial's trial.log shows Harbor's native registration command running — mkdir -p $HOME/.agents/skills && cp -r /harbor/skills/* $HOME/.agents/skills/ — i.e. the [[skill]] dir was uploaded to skills_dir and copied into Codex's native HOME-scoped location inside run(). The trial config.json confirms skills=[…/nasde-dev] (native) with no /app/.agents/skills in sandbox_files. Under the old code that cp would copy from an empty /harbor/skills (the skill went only to /app/.claude/skills, which Codex never scans). The agent turn itself then hit the Codex Plus usage limit — an account constraint, not the fix. (Gemini's native activate_skill registration was proven the same way in fix(skills): register Codex/Gemini skills natively, not in /app cwd (ADR-012) #65; the mechanism is shared.)
• pytest — 397 passed (new collect_*, union, branch, stale-drop, handwritten, basename-collision, frontmatter, mixed-agent tests)
• ruff check / ruff format --check / mypy — clean

Coverage levels (honest): the [[skill]] path is verified e2e on a live agent (Gemini activate_skill below). The [nasde.plugin] path shares the same channel from extra_skill_dirs onward but has no example to run e2e, so it is covered by an integration test driving the real ensure_task_plugin staging → collect_plugin_skill_dirs → harbor_config (no Docker), plus unit tests. Full live-agent e2e for a plugin is a follow-up for when a plugin benchmark exists.

Docs

• ADR-012 extended ("All three skill paths, not just the snapshot")
• CHANGELOG.md (Unreleased → Fixed), CLAUDE.md, nasde-benchmark-creator skill

🤖 Generated with Claude Code