Merge #550: clarify Copilot CLI vs VS Code installation

docs(copilot): clarify CLI installation and VS Code commands

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).
+
 </details>
 
 <details>

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. |

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/<name>.prompt.md`, and each becomes a `/<name>` 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:<name>`, 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.