From b70fbe910ea169c311de575518dfec58a4046d1d Mon Sep 17 00:00:00 2001 From: ayobamiseun Date: Sat, 1 Aug 2026 10:28:06 +0100 Subject: [PATCH] docs: explain per-skill reference limitation --- README.md | 7 +++++++ docs/getting-started.md | 8 ++++++++ 2 files changed, 15 insertions(+) diff --git a/README.md b/README.md index 3700fbaa..05777eec 100644 --- a/README.md +++ b/README.md @@ -57,6 +57,13 @@ npx skills add addyosmani/agent-skills --skill interview-me # requi npx skills add addyosmani/agent-skills --skill test-driven-development # red-green-refactor, enforced ``` +> **Installing one skill?** A per-skill `npx` install copies only +> `skills//`, not the repo-level `references/` directory. The skill still +> works, but paths to supplementary shared checklists are unavailable. Use a +> whole-repo integration, clone the repository, or copy the needed checklist into +> a `references/` directory inside the installed skill. This portability gap is +> tracked in [#361](https://github.com/addyosmani/agent-skills/issues/361). + Prefer a native integration? Pick your tool below.
diff --git a/docs/getting-started.md b/docs/getting-started.md index 97bd5dda..8fe56d39 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -140,6 +140,14 @@ The `references/` directory contains supplementary checklists: Load a reference when you need detailed patterns beyond what the skill covers. +If you install one skill with `npx skills add ... --skill `, only the +selected `skills//` directory is copied. The skill still works, but paths +to supplementary checklists in the repo-level `references/` directory are +unavailable. Use a whole-repo integration, clone the repository, or copy the +needed checklist into a `references/` directory inside the installed skill. +This portability gap is tracked in +[addyosmani/agent-skills#361](https://github.com/addyosmani/agent-skills/issues/361). + ## Spec and task artifacts The `/spec` and `/plan` commands create working artifacts (`SPEC.md`, `tasks/plan.md`, `tasks/todo.md`). Treat them as **living documents** while the work is in progress: