diff --git a/skills/build-ui-component/SKILL.md b/.agents/skills/build-ui-component/SKILL.md similarity index 100% rename from skills/build-ui-component/SKILL.md rename to .agents/skills/build-ui-component/SKILL.md diff --git a/skills/build-ui-component/references/animation.md b/.agents/skills/build-ui-component/references/animation.md similarity index 100% rename from skills/build-ui-component/references/animation.md rename to .agents/skills/build-ui-component/references/animation.md diff --git a/skills/build-ui-component/references/anti-patterns.md b/.agents/skills/build-ui-component/references/anti-patterns.md similarity index 100% rename from skills/build-ui-component/references/anti-patterns.md rename to .agents/skills/build-ui-component/references/anti-patterns.md diff --git a/skills/build-ui-component/references/collection.md b/.agents/skills/build-ui-component/references/collection.md similarity index 100% rename from skills/build-ui-component/references/collection.md rename to .agents/skills/build-ui-component/references/collection.md diff --git a/skills/build-ui-component/references/html.md b/.agents/skills/build-ui-component/references/html.md similarity index 100% rename from skills/build-ui-component/references/html.md rename to .agents/skills/build-ui-component/references/html.md diff --git a/skills/build-ui-component/references/polymorphism.md b/.agents/skills/build-ui-component/references/polymorphism.md similarity index 100% rename from skills/build-ui-component/references/polymorphism.md rename to .agents/skills/build-ui-component/references/polymorphism.md diff --git a/skills/build-ui-component/references/props.md b/.agents/skills/build-ui-component/references/props.md similarity index 100% rename from skills/build-ui-component/references/props.md rename to .agents/skills/build-ui-component/references/props.md diff --git a/skills/build-ui-component/references/react.md b/.agents/skills/build-ui-component/references/react.md similarity index 100% rename from skills/build-ui-component/references/react.md rename to .agents/skills/build-ui-component/references/react.md diff --git a/skills/build-ui-component/references/styling.md b/.agents/skills/build-ui-component/references/styling.md similarity index 100% rename from skills/build-ui-component/references/styling.md rename to .agents/skills/build-ui-component/references/styling.md diff --git a/skills/build-ui-component/references/videojs-element.md b/.agents/skills/build-ui-component/references/videojs-element.md similarity index 100% rename from skills/build-ui-component/references/videojs-element.md rename to .agents/skills/build-ui-component/references/videojs-element.md diff --git a/skills/build-ui-component/references/videojs.md b/.agents/skills/build-ui-component/references/videojs.md similarity index 100% rename from skills/build-ui-component/references/videojs.md rename to .agents/skills/build-ui-component/references/videojs.md diff --git a/skills/change-spf-behavior/SKILL.md b/.agents/skills/change-spf-behavior/SKILL.md similarity index 100% rename from skills/change-spf-behavior/SKILL.md rename to .agents/skills/change-spf-behavior/SKILL.md diff --git a/skills/commit-pr/SKILL.md b/.agents/skills/commit-pr/SKILL.md similarity index 100% rename from skills/commit-pr/SKILL.md rename to .agents/skills/commit-pr/SKILL.md diff --git a/skills/commit-pr/references/branch.md b/.agents/skills/commit-pr/references/branch.md similarity index 100% rename from skills/commit-pr/references/branch.md rename to .agents/skills/commit-pr/references/branch.md diff --git a/skills/commit-pr/references/commit.md b/.agents/skills/commit-pr/references/commit.md similarity index 100% rename from skills/commit-pr/references/commit.md rename to .agents/skills/commit-pr/references/commit.md diff --git a/skills/commit-pr/references/pr.md b/.agents/skills/commit-pr/references/pr.md similarity index 100% rename from skills/commit-pr/references/pr.md rename to .agents/skills/commit-pr/references/pr.md diff --git a/skills/commit-pr/references/scope.md b/.agents/skills/commit-pr/references/scope.md similarity index 100% rename from skills/commit-pr/references/scope.md rename to .agents/skills/commit-pr/references/scope.md diff --git a/skills/create-issue/SKILL.md b/.agents/skills/create-issue/SKILL.md similarity index 100% rename from skills/create-issue/SKILL.md rename to .agents/skills/create-issue/SKILL.md diff --git a/skills/create-skill/SKILL.md b/.agents/skills/create-skill/SKILL.md similarity index 89% rename from skills/create-skill/SKILL.md rename to .agents/skills/create-skill/SKILL.md index 135c9336..40205dd0 100644 --- a/skills/create-skill/SKILL.md +++ b/.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//SKILL.md` with only portable frontmatter: +4. Create `.agents/skills//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. diff --git a/skills/create-skill/references/patterns.md b/.agents/skills/create-skill/references/patterns.md similarity index 100% rename from skills/create-skill/references/patterns.md rename to .agents/skills/create-skill/references/patterns.md diff --git a/skills/create-skill/references/principles.md b/.agents/skills/create-skill/references/principles.md similarity index 100% rename from skills/create-skill/references/principles.md rename to .agents/skills/create-skill/references/principles.md diff --git a/skills/create-skill/references/structure.md b/.agents/skills/create-skill/references/structure.md similarity index 81% rename from skills/create-skill/references/structure.md rename to .agents/skills/create-skill/references/structure.md index 670c0b0a..098cfa7e 100644 --- a/skills/create-skill/references/structure.md +++ b/.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/ └── / ├── 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 diff --git a/skills/create-spf-behavior/SKILL.md b/.agents/skills/create-spf-behavior/SKILL.md similarity index 100% rename from skills/create-spf-behavior/SKILL.md rename to .agents/skills/create-spf-behavior/SKILL.md diff --git a/skills/design-api/SKILL.md b/.agents/skills/design-api/SKILL.md similarity index 100% rename from skills/design-api/SKILL.md rename to .agents/skills/design-api/SKILL.md diff --git a/skills/design-api/references/anti-patterns.md b/.agents/skills/design-api/references/anti-patterns.md similarity index 100% rename from skills/design-api/references/anti-patterns.md rename to .agents/skills/design-api/references/anti-patterns.md diff --git a/skills/design-api/references/extensibility.md b/.agents/skills/design-api/references/extensibility.md similarity index 100% rename from skills/design-api/references/extensibility.md rename to .agents/skills/design-api/references/extensibility.md diff --git a/skills/design-api/references/libraries.md b/.agents/skills/design-api/references/libraries.md similarity index 100% rename from skills/design-api/references/libraries.md rename to .agents/skills/design-api/references/libraries.md diff --git a/skills/design-api/references/principles.md b/.agents/skills/design-api/references/principles.md similarity index 100% rename from skills/design-api/references/principles.md rename to .agents/skills/design-api/references/principles.md diff --git a/skills/design-api/references/state.md b/.agents/skills/design-api/references/state.md similarity index 100% rename from skills/design-api/references/state.md rename to .agents/skills/design-api/references/state.md diff --git a/skills/design-api/references/typescript.md b/.agents/skills/design-api/references/typescript.md similarity index 100% rename from skills/design-api/references/typescript.md rename to .agents/skills/design-api/references/typescript.md diff --git a/skills/design-api/references/voices.md b/.agents/skills/design-api/references/voices.md similarity index 100% rename from skills/design-api/references/voices.md rename to .agents/skills/design-api/references/voices.md diff --git a/skills/document-spf-feature/SKILL.md b/.agents/skills/document-spf-feature/SKILL.md similarity index 100% rename from skills/document-spf-feature/SKILL.md rename to .agents/skills/document-spf-feature/SKILL.md diff --git a/skills/document-spf-use-case/SKILL.md b/.agents/skills/document-spf-use-case/SKILL.md similarity index 100% rename from skills/document-spf-use-case/SKILL.md rename to .agents/skills/document-spf-use-case/SKILL.md diff --git a/skills/implement-accessible-ui/SKILL.md b/.agents/skills/implement-accessible-ui/SKILL.md similarity index 100% rename from skills/implement-accessible-ui/SKILL.md rename to .agents/skills/implement-accessible-ui/SKILL.md diff --git a/skills/implement-accessible-ui/references/anti-patterns.md b/.agents/skills/implement-accessible-ui/references/anti-patterns.md similarity index 100% rename from skills/implement-accessible-ui/references/anti-patterns.md rename to .agents/skills/implement-accessible-ui/references/anti-patterns.md diff --git a/skills/implement-accessible-ui/references/aria.md b/.agents/skills/implement-accessible-ui/references/aria.md similarity index 100% rename from skills/implement-accessible-ui/references/aria.md rename to .agents/skills/implement-accessible-ui/references/aria.md diff --git a/skills/implement-accessible-ui/references/focus.md b/.agents/skills/implement-accessible-ui/references/focus.md similarity index 100% rename from skills/implement-accessible-ui/references/focus.md rename to .agents/skills/implement-accessible-ui/references/focus.md diff --git a/skills/implement-accessible-ui/references/keyboard.md b/.agents/skills/implement-accessible-ui/references/keyboard.md similarity index 100% rename from skills/implement-accessible-ui/references/keyboard.md rename to .agents/skills/implement-accessible-ui/references/keyboard.md diff --git a/skills/implement-accessible-ui/references/media.md b/.agents/skills/implement-accessible-ui/references/media.md similarity index 100% rename from skills/implement-accessible-ui/references/media.md rename to .agents/skills/implement-accessible-ui/references/media.md diff --git a/skills/implement-accessible-ui/references/react.md b/.agents/skills/implement-accessible-ui/references/react.md similarity index 100% rename from skills/implement-accessible-ui/references/react.md rename to .agents/skills/implement-accessible-ui/references/react.md diff --git a/skills/implement-spf-feature/SKILL.md b/.agents/skills/implement-spf-feature/SKILL.md similarity index 100% rename from skills/implement-spf-feature/SKILL.md rename to .agents/skills/implement-spf-feature/SKILL.md diff --git a/skills/implement-spf-use-case/SKILL.md b/.agents/skills/implement-spf-use-case/SKILL.md similarity index 100% rename from skills/implement-spf-use-case/SKILL.md rename to .agents/skills/implement-spf-use-case/SKILL.md diff --git a/skills/investigate-issue/SKILL.md b/.agents/skills/investigate-issue/SKILL.md similarity index 100% rename from skills/investigate-issue/SKILL.md rename to .agents/skills/investigate-issue/SKILL.md diff --git a/skills/maintain-agent-docs/SKILL.md b/.agents/skills/maintain-agent-docs/SKILL.md similarity index 90% rename from skills/maintain-agent-docs/SKILL.md rename to .agents/skills/maintain-agent-docs/SKILL.md index f1a47d23..8cbc9982 100644 --- a/skills/maintain-agent-docs/SKILL.md +++ b/.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/`. diff --git a/skills/migrate-css-to-tailwind/SKILL.md b/.agents/skills/migrate-css-to-tailwind/SKILL.md similarity index 100% rename from skills/migrate-css-to-tailwind/SKILL.md rename to .agents/skills/migrate-css-to-tailwind/SKILL.md diff --git a/skills/migrate-css-to-tailwind/references/migration.md b/.agents/skills/migrate-css-to-tailwind/references/migration.md similarity index 100% rename from skills/migrate-css-to-tailwind/references/migration.md rename to .agents/skills/migrate-css-to-tailwind/references/migration.md diff --git a/skills/review-accessibility/SKILL.md b/.agents/skills/review-accessibility/SKILL.md similarity index 100% rename from skills/review-accessibility/SKILL.md rename to .agents/skills/review-accessibility/SKILL.md diff --git a/skills/review-accessibility/references/checklist.md b/.agents/skills/review-accessibility/references/checklist.md similarity index 100% rename from skills/review-accessibility/references/checklist.md rename to .agents/skills/review-accessibility/references/checklist.md diff --git a/skills/review-api/SKILL.md b/.agents/skills/review-api/SKILL.md similarity index 100% rename from skills/review-api/SKILL.md rename to .agents/skills/review-api/SKILL.md diff --git a/skills/review-api/references/checklist.md b/.agents/skills/review-api/references/checklist.md similarity index 100% rename from skills/review-api/references/checklist.md rename to .agents/skills/review-api/references/checklist.md diff --git a/skills/review-branch/SKILL.md b/.agents/skills/review-branch/SKILL.md similarity index 100% rename from skills/review-branch/SKILL.md rename to .agents/skills/review-branch/SKILL.md diff --git a/skills/review-docs/SKILL.md b/.agents/skills/review-docs/SKILL.md similarity index 100% rename from skills/review-docs/SKILL.md rename to .agents/skills/review-docs/SKILL.md diff --git a/skills/review-docs/references/checklist.md b/.agents/skills/review-docs/references/checklist.md similarity index 100% rename from skills/review-docs/references/checklist.md rename to .agents/skills/review-docs/references/checklist.md diff --git a/skills/review-tailwind-migration/SKILL.md b/.agents/skills/review-tailwind-migration/SKILL.md similarity index 100% rename from skills/review-tailwind-migration/SKILL.md rename to .agents/skills/review-tailwind-migration/SKILL.md diff --git a/skills/review-tailwind-migration/references/checklist.md b/.agents/skills/review-tailwind-migration/references/checklist.md similarity index 100% rename from skills/review-tailwind-migration/references/checklist.md rename to .agents/skills/review-tailwind-migration/references/checklist.md diff --git a/skills/review-ui-component/SKILL.md b/.agents/skills/review-ui-component/SKILL.md similarity index 100% rename from skills/review-ui-component/SKILL.md rename to .agents/skills/review-ui-component/SKILL.md diff --git a/skills/review-ui-component/references/checklist.md b/.agents/skills/review-ui-component/references/checklist.md similarity index 100% rename from skills/review-ui-component/references/checklist.md rename to .agents/skills/review-ui-component/references/checklist.md diff --git a/skills/review-ui-component/references/checklists/general.md b/.agents/skills/review-ui-component/references/checklists/general.md similarity index 100% rename from skills/review-ui-component/references/checklists/general.md rename to .agents/skills/review-ui-component/references/checklists/general.md diff --git a/skills/review-ui-component/references/checklists/severity.md b/.agents/skills/review-ui-component/references/checklists/severity.md similarity index 100% rename from skills/review-ui-component/references/checklists/severity.md rename to .agents/skills/review-ui-component/references/checklists/severity.md diff --git a/skills/review-ui-component/references/checklists/videojs.md b/.agents/skills/review-ui-component/references/checklists/videojs.md similarity index 100% rename from skills/review-ui-component/references/checklists/videojs.md rename to .agents/skills/review-ui-component/references/checklists/videojs.md diff --git a/skills/write-api-reference/SKILL.md b/.agents/skills/write-api-reference/SKILL.md similarity index 100% rename from skills/write-api-reference/SKILL.md rename to .agents/skills/write-api-reference/SKILL.md diff --git a/skills/write-api-reference/references/builder-conventions.md b/.agents/skills/write-api-reference/references/builder-conventions.md similarity index 100% rename from skills/write-api-reference/references/builder-conventions.md rename to .agents/skills/write-api-reference/references/builder-conventions.md diff --git a/skills/write-api-reference/references/demo-patterns.md b/.agents/skills/write-api-reference/references/demo-patterns.md similarity index 100% rename from skills/write-api-reference/references/demo-patterns.md rename to .agents/skills/write-api-reference/references/demo-patterns.md diff --git a/skills/write-api-reference/references/mdx-structure.md b/.agents/skills/write-api-reference/references/mdx-structure.md similarity index 100% rename from skills/write-api-reference/references/mdx-structure.md rename to .agents/skills/write-api-reference/references/mdx-structure.md diff --git a/skills/write-api-reference/references/util-conventions.md b/.agents/skills/write-api-reference/references/util-conventions.md similarity index 100% rename from skills/write-api-reference/references/util-conventions.md rename to .agents/skills/write-api-reference/references/util-conventions.md diff --git a/skills/write-design-doc/SKILL.md b/.agents/skills/write-design-doc/SKILL.md similarity index 100% rename from skills/write-design-doc/SKILL.md rename to .agents/skills/write-design-doc/SKILL.md diff --git a/skills/write-design-doc/references/components.md b/.agents/skills/write-design-doc/references/components.md similarity index 100% rename from skills/write-design-doc/references/components.md rename to .agents/skills/write-design-doc/references/components.md diff --git a/skills/write-design-doc/references/features.md b/.agents/skills/write-design-doc/references/features.md similarity index 100% rename from skills/write-design-doc/references/features.md rename to .agents/skills/write-design-doc/references/features.md diff --git a/skills/write-design-doc/references/structure.md b/.agents/skills/write-design-doc/references/structure.md similarity index 100% rename from skills/write-design-doc/references/structure.md rename to .agents/skills/write-design-doc/references/structure.md diff --git a/skills/write-design-doc/templates/component-basic.md b/.agents/skills/write-design-doc/templates/component-basic.md similarity index 100% rename from skills/write-design-doc/templates/component-basic.md rename to .agents/skills/write-design-doc/templates/component-basic.md diff --git a/skills/write-design-doc/templates/component-compound.md b/.agents/skills/write-design-doc/templates/component-compound.md similarity index 100% rename from skills/write-design-doc/templates/component-compound.md rename to .agents/skills/write-design-doc/templates/component-compound.md diff --git a/skills/write-design-doc/templates/decision.md b/.agents/skills/write-design-doc/templates/decision.md similarity index 100% rename from skills/write-design-doc/templates/decision.md rename to .agents/skills/write-design-doc/templates/decision.md diff --git a/skills/write-design-doc/templates/feature-multi.md b/.agents/skills/write-design-doc/templates/feature-multi.md similarity index 100% rename from skills/write-design-doc/templates/feature-multi.md rename to .agents/skills/write-design-doc/templates/feature-multi.md diff --git a/skills/write-design-doc/templates/feature-single.md b/.agents/skills/write-design-doc/templates/feature-single.md similarity index 100% rename from skills/write-design-doc/templates/feature-single.md rename to .agents/skills/write-design-doc/templates/feature-single.md diff --git a/skills/write-docs/SKILL.md b/.agents/skills/write-docs/SKILL.md similarity index 100% rename from skills/write-docs/SKILL.md rename to .agents/skills/write-docs/SKILL.md diff --git a/skills/write-docs/patterns/code-examples.md b/.agents/skills/write-docs/patterns/code-examples.md similarity index 100% rename from skills/write-docs/patterns/code-examples.md rename to .agents/skills/write-docs/patterns/code-examples.md diff --git a/skills/write-docs/patterns/error-docs.md b/.agents/skills/write-docs/patterns/error-docs.md similarity index 100% rename from skills/write-docs/patterns/error-docs.md rename to .agents/skills/write-docs/patterns/error-docs.md diff --git a/skills/write-docs/references/component-libraries.md b/.agents/skills/write-docs/references/component-libraries.md similarity index 100% rename from skills/write-docs/references/component-libraries.md rename to .agents/skills/write-docs/references/component-libraries.md diff --git a/skills/write-docs/references/gold-standard.md b/.agents/skills/write-docs/references/gold-standard.md similarity index 100% rename from skills/write-docs/references/gold-standard.md rename to .agents/skills/write-docs/references/gold-standard.md diff --git a/skills/write-docs/references/seo.md b/.agents/skills/write-docs/references/seo.md similarity index 100% rename from skills/write-docs/references/seo.md rename to .agents/skills/write-docs/references/seo.md diff --git a/skills/write-docs/references/state-tooling.md b/.agents/skills/write-docs/references/state-tooling.md similarity index 100% rename from skills/write-docs/references/state-tooling.md rename to .agents/skills/write-docs/references/state-tooling.md diff --git a/skills/write-docs/references/writing-style.md b/.agents/skills/write-docs/references/writing-style.md similarity index 100% rename from skills/write-docs/references/writing-style.md rename to .agents/skills/write-docs/references/writing-style.md diff --git a/skills/write-docs/templates/concept.md b/.agents/skills/write-docs/templates/concept.md similarity index 100% rename from skills/write-docs/templates/concept.md rename to .agents/skills/write-docs/templates/concept.md diff --git a/skills/write-docs/templates/how-to.md b/.agents/skills/write-docs/templates/how-to.md similarity index 100% rename from skills/write-docs/templates/how-to.md rename to .agents/skills/write-docs/templates/how-to.md diff --git a/skills/write-docs/templates/readme.md b/.agents/skills/write-docs/templates/readme.md similarity index 100% rename from skills/write-docs/templates/readme.md rename to .agents/skills/write-docs/templates/readme.md diff --git a/skills/write-rfc/SKILL.md b/.agents/skills/write-rfc/SKILL.md similarity index 100% rename from skills/write-rfc/SKILL.md rename to .agents/skills/write-rfc/SKILL.md diff --git a/.github/workflows/changelog-prose.yml b/.github/workflows/changelog-prose.yml index 928537e9..e11ea597 100644 --- a/.github/workflows/changelog-prose.yml +++ b/.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. diff --git a/.gitignore b/.gitignore index 14307da2..3d8ccc4d 100644 --- a/.gitignore +++ b/.gitignore @@ -156,7 +156,6 @@ bun.lockb /.claude/worktrees/ /.claude/skills /.claude/plans -/.agents/skills /.opencode # Playwright diff --git a/AGENTS.md b/AGENTS.md index 3a9f048b..097cc62d 100644 --- a/AGENTS.md +++ b/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` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bc2a0d5c..0735cb4a 100644 --- a/CONTRIBUTING.md +++ b/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` diff --git a/build/scripts/check-workspace.mjs b/build/scripts/check-workspace.mjs index 3f3ec41b..eb1dac45 100644 --- a/build/scripts/check-workspace.mjs +++ b/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` ); } diff --git a/build/scripts/link-aliases.mjs b/build/scripts/link-aliases.mjs index bcecadcb..6bf28c6b 100644 --- a/build/scripts/link-aliases.mjs +++ b/build/scripts/link-aliases.mjs @@ -2,8 +2,7 @@ * Exposes the checked-in, host-neutral skill catalog through client-specific * discovery paths: * - * skills//SKILL.md (source) - * .agents/skills (generated junction) + * .agents/skills//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); diff --git a/internal/design/spf/conventions/behaviors.md b/internal/design/spf/conventions/behaviors.md index 47df4262..efdcce81 100644 --- a/internal/design/spf/conventions/behaviors.md +++ b/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. diff --git a/internal/design/spf/use-cases/README.md b/internal/design/spf/use-cases/README.md index 611dd609..826e522d 100644 --- a/internal/design/spf/use-cases/README.md +++ b/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. diff --git a/site/src/content/docs/reference/write-references.mdx b/site/src/content/docs/reference/write-references.mdx index 7cfe9401..f52a9754 100644 --- a/site/src/content/docs/reference/write-references.mdx +++ b/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