* feat(#1243): consume Claude plugin-provided skills via native Skill-tool directive + grant Skill to agent_skills-consumer agents - Relax global skill name validation to accept namespaced form `^[A-Za-z0-9_-]+(:[A-Za-z0-9_-]+)*$` - Namespaced names (containing colon) on claude runtime emit a Skill-tool load directive instead of a @-include line - Namespaced names on non-claude runtimes are skipped with a warning - Bare unresolved names retain existing warn-and-skip behavior (no promotion to directive) - Grant `Skill` tool to all 22 agent_skills consumer agents; 5 generated agents updated via research-profiles.cjs + regen, 17 hand-authored agents edited directly - Add 16 TDD tests in describe('bug #1243') covering happy/mixed/precedence/negative/cross-runtime/regression/grant cases Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs(#1243): document plugin-provided skills in agent_skills Update the Agent Skills Injection reference in CONFIGURATION.md with the three entry forms (project-relative, global:<name>, global:<plugin>:<skill>), the Claude-only runtime behaviour of the namespaced form and the warn-skip on other runtimes, the plugin pre-install prerequisite, and the consumer-agent Skill tool grant. Add docs/how-to/attach-a-plugin-skill-to-a-gsd-agent.md with a step-by-step guide for installing the plugin, locating the namespaced skill name, wiring it into agent_skills, and verifying injection. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix(#1243): align agent_skills docs with emitted block format + mixed-block regression test (code-review) - Replace two-section mixed-block example (bogus "Load these plugin-provided skills using the Skill tool:" header) with the actual single-section inline format in CONFIGURATION.md and docs/how-to/attach-a-plugin-skill-to-a-gsd-agent.md - Fix quoted warning text in how-to doc to exactly match the emitted string: [agent-skills] WARNING: Plugin-namespaced skill "global:<name>" requires a Skill-tool-capable runtime (claude) — skipping on runtime "<runtime>" - Replace phantom agent slugs (gsd-checker, gsd-researcher, gsd-advisor, gsd-synthesizer) in CONFIGURATION.md Supported Agent Types with real agents/gsd-*.md examples (gsd-plan-checker, gsd-phase-researcher, gsd-code-reviewer, gsd-ui-auditor, gsd-research-synthesizer) - Add byte-identical mixed-block regression test: one path-resolvable global skill + one plugin-namespaced skill on claude runtime → asserts r.ir.block === single-section interleaved block, no secondary header Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * chore(#1243): regenerate agent-size baseline for the Skill-tool grant The 22 agent_skills-consumer agents each grew +7 bytes from adding `Skill` to their tools list; refresh the committed per-agent size baseline (#1074 guard). * chore(#1243): add Added changeset fragment * fix(#1243): traceable allow-test-rule ref + separator-agnostic byte-identical tests (CI) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
@@ -405,52 +405,90 @@ Inject custom skill files into GSD subagent prompts. Skills are read by agents a
|
||||
|
||||
| Setting | Type | Default | Description |
|
||||
|---------|------|---------|-------------|
|
||||
| `agent_skills` | object | `{}` | Map of agent types to skill directory paths |
|
||||
| `agent_skills` | object | `{}` | Map of agent types to arrays of skill entries |
|
||||
| `agent_skills_security.trusted_global_roots` | array of strings | `[]` | Opt-in allowlist of additional trusted directories for `global:` skills. See [Trusted global skill roots](#trusted-global-skill-roots-agent_skills_securitytrusted_global_roots) |
|
||||
|
||||
### Configuration
|
||||
|
||||
Add an `agent_skills` section to `.planning/config.json` mapping agent types to arrays of skill directory paths (relative to project root):
|
||||
Add an `agent_skills` section to `.planning/config.json` mapping agent types to arrays of skill entries:
|
||||
|
||||
```json
|
||||
{
|
||||
"agent_skills": {
|
||||
"gsd-executor": ["skills/testing-standards", "skills/api-conventions"],
|
||||
"gsd-executor": [
|
||||
"skills/testing-standards",
|
||||
"global:shared-conventions",
|
||||
"global:coderabbit:code-review"
|
||||
],
|
||||
"gsd-planner": ["skills/architecture-rules"],
|
||||
"gsd-verifier": ["skills/acceptance-criteria"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Each path must be a directory containing a `SKILL.md` file. Paths are validated for safety (no traversal outside project root).
|
||||
### Skill Entry Forms
|
||||
|
||||
Each element in the array is one of three forms:
|
||||
|
||||
| Form | Example | Resolution |
|
||||
|------|---------|------------|
|
||||
| Project-relative path | `"skills/my-skill"` | Resolves to `<project>/skills/my-skill/SKILL.md`, injected as an `@`-include |
|
||||
| Global personal skill | `"global:<name>"` | Resolves to `~/.claude/skills/<name>/SKILL.md`, injected as an `@`-include |
|
||||
| Plugin-provided skill (Claude only) | `"global:<plugin>:<skill>"` | A Claude Code plugin skill, loaded by name via the Skill tool at agent spawn time |
|
||||
|
||||
**Project-relative paths** must point to a directory containing a `SKILL.md` file. Paths are validated for safety (no traversal outside the project root).
|
||||
|
||||
**Global personal skills** (`global:<name>`) resolve against the runtime's global skills directory (e.g. `~/.claude/skills/`). Symlink-escape protection applies unless the target is listed in `agent_skills_security.trusted_global_roots`.
|
||||
|
||||
**Plugin-provided skills** (`global:<plugin>:<skill>`) follow the namespaced form `seg(:seg)*`, where each segment is one or more alphanumeric characters, underscores, or hyphens joined by single colons (e.g. `global:coderabbit:code-review`). This form is **Claude-only**: on the Claude runtime GSD emits a Skill-tool load directive in the agent's `<agent_skills>` block so the agent loads the skill by name via the Skill tool, and Claude Code resolves the `plugin:skill` namespace. On all other runtimes the entry is skipped with a warning — the plugin/Skill-tool model is specific to Claude Code and has no equivalent elsewhere.
|
||||
|
||||
> **Why load by name rather than path?** Claude Code's plugin cache is versioned and ephemeral, so there is no stable filesystem path to `@`-include. Loading by namespaced name via the Skill tool lets Claude Code's own resolver locate the current version of the plugin skill at runtime.
|
||||
|
||||
The plugin must already be installed in the user's Claude Code environment (`/plugin install …`). GSD only references the skill by its namespaced name and does not read or validate the plugin cache itself.
|
||||
|
||||
### Supported Agent Types
|
||||
|
||||
Any GSD agent type can receive skills. Common types:
|
||||
Any GSD agent type can receive skills. The agent types that consume `agent_skills` are the GSD sub-agents the workflows dispatch. There are 22 consumer agents in total, including:
|
||||
|
||||
- `gsd-executor` -- executes implementation plans
|
||||
- `gsd-planner` -- creates phase plans
|
||||
- `gsd-checker` -- verifies plan quality
|
||||
- `gsd-verifier` -- post-execution verification
|
||||
- `gsd-researcher` -- phase research
|
||||
- `gsd-project-researcher` -- new-project research
|
||||
- `gsd-debugger` -- diagnostic agents
|
||||
- `gsd-codebase-mapper` -- codebase analysis
|
||||
- `gsd-advisor` -- discuss-phase advisors
|
||||
- `gsd-ui-researcher` -- UI design contract creation
|
||||
- `gsd-ui-checker` -- UI spec verification
|
||||
- `gsd-roadmapper` -- roadmap creation
|
||||
- `gsd-synthesizer` -- research synthesis
|
||||
- `gsd-executor` — executes implementation plans
|
||||
- `gsd-planner` — creates phase plans
|
||||
- `gsd-plan-checker` — verifies plan quality
|
||||
- `gsd-verifier` — post-execution verification
|
||||
- `gsd-phase-researcher` — phase research
|
||||
- `gsd-project-researcher` — new-project research
|
||||
- `gsd-debugger` — diagnostic agents
|
||||
- `gsd-codebase-mapper` — codebase analysis
|
||||
- `gsd-code-reviewer` — code review
|
||||
- `gsd-ui-researcher` — UI design contract creation
|
||||
- `gsd-ui-checker` — UI spec verification
|
||||
- `gsd-ui-auditor` — UI audit
|
||||
- `gsd-roadmapper` — roadmap creation
|
||||
- `gsd-research-synthesizer` — research synthesis
|
||||
- and others (see `tests/agent-skills.test.cjs` `CONSUMER_AGENTS` list for the full 22)
|
||||
|
||||
The `Skill` tool is granted to consumer agents deliberately and is instruction-bounded — agents use it only to load the skills listed in the `<agent_skills>` block.
|
||||
|
||||
### How It Works
|
||||
|
||||
At spawn time, workflows call `gsd-tools query agent-skills <type>` (or legacy `node gsd-tools.cjs agent-skills <type>`) to load configured skills. If skills exist for the agent type, they are injected as an `<agent_skills>` block in the Task() prompt:
|
||||
At spawn time, workflows call `gsd-tools query agent-skills <type>` (or legacy `node gsd-tools.cjs agent-skills <type>`) to load configured skills. If skills exist for the agent type, they are injected as an `<agent_skills>` block in the Task() prompt.
|
||||
|
||||
For project-relative and global personal skills, entries appear as `@`-includes:
|
||||
|
||||
```xml
|
||||
<agent_skills>
|
||||
Read these user-configured skills:
|
||||
- @skills/testing-standards/SKILL.md
|
||||
- @skills/api-conventions/SKILL.md
|
||||
- @/Users/you/.claude/skills/shared-conventions/SKILL.md
|
||||
</agent_skills>
|
||||
```
|
||||
|
||||
For a mixed config (path-resolvable and plugin-provided skills together), entries appear interleaved in config order in a single section:
|
||||
|
||||
```xml
|
||||
<agent_skills>
|
||||
Read these user-configured skills:
|
||||
- @skills/testing-standards/SKILL.md
|
||||
- Load the `coderabbit:code-review` skill via the Skill tool before proceeding (plugin-provided).
|
||||
</agent_skills>
|
||||
```
|
||||
|
||||
@@ -464,6 +502,8 @@ Set skills via the CLI:
|
||||
gsd-tools query config-set agent_skills.gsd-executor '["skills/my-skill"]'
|
||||
```
|
||||
|
||||
See [How to attach a plugin-provided skill to a GSD agent](how-to/attach-a-plugin-skill-to-a-gsd-agent.md) for a step-by-step walkthrough of the `global:plugin:skill` form.
|
||||
|
||||
---
|
||||
|
||||
## Trusted Global Skill Roots (`agent_skills_security.trusted_global_roots`)
|
||||
|
||||
@@ -17,6 +17,7 @@ Language versions: [English](README.md) · [Português (pt-BR)](pt-BR/README.md)
|
||||
|
||||
- [Install on your runtime](how-to/install-on-your-runtime.md) — runtime-specific install steps for all 16 supported runtimes
|
||||
- [Install a minimal GSD and add skills later](how-to/install-minimal-and-add-skills.md) — install only the core skills, then grow the surface with profiles and `/gsd:surface`
|
||||
- [Attach a plugin-provided skill to a GSD agent](how-to/attach-a-plugin-skill-to-a-gsd-agent.md) — use the `global:plugin:skill` entry form to load Claude Code plugin skills into agent prompts
|
||||
- [Discuss a phase](how-to/discuss-a-phase.md) — capture implementation decisions before planning begins
|
||||
- [Resolve edge-coverage findings](how-to/resolve-edge-coverage-findings.md) — turn the spec phase's surfaced domain-boundary edges into covered, dismissed, or backstopped spec decisions
|
||||
- [Resolve prohibition findings](how-to/resolve-prohibition-findings.md) — turn the spec phase's surfaced must-NOT constraints into resolved, dismissed, or deferred spec decisions
|
||||
|
||||
98
docs/how-to/attach-a-plugin-skill-to-a-gsd-agent.md
Normal file
98
docs/how-to/attach-a-plugin-skill-to-a-gsd-agent.md
Normal file
@@ -0,0 +1,98 @@
|
||||
# How to attach a plugin-provided skill to a GSD agent
|
||||
|
||||
Use this guide when you have a Claude Code plugin that ships a skill and you want GSD agents to load it automatically at spawn time. The `global:<plugin>:<skill>` entry form makes GSD emit a Skill-tool load directive so the agent picks up the plugin skill alongside any project-local or personal global skills.
|
||||
|
||||
**This feature works on the Claude runtime only.** On other runtimes (Codex, Gemini, Cursor, etc.) the entry is skipped with a warning. Plan accordingly if your team uses multiple runtimes.
|
||||
|
||||
---
|
||||
|
||||
## 1. Install the plugin in Claude Code
|
||||
|
||||
GSD does not install or manage Claude Code plugins. Install the plugin first:
|
||||
|
||||
```
|
||||
/plugin install <plugin-source>
|
||||
```
|
||||
|
||||
Verify the plugin is active and note the skill names it exposes. The plugin's documentation or `README` will list available skill names in the format `plugin:skill` — for example, `coderabbit:code-review`.
|
||||
|
||||
---
|
||||
|
||||
## 2. Find the namespaced skill name
|
||||
|
||||
The name you need has two colon-separated segments after `global:`:
|
||||
|
||||
```
|
||||
global:<plugin>:<skill>
|
||||
```
|
||||
|
||||
For example, if the plugin slug is `coderabbit` and it provides a skill called `code-review`, the entry is:
|
||||
|
||||
```
|
||||
global:coderabbit:code-review
|
||||
```
|
||||
|
||||
Each segment must consist of alphanumeric characters, underscores, or hyphens only. No spaces, no slashes, no dots.
|
||||
|
||||
---
|
||||
|
||||
## 3. Add the entry to `agent_skills`
|
||||
|
||||
Open `.planning/config.json` and add the namespaced skill to the array for the agent type that should receive it:
|
||||
|
||||
```json
|
||||
{
|
||||
"agent_skills": {
|
||||
"gsd-executor": [
|
||||
"skills/project-conventions",
|
||||
"global:coderabbit:code-review"
|
||||
],
|
||||
"gsd-verifier": [
|
||||
"global:coderabbit:code-review"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You can mix all three entry forms freely within the same array — project-relative paths, `global:<name>` personal skills, and `global:<plugin>:<skill>` plugin skills.
|
||||
|
||||
Or set it from the CLI:
|
||||
|
||||
```bash
|
||||
gsd-tools query config-set agent_skills.gsd-executor '["skills/project-conventions","global:coderabbit:code-review"]'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Verify the injection
|
||||
|
||||
Start a phase on the Claude runtime. When the target agent is spawned, its Task() prompt will contain an `<agent_skills>` block that includes a Skill-tool load directive for the plugin skill:
|
||||
|
||||
```xml
|
||||
<agent_skills>
|
||||
Read these user-configured skills:
|
||||
- @skills/project-conventions/SKILL.md
|
||||
- Load the `coderabbit:code-review` skill via the Skill tool before proceeding (plugin-provided).
|
||||
</agent_skills>
|
||||
```
|
||||
|
||||
Both entry types appear in the same `Read these user-configured skills:` section, interleaved in config order. There is no separate header for plugin-provided skills.
|
||||
|
||||
If you see `[agent-skills] WARNING: Plugin-namespaced skill "global:coderabbit:code-review" requires a Skill-tool-capable runtime (claude) — skipping on runtime "<runtime>"` in the logs, the entry is being skipped because the active runtime is not Claude. The configuration is still valid; no change is needed.
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- **Plugin must be pre-installed.** GSD only references the skill by namespaced name. If the plugin is not installed in Claude Code, the Skill tool call will fail at agent runtime — GSD cannot validate plugin presence at configuration time.
|
||||
- **Which agents support it.** All 22 GSD agent types that consume `agent_skills` carry the `Skill` tool, so any of them can load plugin-provided skills. See [Agent Skills Injection — Supported Agent Types](../CONFIGURATION.md#supported-agent-types) for the full list.
|
||||
- **Non-Claude runtimes.** The `global:<plugin>:<skill>` entry is silently skipped with a warning on non-Claude runtimes. Project-relative and `global:<name>` entries work on all runtimes.
|
||||
- **Security boundary.** Plugin skill content is resolved entirely by Claude Code at agent runtime. GSD does not read, cache, or validate the plugin's files.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [Configuration — Agent Skills Injection](../CONFIGURATION.md#agent-skills-injection)
|
||||
- [Install a minimal GSD and add skills later](install-minimal-and-add-skills.md)
|
||||
- [Import a capability from a URL](import-a-capability-from-a-url.md)
|
||||
Reference in New Issue
Block a user