From a71eb51e057210fc0ac2bbd41c0f0fc294b16ac8 Mon Sep 17 00:00:00 2001 From: vam Date: Sat, 5 Sep 2026 11:45:31 +0800 Subject: [PATCH] docs: avoid double skill routing on native hosts --- docs/adoption-guide.md | 6 +++--- docs/codex-setup.md | 2 ++ docs/getting-started.md | 6 ++++-- 3 files changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/adoption-guide.md b/docs/adoption-guide.md index 151562b8..ce66ed76 100644 --- a/docs/adoption-guide.md +++ b/docs/adoption-guide.md @@ -28,7 +28,7 @@ A new project is the best-case scenario: there's no legacy behavior to preserve, ### Day 0 | Install and wire up 1. Install the pack (`npx skills add addyosmani/agent-skills`, or the native integration for your tool, see [getting-started.md](getting-started.md)). -2. Load `using-agent-skills` (the meta-skill) so the agent can route work to the right skill on its own. +2. If the host has no native skill router, load `using-agent-skills` (the meta-skill) so the agent can route work to the right skill on its own. On hosts with native routing, install the individual skills and do not preload the meta-skill as always-on context. 3. Add a short project rules file (`CLAUDE.md`, `.cursorrules`, etc.) with your stack, commands, and boundaries, `context-engineering` describes what belongs there. ### Day 0 | Define before you build @@ -65,7 +65,7 @@ Run the lifecycle in order for the project's first real feature: ### Greenfield anti-patterns - **Skipping `/spec` because "it's just a prototype."** Prototypes become products. The spec is the cheapest artifact you'll ever write for this codebase. -- **Loading all 25 skills into every session.** It wastes context and dilutes the ones that matter. Load by phase; let `using-agent-skills` route. +- **Loading all 25 skills into every session.** It wastes context and dilutes the ones that matter. Load by phase; let the host's native router or `using-agent-skills` route, but not both. - **Deferring observability until "there's something to observe."** Instrument as you build, retrofitting structured logging is a Path B problem you're choosing to create. --- @@ -121,7 +121,7 @@ Both end in the same steady state: `/spec → /plan → /build → /review → / | | Greenfield | Brownfield | | ---------------------- | ------------------------------ | ---------------------------------------- | -| First skill loaded | `using-agent-skills` + `/spec` | `context-engineering` | +| First skill loaded | Native router, or `using-agent-skills` + `/spec` | `context-engineering` | | First value delivered | Spec'd, tested first feature | Zero-risk reviews and safer bug fixes | | TDD posture | Universal from commit one | Selective: tests where change is planned | | Refactoring rule | Rare (little to refactor) | Characterization tests first, always | diff --git a/docs/codex-setup.md b/docs/codex-setup.md index 7f329396..51a71e56 100644 --- a/docs/codex-setup.md +++ b/docs/codex-setup.md @@ -24,6 +24,8 @@ codex plugin add agent-skills@agent-skills After install, invoke a skill in Codex chat with `@` (e.g. `@spec-driven-development`) or just describe the task and let Codex pick the right skill. All 25 skills under `skills/` are available. +[Codex uses progressive disclosure](https://developers.openai.com/codex/skills): it starts with each skill's `name` and `description`, chooses skills on demand, then loads the full `SKILL.md` only when selected. Do not also paste `using-agent-skills/SKILL.md` into `AGENTS.md`, a system prompt, or other always-on context: that stacks the pack's meta-router on Codex's native router and adds unnecessary routing work. The meta-skill can remain installed with the pack; the warning is specifically against preloading its full instructions. + ## How it works - `.codex-plugin/plugin.json` — Codex plugin manifest at the repo root. Points `skills` at `./skills/` and provides the metadata required by Codex. diff --git a/docs/getting-started.md b/docs/getting-started.md index 8572898a..26e08fde 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -35,9 +35,11 @@ Copy the relevant `SKILL.md` content into your agent's system prompt, rules file **Conversation:** Reference the skill when giving instructions: "Follow the test-driven-development process for this change." -### 4. Use the meta-skill for discovery +### 4. Use the meta-skill for discovery when needed -Start with the `using-agent-skills` skill loaded. It contains a flowchart that maps task types to the appropriate skill. +If your agent does not route skills natively, start with the `using-agent-skills` skill loaded. It contains a flowchart that maps task types to the appropriate skill. + +If your host already discovers and activates skills from their descriptions, do not also paste `using-agent-skills` into an always-on system prompt or rules file. That creates two routers for the same task. Install the individual skills and let the host activate them on demand instead. ## Recommended Setup