diff --git a/.agents/prompts/add-project.prompt.md b/.agents/prompts/add-project.prompt.md index 63921b7..22ac39e 100644 --- a/.agents/prompts/add-project.prompt.md +++ b/.agents/prompts/add-project.prompt.md @@ -15,21 +15,21 @@ Inputs (fill in before running): - Notes: anything known about docs location, package ids, or the story to tell Anything left blank is answered by recon, or asked using the intake questions in -`.agents/skills/add-project-intake/SKILL.md` (category, experimental, relationships, credit, and the +`skills/add-project-intake/SKILL.md` (category, experimental, relationships, credit, and the use-case story cannot be derived from the repository). ## Instructions Load and follow these skills, in order: -1. `.agents/skills/add-project-intake/SKILL.md` — the intake interview: the questions to ask before +1. `skills/add-project-intake/SKILL.md` — the intake interview: the questions to ask before writing anything, and the field each answer decides. -2. `.agents/skills/add-catalogue-project/SKILL.md` — the end-to-end procedure. -3. `.agents/skills/project-manifest-reference/SKILL.md` — fields and rules. -4. `.agents/skills/docs-aggregation-rules/SKILL.md` — the `docs` configuration. -5. `.agents/skills/use-case-authoring/SKILL.md` — the use cases. -6. `.agents/skills/github-repo-metadata/SKILL.md` — topics and stability signals. -7. `.agents/skills/site-validation-loop/SKILL.md` — the checks to run. +2. `skills/add-catalogue-project/SKILL.md` — the end-to-end procedure. +3. `skills/project-manifest-reference/SKILL.md` — fields and rules. +4. `skills/docs-aggregation-rules/SKILL.md` — the `docs` configuration. +5. `skills/use-case-authoring/SKILL.md` — the use cases. +6. `skills/github-repo-metadata/SKILL.md` — topics and stability signals. +7. `skills/site-validation-loop/SKILL.md` — the checks to run. Use the `catalogue-onboarder` agent if it is available. diff --git a/.agents/prompts/audit-projects.prompt.md b/.agents/prompts/audit-projects.prompt.md index 3967def..bb21238 100644 --- a/.agents/prompts/audit-projects.prompt.md +++ b/.agents/prompts/audit-projects.prompt.md @@ -13,12 +13,12 @@ Scope (fill in before running): ## Instructions -1. Read `.agents/skills/audit-catalogue-projects/SKILL.md` and follow its method and report format. -2. Load `.agents/skills/project-manifest-reference/SKILL.md`, - `.agents/skills/docs-aggregation-rules/SKILL.md`, - `.agents/skills/use-case-authoring/SKILL.md`, and - `.agents/skills/github-repo-metadata/SKILL.md` as the reference for the checks. -3. Load `.agents/skills/site-validation-loop/SKILL.md` for the commands and their meaning. +1. Read `skills/audit-catalogue-projects/SKILL.md` and follow its method and report format. +2. Load `skills/project-manifest-reference/SKILL.md`, + `skills/docs-aggregation-rules/SKILL.md`, + `skills/use-case-authoring/SKILL.md`, and + `skills/github-repo-metadata/SKILL.md` as the reference for the checks. +3. Load `skills/site-validation-loop/SKILL.md` for the commands and their meaning. Use the `catalogue-auditor` agent if it is available. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 9bb461b..c41b6b9 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -52,10 +52,10 @@ package is `src/`. ## Task routing - Adding a project → `.agents/agents/catalogue-onboarder.agent.md` and - `.agents/skills/add-project-intake/SKILL.md` (the questions to ask) then - `.agents/skills/add-catalogue-project/SKILL.md` (the procedure). + `skills/add-project-intake/SKILL.md` (the questions to ask) then + `skills/add-catalogue-project/SKILL.md` (the procedure). - Auditing/fixing the catalogue → `.agents/agents/catalogue-auditor.agent.md` and - `.agents/skills/audit-catalogue-projects/SKILL.md`. + `skills/audit-catalogue-projects/SKILL.md`. - Assessing a product repository's integration → `skills/purview-site-assessment/SKILL.md`. - Any other change → `.agents/` holds the manifest reference, docs-aggregation rules, use-case authoring rules, repo-metadata guidance, and the validation loop. diff --git a/.gitignore b/.gitignore index b04df9a..c73a61c 100644 --- a/.gitignore +++ b/.gitignore @@ -702,3 +702,10 @@ BenchmarkDotNet.Artifacts/ # Generated: Agent Skills mirrored from the product repositories by `just data-sync`. src/public/skills/ + +# Agent skills are installed into the universal .agents/skills/ folder, which is a local install: +# gitignored, and reproducible from the committed skills-lock.json with `just skills-install`. The +# skills this repository authors live in skills/ and are the only ones another repository installs. +# Per-agent folders (including .claude/) are local too - never commit a copy. +.agents/skills/ +.claude/ diff --git a/AGENTS.md b/AGENTS.md index 7018465..30558c6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,7 +6,7 @@ This repository builds the Purview-Dev public website: a fully static Astro + St both the project catalogue/release browser and the unified documentation portal for the Purview .NET product family (production URL: https://purview.dev). -Two agent tasks recur here, and both have a dedicated agent plus skills under `.agents/`: +Two agent tasks recur here, and both have a dedicated agent under `.agents/` and their skills in `skills/`: 1. **Add a project** — given a `purview-dev/` (or a collaboration repository), build its documentation, use cases, tags and metadata so it is fully integrated into the site. @@ -158,15 +158,15 @@ Do not assume this file contains everything; consult `.agents/` while planning. - `.github/copilot-instructions.md` — the condensed always-on rules for Copilot. - `.agents/agents/catalogue-onboarder.agent.md` — add and integrate a project end-to-end. - `.agents/agents/catalogue-auditor.agent.md` — audit (and repair) the whole catalogue. -- `.agents/skills/add-catalogue-project/SKILL.md` — the ordered onboarding procedure. -- `.agents/skills/add-project-intake/SKILL.md` — the intake interview: the questions to ask, what +- `skills/add-catalogue-project/SKILL.md` — the ordered onboarding procedure. +- `skills/add-project-intake/SKILL.md` — the intake interview: the questions to ask, what recon answers instead, and the field each answer decides. -- `.agents/skills/audit-catalogue-projects/SKILL.md` — the audit procedure and report format. -- `.agents/skills/project-manifest-reference/SKILL.md` — every manifest field and rule. -- `.agents/skills/docs-aggregation-rules/SKILL.md` — how repository docs become `/docs//`. -- `.agents/skills/use-case-authoring/SKILL.md` — concrete, audience-tagged use cases (ADR 0002). -- `.agents/skills/github-repo-metadata/SKILL.md` — topics, descriptions, stability signals. -- `.agents/skills/site-validation-loop/SKILL.md` — the checks, and how to reproduce failures. +- `skills/audit-catalogue-projects/SKILL.md` — the audit procedure and report format. +- `skills/project-manifest-reference/SKILL.md` — every manifest field and rule. +- `skills/docs-aggregation-rules/SKILL.md` — how repository docs become `/docs//`. +- `skills/use-case-authoring/SKILL.md` — concrete, audience-tagged use cases (ADR 0002). +- `skills/github-repo-metadata/SKILL.md` — topics, descriptions, stability signals. +- `skills/site-validation-loop/SKILL.md` — the checks, and how to reproduce failures. - `.agents/prompts/add-project.prompt.md`, `.agents/prompts/audit-projects.prompt.md`. `skills/` (repository root) is different: it holds the **consumer** skills that product repositories diff --git a/docs/decisions/0003-agent-tooling.md b/docs/decisions/0003-agent-tooling.md index 07d3606..be1a7a1 100644 --- a/docs/decisions/0003-agent-tooling.md +++ b/docs/decisions/0003-agent-tooling.md @@ -1,6 +1,6 @@ # ADR 0003 — Agent tooling for the catalogue: agents, skills, and a deterministic guard -- Status: accepted +- Status: superseded by [ADR 0014](0014-project-skills-live-in-skills.md) - Date: 2026-09-30 ## Context diff --git a/docs/decisions/0014-project-skills-live-in-skills.md b/docs/decisions/0014-project-skills-live-in-skills.md new file mode 100644 index 0000000..d5b23da --- /dev/null +++ b/docs/decisions/0014-project-skills-live-in-skills.md @@ -0,0 +1,38 @@ +# ADR 0014 — Project skills live in `skills/` + +- Status: accepted +- Date: 2026-11-15 + +## Context + +The skills CLI installs into `.agents/skills/`, its "universal" location, and `npx skills add +/` reads a repository's *published* skills. When a repository commits `.agents/skills/`, +the skills it installed for its own agents — someone else's guidance — become discoverable as though +the repository had written them, and the CLI's next update fights the committed copy. `.claude/` and +every other per-agent folder are the same problem one level down: a local copy that drifts from +`skills-lock.json` the moment the CLI updates it. + +## Decisions + +1. `skills//SKILL.md` is the only location for the skills a repository authors and publishes. +2. `.agents/skills/` is a local install: gitignored, never tracked, and reproducible from the + committed `skills-lock.json` with `just skills-install` (the SDK's `InstallPurviewSkills` target). +3. `.claude/` (and every other per-agent folder) is gitignored with it. +4. The catalogue-maintenance skills this repository used to keep in `.agents/skills/` moved to + `skills/`, with every pointer to them updated. `.agents/agents/` and `.agents/prompts/` stay where + they are: they are authored content and neither is something the CLI writes. +5. A repository holds the line with a test rather than a convention: nothing under `.agents/skills/` + may be tracked, and both ignore rules must be in place. The .NET repositories assert this in + `InstalledSkillTests`, and `purview-dev/build-sdk` asserts it in `RepositorySkillsSelfTests` and + documents it in the `purview-buildsdk-skills-layout` skill. + +## Consequences + +- `npx skills add purview-dev/` finds only the skills that repository publishes. +- A fresh clone has no `.agents/skills/` until `just skills-install` runs; the checks that compare an + install with the record are vacuous before that and strict afterwards. +- `skills-lock.json` stays committed — it is the record of what to install, and the only part of the + install that belongs in git. +- Two skills that were deliberately local become part of their repositories' published sets when they + move: `purview-buildsdk-settings-docs-sync` (build-sdk) and `purview-telemetry-benchmarks` + (telemetry-sourcegenerator), and this repository's eight catalogue skills. diff --git a/.agents/skills/add-catalogue-project/SKILL.md b/skills/add-catalogue-project/SKILL.md similarity index 100% rename from .agents/skills/add-catalogue-project/SKILL.md rename to skills/add-catalogue-project/SKILL.md diff --git a/.agents/skills/add-project-intake/SKILL.md b/skills/add-project-intake/SKILL.md similarity index 100% rename from .agents/skills/add-project-intake/SKILL.md rename to skills/add-project-intake/SKILL.md diff --git a/.agents/skills/audit-catalogue-projects/SKILL.md b/skills/audit-catalogue-projects/SKILL.md similarity index 100% rename from .agents/skills/audit-catalogue-projects/SKILL.md rename to skills/audit-catalogue-projects/SKILL.md diff --git a/.agents/skills/docs-aggregation-rules/SKILL.md b/skills/docs-aggregation-rules/SKILL.md similarity index 100% rename from .agents/skills/docs-aggregation-rules/SKILL.md rename to skills/docs-aggregation-rules/SKILL.md diff --git a/.agents/skills/github-repo-metadata/SKILL.md b/skills/github-repo-metadata/SKILL.md similarity index 100% rename from .agents/skills/github-repo-metadata/SKILL.md rename to skills/github-repo-metadata/SKILL.md diff --git a/.agents/skills/project-manifest-reference/SKILL.md b/skills/project-manifest-reference/SKILL.md similarity index 100% rename from .agents/skills/project-manifest-reference/SKILL.md rename to skills/project-manifest-reference/SKILL.md diff --git a/.agents/skills/site-validation-loop/SKILL.md b/skills/site-validation-loop/SKILL.md similarity index 100% rename from .agents/skills/site-validation-loop/SKILL.md rename to skills/site-validation-loop/SKILL.md diff --git a/.agents/skills/use-case-authoring/SKILL.md b/skills/use-case-authoring/SKILL.md similarity index 100% rename from .agents/skills/use-case-authoring/SKILL.md rename to skills/use-case-authoring/SKILL.md diff --git a/src/astro.config.ts b/src/astro.config.ts index b56cbba..8345b6b 100644 --- a/src/astro.config.ts +++ b/src/astro.config.ts @@ -208,7 +208,7 @@ export default defineConfig({ vitePlugin: { workspace: 'src/likec4' }, highlighting: { ref: 'v1.60.0' }, // The `docs` collection is the aggregated mirror of other repositories' - // Markdown (see .agents/skills/docs-aggregation-rules). Those pages were + // Markdown (see skills/docs-aggregation-rules). Those pages were // written for GitHub or mkdocs, so a ```likec4 fence there is often a // partial snippet rather than a diagram: relax validation for the // collection so one cannot fail this site's build — astroc4 warns and diff --git a/src/scripts/check-projects.ts b/src/scripts/check-projects.ts index 78d00ca..93e1587 100644 --- a/src/scripts/check-projects.ts +++ b/src/scripts/check-projects.ts @@ -697,7 +697,7 @@ function checkRepoMetadata(project: ResolvedProject, data: ReleaseCacheData): vo field: 'repository topics', observed: 'none', expected: 'topics that describe the project (they are the site tag chips)', - remediation: `set topics on ${project.repository} — see .agents/skills/github-repo-metadata/SKILL.md.`, + remediation: `set topics on ${project.repository} — see skills/github-repo-metadata/SKILL.md.`, }); }