diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 0e73f1b..1a18794 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -2,7 +2,7 @@
 This is the default PR template. Before requesting review, replace this
 content with a generated PR description by running the
 /update-pr-description skill in Claude Code. See:
-https://github.com/testdouble/han/blob/main/docs/skills/update-pr-description.md
+https://github.com/testdouble/han/blob/main/docs/skills/han-github/update-pr-description.md
 -->
 
 ## Before requesting review
@@ -16,7 +16,7 @@ Work through this checklist before marking the PR ready. Leave it in the PR body
 - [ ] Read [CONTRIBUTING.md](../CONTRIBUTING.md) and confirm the changes follow the rules for the entity being touched (skill, agent, long-form doc, index, template).
 - [ ] Walk the [self-review checklist in CONTRIBUTING.md](../CONTRIBUTING.md#reviewing-your-own-changes): frontmatter validity, `allowed-tools` accuracy, context-injection simplicity, template adherence, index placement, link resolution, voice compliance.
 - [ ] Confirm the writing follows [`docs/writing-voice.md`](../docs/writing-voice.md). No em-dashes. No banned words ("actually", "just", "leverage", "utilize", "showcase", "robust" as vague positive, "It's worth noting", "Importantly").
-- [ ] If a new skill or agent was added or renamed, confirm the [coverage rule](../docs/templates/coverage-rule.md) is satisfied: long-form doc exists at `docs/skills/{name}.md` or `docs/agents/{name}.md`, and the index in `docs/skills/README.md` or `docs/agents/README.md` has a one-sentence scent line.
+- [ ] If a new skill or agent was added or renamed, confirm the [coverage rule](../docs/templates/coverage-rule.md) is satisfied: long-form doc exists at `docs/skills/{plugin}/{name}.md` or `docs/agents/han-core/{name}.md`, and the index in `docs/skills/README.md` or `docs/agents/README.md` has a one-sentence scent line.
 - [ ] If a skill or agent was added, removed, or renamed, confirm the indexes ([`docs/skills/README.md`](../docs/skills/README.md), [`docs/agents/README.md`](../docs/agents/README.md)), and [`docs/concepts.md`](../docs/concepts.md) each list every current entity.
 - [ ] If the change touches plugin behavior, run the affected skill or agent locally and confirm it still works end-to-end.
 - [ ] If the change affects `plugin/.claude-plugin/plugin.json` or `.claude-plugin/marketplace.json`, confirm both are consistent.
diff --git a/CLAUDE.md b/CLAUDE.md
index a11435e..f1688a7 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -67,7 +67,7 @@ Han is a Claude Code plugin suite for solo (or small-team) product engineers. It
 └── images/             # Banner and graphics for README
 ```
 
-The plugins are shipped from `han-core/`, `han-planning/`, `han-coding/`, `han-github/`, `han-reporting/`, `han-feedback/`, `han-atlassian/`, `han-linear/`, and `han-plugin-builder/`; the `han/` meta-plugin pulls in `han-core`, `han-planning`, `han-coding`, `han-github`, and `han-reporting` through its `dependencies`. `han-planning` and `han-coding` depend on `han-core` like the GitHub and reporting layers and are bundled by the meta-plugin. `han-feedback`, `han-atlassian`, and `han-linear` depend on `han-core` like the other layers but are deliberately left out of the meta-plugin, so each is opt-in and installed on its own (`han-atlassian` additionally requires a configured Atlassian MCP server, and `han-linear` a configured Linear MCP server). `han-plugin-builder` depends on nothing and is likewise opt-in and installed on its own. The contributor-facing authoring guidance (how to build skills, agents, and plugins) lives inside `han-plugin-builder/skills/guidance/references/`, not under `docs/`; running the `guidance` skill with `init` vendors all three plugin-building skills into any repo's `.claude/skills/` under a `plugin-` prefix (`plugin-guidance`, `plugin-skill-builder`, and `plugin-agent-builder`, so they never collide with this plugin's own slash commands), plus a path-scoped rule index, so the skills run and the guidance surfaces with no dependency on the plugin being installed. The same plugin also ships those two interview-driven builder skills, `skill-builder` and `agent-builder`, that walk the design tree for a new skill or agent decision-by-decision and then review the finished artifact against that guidance. Documentation lives in `docs/` and covers the whole suite. Long-form docs in `docs/skills/{name}.md` and `docs/agents/{name}.md` are the canonical operator-facing source for every skill and every agent. The underlying definition (`han-core/skills/{name}/SKILL.md`, `han-planning/skills/{name}/SKILL.md`, `han-coding/skills/{name}/SKILL.md`, `han-github/skills/{name}/SKILL.md`, `han-reporting/skills/{name}/SKILL.md`, `han-feedback/skills/{name}/SKILL.md`, `han-atlassian/skills/{name}/SKILL.md`, `han-linear/skills/{name}/SKILL.md`, or `han-core/agents/{name}.md`) is the implementation.
+The plugins are shipped from `han-core/`, `han-planning/`, `han-coding/`, `han-github/`, `han-reporting/`, `han-feedback/`, `han-atlassian/`, `han-linear/`, and `han-plugin-builder/`; the `han/` meta-plugin pulls in `han-core`, `han-planning`, `han-coding`, `han-github`, and `han-reporting` through its `dependencies`. `han-planning` and `han-coding` depend on `han-core` like the GitHub and reporting layers and are bundled by the meta-plugin. `han-feedback`, `han-atlassian`, and `han-linear` depend on `han-core` like the other layers but are deliberately left out of the meta-plugin, so each is opt-in and installed on its own (`han-atlassian` additionally requires a configured Atlassian MCP server, and `han-linear` a configured Linear MCP server). `han-plugin-builder` depends on nothing and is likewise opt-in and installed on its own. The contributor-facing authoring guidance (how to build skills, agents, and plugins) lives inside `han-plugin-builder/skills/guidance/references/`, not under `docs/`; running the `guidance` skill with `init` vendors all three plugin-building skills into any repo's `.claude/skills/` under a `plugin-` prefix (`plugin-guidance`, `plugin-skill-builder`, and `plugin-agent-builder`, so they never collide with this plugin's own slash commands), plus a path-scoped rule index, so the skills run and the guidance surfaces with no dependency on the plugin being installed. The same plugin also ships those two interview-driven builder skills, `skill-builder` and `agent-builder`, that walk the design tree for a new skill or agent decision-by-decision and then review the finished artifact against that guidance. Documentation lives in `docs/` and covers the whole suite. Long-form docs in `docs/skills/{plugin}/{name}.md` and `docs/agents/han-core/{name}.md` are the canonical operator-facing source for every skill and every agent. The underlying definition (`han-core/skills/{name}/SKILL.md`, `han-planning/skills/{name}/SKILL.md`, `han-coding/skills/{name}/SKILL.md`, `han-github/skills/{name}/SKILL.md`, `han-reporting/skills/{name}/SKILL.md`, `han-feedback/skills/{name}/SKILL.md`, `han-atlassian/skills/{name}/SKILL.md`, `han-linear/skills/{name}/SKILL.md`, or `han-core/agents/{name}.md`) is the implementation.
 
 ## When to use which doc
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8755444..723e0a9 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -7,7 +7,7 @@ This page is for contributors: anyone adding, editing, or restructuring skills,
 ## TL;DR
 
 - Skills ship from the plugin that matches what they do: [`han-core/skills/`](./han-core/skills/) (research, analysis, documentation, operations), [`han-planning/skills/`](./han-planning/skills/) (specifying, planning, sequencing, breaking down, and stress-testing work before implementation), [`han-coding/skills/`](./han-coding/skills/) (writing, reviewing, analyzing, testing, investigating, and standardizing code), [`han-github/skills/`](./han-github/skills/) (GitHub-facing), [`han-reporting/skills/`](./han-reporting/skills/) (stakeholder reporting), or [`han-feedback/skills/`](./han-feedback/skills/) (feedback on Han itself); the contributor authoring guidance lives in [`han-plugin-builder/skills/`](./han-plugin-builder/skills/). All agents live in [`han-core/agents/{name}.md`](./han-core/agents/). See [Which plugin does the change belong in?](#which-plugin-does-the-change-belong-in) before you start.
-- Long-form docs (for humans deciding *when* and *how* to use a skill or agent) live in `docs/skills/{name}.md` and `docs/agents/{name}.md`.
+- Long-form docs (for humans deciding *when* and *how* to use a skill or agent) live in `docs/skills/{plugin}/{name}.md` and `docs/agents/han-core/{name}.md`.
 - **Every skill and every agent gets a long-form doc.** No exceptions. See the [coverage rule](./docs/templates/coverage-rule.md).
 - Use the [long-form skill template](./docs/templates/skill-long-form-template.md) or the [agent template](./docs/templates/agent-long-form-template.md).
 - The root [CLAUDE.md](./CLAUDE.md) carries the at-a-glance project map for assistants and contributors.
@@ -47,7 +47,7 @@ When a change adds, removes, or moves a skill between plugins, update the market
 2. Write the `SKILL.md`:
    - Frontmatter with `name`, `description`, `allowed-tools`. See [skill-description-frontmatter.md](./han-plugin-builder/skills/guidance/references/skill-building-guidance/skill-description-frontmatter.md).
    - Body: numbered steps, `${CLAUDE_SKILL_DIR}` paths for script references, extracted references under `references/`.
-3. Copy [the skill template](./docs/templates/skill-long-form-template.md) into `docs/skills/{name}.md` and fill it in. Every skill gets a long-form doc.
+3. Copy [the skill template](./docs/templates/skill-long-form-template.md) into `docs/skills/{plugin}/{name}.md` and fill it in. Every skill gets a long-form doc.
 4. Add the skill to the [Skills Index](./docs/skills/README.md) with a one-sentence scent line and a link.
 5. Add the skill to the catalog in [Root CLAUDE.md](./CLAUDE.md). The indexes and concept docs list skills without a running total, so there is no count to bump. If the skill belongs to a new category, add it to the category lists too.
 6. Update the marketplace registry at [`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json) if the new skill ships in a different plugin's component set.
@@ -55,7 +55,7 @@ When a change adds, removes, or moves a skill between plugins, update the market
 ## Adding an agent
 
 1. Create `han-core/agents/{name}.md` with frontmatter (`name`, `description`, `tools`, `model`) and the agent body. See [agent-domain-focus.md](./han-plugin-builder/skills/guidance/references/agent-building-guidelines/agent-domain-focus.md) for how narrow and named the domain vocabulary should be.
-2. Copy [the agent template](./docs/templates/agent-long-form-template.md) into `docs/agents/{name}.md` and fill it in. Every agent gets a long-form doc.
+2. Copy [the agent template](./docs/templates/agent-long-form-template.md) into `docs/agents/han-core/{name}.md` and fill it in. Every agent gets a long-form doc.
 3. Add the agent to the [Agents Index](./docs/agents/README.md) under the right role group.
 
 ## Editing an existing long-form doc
diff --git a/docs/templates/coverage-rule.md b/docs/templates/coverage-rule.md
index c6fb719..5205d7b 100644
--- a/docs/templates/coverage-rule.md
+++ b/docs/templates/coverage-rule.md
@@ -4,9 +4,9 @@ Every skill and agent in the han plugin gets a long-form doc. No exceptions.
 
 ## The Rule
 
-When you add a new skill, you create a long-form doc in `docs/skills/{name}.md` using [the skill template](./skill-long-form-template.md).
+When you add a new skill, you create a long-form doc in `docs/skills/{plugin}/{name}.md` using [the skill template](./skill-long-form-template.md).
 
-When you add a new agent, you create a long-form doc in `docs/agents/{name}.md` using [the agent template](./agent-long-form-template.md).
+When you add a new agent, you create a long-form doc in `docs/agents/han-core/{name}.md` using [the agent template](./agent-long-form-template.md).
 
 The long-form doc lands in the same pull request as the skill or agent definition. Not as a follow-up. Not "when there's time."