chore(root): move skills into agents directory

.agents/skills/create-skill/SKILL.md

@@ -12,7 +12,7 @@ Create a skill only when a repeatable vertical workflow needs instructions beyon
 1. Collect concrete trigger and non-trigger examples.
 2. Check existing skills for overlap; extend or consolidate before adding another metadata entry.
 3. Choose one coherent job and a globally unique, verb-first kebab-case name.
-4. Create `skills/<name>/SKILL.md` with only portable frontmatter:
+4. Create `.agents/skills/<name>/SKILL.md` with only portable frontmatter:
 
    ```yaml
    ---
@@ -36,4 +36,4 @@ Create another skill only when it has an independent trigger and useful standalo
 
 Input: “Create a repeatable workflow for reviewing package export changes.”
 
-Output: One focused `skills/review-package-exports/` skill with a precise trigger, compact procedure, example result, and validation loop.
+Output: One focused `.agents/skills/review-package-exports/` skill with a precise trigger, compact procedure, example result, and validation loop.

.agents/skills/create-skill/references/structure.md

@@ -1,9 +1,9 @@
 # Repository skill structure
 
-Checked-in skills are direct children of a flat, host-neutral catalog:
+Checked-in skills are direct children of the canonical agent catalog:
 
 ```text
-skills/
+.agents/skills/
 └── <globally-unique-action-name>/
     ├── SKILL.md
     ├── references/  # optional, conditional detail
@@ -11,7 +11,7 @@ skills/
     └── assets/      # optional, output inputs
 ```
 
-`pnpm link:aliases` exposes the whole catalog through generated `.agents/skills/`, `.claude/skills/`, and `.opencode/skills/` directory links. Do not create per-skill links or depend on recursive discovery inside a host's skills directory.
+`pnpm link:aliases` exposes the whole catalog through generated `.claude/skills/` and `.opencode/skills/` directory links. Do not create per-skill links or depend on recursive discovery inside a host's skills directory.
 
 ## Portable metadata
 

.agents/skills/maintain-agent-docs/SKILL.md

@@ -12,7 +12,7 @@ Keep agent guidance as a routing and correction layer over project sources, not
 - Put durable, broadly applicable repository facts in the nearest `AGENTS.md`.
 - Keep each `CLAUDE.md` as `@AGENTS.md` unless Claude-only behavior is genuinely required.
 - Put an explicit, repeatable vertical workflow in a skill.
-- Keep checked-in skills as direct children of top-level `skills/`; treat `.agents/skills/`, `.claude/skills/`, and `.opencode/skills/` as generated directory aliases.
+- Keep checked-in skills as direct children of `.agents/skills/`; treat `.claude/skills/` and `.opencode/skills/` as generated directory aliases.
 - Put conditional detail in a directly linked skill reference.
 - Put rules that can be mechanically checked in code, tests, lint, hooks, or `build/scripts/check-workspace.mjs`.
 - Put architecture rationale in `internal/design/`, `internal/decisions/`, or `rfc/`.

.github/workflows/changelog-prose.yml

@@ -100,7 +100,7 @@ jobs:
             Steps:
 
             1. **Load context:**
-               - Read `skills/write-docs/references/writing-style.md` for tone and style rules.
+               - Read `.agents/skills/write-docs/references/writing-style.md` for tone and style rules.
                - Read the raw changelog at `site/src/content/changelog/${{ steps.version.outputs.version }}.md`.
                - Read other existing `.md` files in `site/src/content/changelog/` (if any) to match their tone and format.
 

.gitignore

@@ -156,7 +156,6 @@ bun.lockb
 /.claude/worktrees/
 /.claude/skills
 /.claude/plans
-/.agents/skills
 /.opencode
 
 # Playwright

AGENTS.md

@@ -66,7 +66,7 @@ Use the narrowest relevant test/build while iterating. Before handoff, run check
 
 ## Skills and agent documentation
 
-Checked-in skills are direct children of top-level `skills/`. `pnpm install` exposes that catalog through generated `.agents/skills/`, `.claude/skills/`, and `.opencode/skills/` directory aliases. Load only the specialized workflow needed after inspecting relevant project sources.
+Checked-in skills are direct children of `.agents/skills/`. `pnpm install` exposes that canonical catalog through generated `.claude/skills/` and `.opencode/skills/` directory aliases. Load only the specialized workflow needed after inspecting relevant project sources.
 
 - API: `design-api`, `review-api`
 - UI: `build-ui-component`, `review-ui-component`, `implement-accessible-ui`, `review-accessibility`

CONTRIBUTING.md

@@ -57,7 +57,7 @@ git pull upstream main
 pnpm install
 ```
 
-This also exposes the checked-in top-level `skills/` catalog through generated `.agents/skills/`, `.claude/skills/`, and `.opencode/skills/` directory aliases. `AGENTS.md` is the canonical project guide; Claude's `CLAUDE.md` imports it.
+This also exposes the checked-in `.agents/skills/` catalog through generated `.claude/skills/` and `.opencode/skills/` directory aliases. `AGENTS.md` is the canonical project guide; Claude's `CLAUDE.md` imports it.
 
 > [!NOTE]
 > **Windows users:** Directory aliases use junctions and work without Developer Mode. If alias creation fails, `pnpm install` logs a warning and continues; the checked-in domain folders remain available.
@@ -245,7 +245,7 @@ Video.js 10 includes portable tooling for AI-assisted development. Read [`AGENTS
 
 ### Skills
 
-Focused workflows live as direct children of top-level `skills/`; host-specific discovery paths are generated aliases. A few of the most-used skills:
+Focused workflows live as direct children of `.agents/skills/`; host-specific discovery paths are generated aliases. A few of the most-used skills:
 
 | Skill                    | Use When                                                |
 | ------------------------ | ------------------------------------------------------- |
@@ -270,7 +270,7 @@ Focused workflows live as direct children of top-level `skills/`; host-specific
 When your changes introduce new patterns:
 
 - **Repo-wide recurring facts** → Update the nearest `AGENTS.md`
-- **Repeatable domain workflows** → Update the relevant skill under top-level `skills/`
+- **Repeatable domain workflows** → Update the relevant skill under `.agents/skills/`
 - **Mechanically enforceable rules** → Update code, tests, lint, hooks, or `check:workspace`
 
 ## Design Docs and RFCs
@@ -317,7 +317,7 @@ You want to do your work in a separate branch. In general, you want to make sure
 git checkout -b my-branch
 ```
 
-One helpful naming convention approximates [conventional commits](conventional-commit-style), e.g.:
+One helpful naming convention approximates [conventional commits][conventional-commit-style], e.g.:
 
 - `fix/some-issue`
 - `feat/my-media-store-feature`

build/scripts/check-workspace.mjs

@@ -537,14 +537,14 @@ function checkAgentContext() {
       .filter((line) => line && !line.startsWith('#'))
   );
 
-  for (const rule of ['/.agents/skills', '/.claude/skills', '/.claude/plans', '/.opencode']) {
+  for (const rule of ['/.claude/skills', '/.claude/plans', '/.opencode']) {
     if (!gitignoreRules.has(rule)) {
       warnings.push(`.gitignore: missing generated agent path ${rule}`);
     }
   }
-  for (const rule of ['/skills', '/skills/', 'skills', 'skills/']) {
+  for (const rule of ['/.agents/skills', '/.agents/skills/', '.agents/skills', '.agents/skills/']) {
     if (gitignoreRules.has(rule)) {
-      warnings.push(`.gitignore: canonical top-level skills catalog must not be ignored by ${rule}`);
+      warnings.push(`.gitignore: canonical .agents/skills catalog must not be ignored by ${rule}`);
     }
   }
 
@@ -582,8 +582,8 @@ function checkAgentContext() {
   }
 
   const agentsDir = join(ROOT, '.agents');
-  const skillsDir = join(ROOT, 'skills');
-  for (const alias of [join(ROOT, '.agents/skills'), join(ROOT, '.claude/skills'), join(ROOT, '.opencode/skills')]) {
+  const skillsDir = join(agentsDir, 'skills');
+  for (const alias of [join(ROOT, '.claude/skills'), join(ROOT, '.opencode/skills')]) {
     if (!existsSync(alias)) {
       warnings.push(`${relativePath(alias)}: missing compatibility alias to skills`);
     } else if (realpathSync(alias) !== realpathSync(skillsDir)) {
@@ -603,12 +603,12 @@ function checkAgentContext() {
   const skillNames = new Set();
   for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
     if (!entry.isDirectory()) {
-      warnings.push(`skills/${entry.name}: only skill directories are allowed at the catalog root`);
+      warnings.push(`.agents/skills/${entry.name}: only skill directories are allowed at the catalog root`);
       continue;
     }
     const skillDir = join(skillsDir, entry.name);
     if (!existsSync(join(skillDir, 'SKILL.md'))) {
-      warnings.push(`skills/${entry.name}: missing SKILL.md`);
+      warnings.push(`.agents/skills/${entry.name}: missing SKILL.md`);
       continue;
     }
     skillNames.add(entry.name);
@@ -618,7 +618,7 @@ function checkAgentContext() {
   const canonicalSkillFiles = new Set(canonicalSkillDirs.map((dir) => join(dir, 'SKILL.md')));
   for (const path of listFiles(skillsDir, (path) => path.endsWith('/SKILL.md'))) {
     if (!canonicalSkillFiles.has(path)) {
-      warnings.push(`${relativePath(path)}: skills must be direct children of top-level skills/`);
+      warnings.push(`${relativePath(path)}: skills must be direct children of .agents/skills/`);
     }
   }
 
@@ -673,7 +673,7 @@ function checkAgentContext() {
 
   if (metadataBytes > SKILL_METADATA_MAX_BYTES) {
     warnings.push(
-      `skills metadata: ~${estimatedTokens(metadataBytes)} tokens (${metadataBytes} bytes) exceeds ` +
+      `.agents/skills metadata: ~${estimatedTokens(metadataBytes)} tokens (${metadataBytes} bytes) exceeds ` +
         `~${estimatedTokens(SKILL_METADATA_MAX_BYTES)} tokens`
     );
   }

build/scripts/link-aliases.mjs

@@ -2,8 +2,7 @@
  * Exposes the checked-in, host-neutral skill catalog through client-specific
  * discovery paths:
  *
- *   skills/<skill-name>/SKILL.md  (source)
- *   .agents/skills                (generated junction)
+ *   .agents/skills/<skill-name>/SKILL.md  (source)
  *   .claude/skills                (generated junction)
  *   .claude/plans                 (generated junction)
  *   .opencode                     (generated junction)
@@ -16,7 +15,7 @@ import { dirname, join, resolve } from 'node:path';
 
 const root = resolve(import.meta.dirname, '../..');
 const agentsDir = join(root, '.agents');
-const skillsDir = join(root, 'skills');
+const skillsDir = join(agentsDir, 'skills');
 
 function linkState(path) {
   try {
@@ -52,7 +51,6 @@ function ensureAlias(relativePath, target) {
 
 mkdirSync(join(agentsDir, 'plans'), { recursive: true });
 
-ensureAlias('.agents/skills', skillsDir);
 ensureAlias('.claude/skills', skillsDir);
 ensureAlias('.claude/plans', join(agentsDir, 'plans'));
 ensureAlias('.opencode', agentsDir);

internal/design/spf/conventions/behaviors.md

@@ -305,7 +305,7 @@ A sketch is not a refactor commitment. If a side already conforms to current con
 
 ### Merging two behaviors — extra discipline
 
-> This section is the canonical reference for merge analysis. [`change-spf-behavior`](../../../../skills/change-spf-behavior/SKILL.md) applies it during a refactor.
+> This section is the canonical reference for merge analysis. [`change-spf-behavior`](../../../../.agents/skills/change-spf-behavior/SKILL.md) applies it during a refactor.
 
 When the decomposition check says merge, the refactor is **two separate analyses combined**, not one:
 
@@ -504,7 +504,7 @@ Why: each `listen` / `subscribe` call already returns its own removal function
 
 ## Per-type specialization
 
-> This section codifies the *destination shape* for per-type behaviors. [`change-spf-behavior`](../../../../skills/change-spf-behavior/SKILL.md) applies it with an explicit axis and cross-boundary constraint audit.
+> This section codifies the *destination shape* for per-type behaviors. [`change-spf-behavior`](../../../../.agents/skills/change-spf-behavior/SKILL.md) applies it with an explicit axis and cross-boundary constraint audit.
 
 When a behavior's logic varies by media type (video / audio / text), prefer **separate exports per type** over a single behavior with a `config.type` discriminant.
 

internal/design/spf/use-cases/README.md

@@ -147,6 +147,6 @@ Initially empty; populated as docs land. Candidates flagged in source material (
 - [`../features/clusters.md` § Feature classification axes](../features/clusters.md#feature-classification-axes) — the parent classification section. The Media-src-vs-Player axis here is the Case-1 (Media-src feature) vs Case-2 (Player feature / use-case composition) split implicit in Notion's "Composition cases per mode" framing.
 - [`../conventions/behaviors.md` § Inverse: behaviors that operate uniformly across tracks](../conventions/behaviors.md#inverse-behaviors-that-operate-uniformly-across-tracks) — the discipline that lets composition variants compose existing behaviors unchanged; the `updateMediaSourceDuration` worked example.
 - [`../evaluation-axes.md`](../evaluation-axes.md) — current axes for evaluating SPF code; will likely expand to formalize the Path-A-vs-Path-B judgment for use-case behavior customization.
-- [`document-spf-use-case`](../../../../skills/document-spf-use-case/SKILL.md) — maintains use-case composition records.
-- [`implement-spf-use-case`](../../../../skills/implement-spf-use-case/SKILL.md) — implements work from those records.
+- [`document-spf-use-case`](../../../../.agents/skills/document-spf-use-case/SKILL.md) — maintains use-case composition records.
+- [`implement-spf-use-case`](../../../../.agents/skills/implement-spf-use-case/SKILL.md) — implements work from those records.
 - [SPF Epics Working Doc](https://www.notion.so/35f97a7f89d08123a13fecab1ca1cac4) — source material; Composition cases per mode framing; Case-2 epics tracked here.

site/src/content/docs/reference/write-references.mdx

@@ -44,7 +44,7 @@ The builder relies on file naming conventions to discover components:
 | React component | `packages/react/src/ui/{name}/` | `packages/react/src/ui/play-button/` |
 | Multi-part detection | `index.parts.ts` | `packages/react/src/ui/slider/index.parts.ts` |
 
-If the builder output is missing or incomplete, check that your files match these conventions. See `skills/write-api-reference/references/builder-conventions.md` for the full list.
+If the builder output is missing or incomplete, check that your files match these conventions. See `.agents/skills/write-api-reference/references/builder-conventions.md` for the full list.
 
 ## Create demo files