From f7fe1a447d624d83b29c509769f367a9f68cd572 Mon Sep 17 00:00:00 2001 From: DEOWL-kan <155065216+DEOWL-kan@users.noreply.github.com> Date: Sat, 5 Sep 2026 11:13:50 +0800 Subject: [PATCH] docs(copilot): clarify CLI installation and VS Code commands --- README.md | 2 + docs/copilot-cli-setup.md | 64 ++++++++++++++++++++++++++++++++ docs/copilot-setup.md | 77 ++++++++++++++++++++++++++++++++++++++- 3 files changed, 142 insertions(+), 1 deletion(-) create mode 100644 docs/copilot-cli-setup.md diff --git a/README.md b/README.md index 582f74c9..0d3b2a38 100644 --- a/README.md +++ b/README.md @@ -164,6 +164,8 @@ See [docs/opencode-setup.md](docs/opencode-setup.md). Use agent definitions from `agents/` as Copilot personas and skill content in `.github/copilot-instructions.md`. See [docs/copilot-setup.md](docs/copilot-setup.md). +Using the standalone `copilot` CLI? Install it as a plugin — see [docs/copilot-cli-setup.md](docs/copilot-cli-setup.md). +
diff --git a/docs/copilot-cli-setup.md b/docs/copilot-cli-setup.md new file mode 100644 index 00000000..06e3f526 --- /dev/null +++ b/docs/copilot-cli-setup.md @@ -0,0 +1,64 @@ +# Using agent-skills with GitHub Copilot CLI + +The standalone `copilot` command-line tool installs this repository as a plugin and discovers every skill in `skills/`. For Copilot inside VS Code, see [copilot-setup.md](copilot-setup.md) instead — the setup and the invocation model are different. + +## Install + +**From this repository's marketplace** — register it, then install from it. `addy-agent-skills` is the marketplace name this repository declares, not a GitHub-wide registry, and the name only resolves after the `marketplace add`: + +```bash +copilot plugin marketplace add addyosmani/agent-skills +copilot plugin install agent-skills@addy-agent-skills +``` + +**Directly from the repository**, without registering a marketplace: + +```bash +copilot plugin install addyosmani/agent-skills +``` + +**From a local clone**, for a session-scoped development install: + +```bash +git clone https://github.com/addyosmani/agent-skills.git +copilot --plugin-dir /path/to/agent-skills +``` + +`--plugin-dir` loads the plugin for that session only and installs nothing persistently — use it while editing skills. + +## Verify + +```bash +copilot plugin list # agent-skills@addy-agent-skills +copilot skill list # the plugin's skills, alongside the built-in ones +``` + +In an interactive session, `/skills list` shows the same catalog. + +## What you get, and what you don't + +The root `plugin.json` is the manifest Copilot CLI reads — it takes precedence over `.claude-plugin/plugin.json`, which belongs to Claude Code. That root manifest declares only a name, version and description, so component paths fall back to their defaults: + +- **Skills — available.** With no explicit path, the CLI uses the conventional `skills/` directory, and the skills are discovered there. +- **Lifecycle commands — not available.** The root manifest has no `commands` field, so nothing registers `/spec`, `/plan`, `/build`, `/test`, `/review` or `/ship`. Those files live in `.claude/commands/` and are Claude Code commands. + +For manifest precedence and the per-component path defaults, see the [CLI plugin reference](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference) and [Creating plugins](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/plugins-creating). + +## Usage + +Name the skill you want, or describe the task and let the agent route to it: + +> Use the spec-driven-development skill to write a spec for [the feature]. + +> Use the test-driven-development skill: write a failing test for this bug first, then fix it. + +> Use the code-review-and-quality skill to review my staged changes. + +## Troubleshooting + +| Symptom | What to check | +|---------|---------------| +| `plugin install` can't resolve `agent-skills@addy-agent-skills` | Run `copilot plugin marketplace add addyosmani/agent-skills` first — that name only resolves once the marketplace is registered. Or install the repository directly. | +| Plugin installed but no skills | `copilot plugin list` to confirm the plugin, then `copilot skill list` (or `/skills list` in session) to see what was discovered. | +| `/spec`, `/build` and friends are not found | Expected, not a broken install: the root manifest registers no commands. Ask for the skill by name instead. | +| Skills changed locally but the CLI shows the old copy | Start a fresh session, or run with `--plugin-dir` pointing at your clone. | diff --git a/docs/copilot-setup.md b/docs/copilot-setup.md index cfe137ee..f70aa3b1 100644 --- a/docs/copilot-setup.md +++ b/docs/copilot-setup.md @@ -1,5 +1,9 @@ # Using agent-skills with GitHub Copilot +This guide covers Copilot in VS Code. For the standalone `copilot` command-line tool, see [copilot-cli-setup.md](copilot-cli-setup.md). + +**What an install actually gives you:** the skills. Each installed skill becomes a slash command named after its frontmatter `name` — `/spec-driven-development`, `/test-driven-development`, and so on. `npx skills add addyosmani/agent-skills` and the manual copy below both install skills only. Neither of those two routes copies this repo's short lifecycle wrappers (`/spec`, `/plan`, `/build`, `/test`, `/review`, `/ship`) — those are Claude Code commands living in `.claude/commands/`. Use the full skill names, or add your own aliases — see [Lifecycle workflows](#lifecycle-workflows). + ## Setup ### Copilot Instructions @@ -14,7 +18,9 @@ cat /path/to/agent-skills/skills/test-driven-development/SKILL.md > .github/skil cat /path/to/agent-skills/skills/code-review-and-quality/SKILL.md > .github/skills/code-review-and-quality/SKILL.md ``` -For more details, refer [Creating agent skills for GitHub Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-skills). +Whichever of these two routes you use, the result is one `SKILL.md` per skill directory under one of those three project paths. An installer run with a global/user flag writes somewhere else instead — check its output for the path it used. Run `/skills` in Copilot Chat to open the **Configure Skills** menu and confirm what got discovered. + +For more details, refer [Creating agent skills for GitHub Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-skills) and the VS Code guide to [agent skills](https://code.visualstudio.com/docs/agent-customization/agent-skills). ### Agent Personas (*.agent.md) @@ -79,6 +85,75 @@ GitHub Copilot supports project-level instructions via `.github/copilot-instruct Use the agents for targeted review workflows in Copilot Chat. +## Lifecycle Workflows + +Skills are user-invocable by default, so once they're discovered the whole lifecycle is available under the skills' own names — no extra configuration: + +| Workflow | Copilot invocation | Notes | +|----------|--------------------|-------| +| Define | `/spec-driven-development` | Writes a structured spec before code | +| Plan | `/planning-and-task-breakdown` | Produces `tasks/plan.md` and `tasks/todo.md` | +| Build | `/incremental-implementation` | Pair with `/test-driven-development`; one slice at a time | +| Verify | `/test-driven-development` | Red-green-refactor, Prove-It for bugs | +| Review | `/code-review-and-quality` | Five-axis review | +| Ship | `/shipping-and-launch` | Launch readiness | + +Type `/` to browse what's actually loaded in this workspace. + +Natural language is the fallback, and works in any Copilot surface whether or not the slash commands show up: + +> Use the spec-driven-development skill to write a spec for [the feature]. + +> Use the code-review-and-quality skill to review my staged changes. + +### Optional: short `/spec`-style aliases + +VS Code's extension-host local agents support [prompt files](https://code.visualstudio.com/docs/agent-customization/prompt-files) at `.github/prompts/.prompt.md`, and each becomes a `/` slash command. The Agent Host does **not** use prompt files — there, use the skill names above. + +An alias is a thin shortcut to one skill, nothing more. These aliases do not implement the orchestration in this repo's Claude Code commands — `/build auto`'s single-approval plan-and-implement pass and `/ship`'s parallel persona fan-out. Reproducing that on Copilot is its own piece of work, not something a one-file alias covers. Prefer the skill names as your default; reach for aliases only if the short form is worth the extra file. + +Create one, without clobbering an existing file: + +```bash +mkdir -p .github/prompts +[ -e .github/prompts/spec.prompt.md ] || cat > .github/prompts/spec.prompt.md <<'EOF' +--- +description: Write a structured spec before writing code +--- + +Use the spec-driven-development skill. + +Ask clarifying questions about the objective and target users, core features and +acceptance criteria, stack preferences and constraints, and known boundaries. +Then write a spec covering objective, commands, project structure, code style, +testing strategy, and boundaries. Save it as SPEC.md in the project root and +confirm with me before any code is written. +EOF +``` + +Reload the window, then type `/spec`. + +For the rest, run the same `mkdir`/`cat` block with the filename swapped (the filename *is* the command name), and take the `description` and body from this table. **Replace the entire body below the `---` frontmatter**, not just the skill name — the spec body's SPEC.md and clarifying-question instructions belong to Define only, and leaving them in would make `/plan` or `/test` write a spec. + +| Alias file | `description` | Complete body — everything below the frontmatter | +|------------|---------------|--------------------------------------------------| +| `.github/prompts/plan.prompt.md` | Break an approved spec into ordered, verifiable tasks | Use the planning-and-task-breakdown skill. Read the spec, then break the work into small, independently verifiable tasks, each with acceptance criteria and explicit dependency order. Save the result to `tasks/plan.md` and `tasks/todo.md`. Write no product code — show me the plan and wait for my approval. | +| `.github/prompts/build.prompt.md` | Implement the next planned task, test-first | Use the incremental-implementation and test-driven-development skills. Read `tasks/plan.md` and `tasks/todo.md`, then take the next unchecked task and only that one. Write a failing test first, make it pass, refactor, run the suite, and tick the task off. Stop there and report what changed. | +| `.github/prompts/test.prompt.md` | Write tests before the code that satisfies them | Use the test-driven-development skill. For new behavior, write a failing test that captures it before any implementation. For a bug, reproduce it with a failing test first, then fix it. Run the suite after each step and show me the red and the green output. | + +Write the body yourself, or take it from this table, rather than copying `.claude/commands/*.md` verbatim: those files reference skills as `agent-skills:`, a Claude Code plugin namespace that means nothing to Copilot. + +### If the skill slash commands don't appear + +Work through these in order — `/spec-driven-development` missing and `/spec` missing have different causes: + +1. **Check where the skills landed.** Each one needs its own directory containing a `SKILL.md`. The project-level paths this guide uses are `.github/skills/`, `.claude/skills/` and `.agents/skills/` — but an installer run with a global/user flag writes outside the workspace instead (`~/.agents/skills/` and equivalents), so a skill that isn't in any of the three may simply be installed personally. Confirm the actual path against the [VS Code agent skills docs](https://code.visualstudio.com/docs/agent-customization/agent-skills), then re-install into the project if you wanted it project-scoped. +2. **Check the frontmatter.** `name` must be present and valid — it *is* the slash command. A skill whose frontmatter opts out of user invocation won't appear. +3. **Check the Configure Skills menu.** Run `/skills` and confirm the skill is enabled here. +4. **Start a fresh session.** Newly added skills aren't always picked up mid-conversation. +5. **Check the host.** If `/spec-driven-development` works but your `/spec` alias doesn't, you're likely on the Agent Host, which doesn't read prompt files. +6. **Check versions.** VS Code (**Help → About**) and the Copilot Chat extension; skills-as-slash-commands is recent, so update if either is behind. + ## Usage Tips 1. **Keep instructions concise** — Copilot instructions work best when focused. Summarize the key rules rather than including full skill files.