Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions .agents/prompts/add-project.prompt.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
12 changes: 6 additions & 6 deletions .agents/prompts/audit-projects.prompt.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
6 changes: 3 additions & 3 deletions .github/copilot-instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
7 changes: 7 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -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/
18 changes: 9 additions & 9 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<repo>` (or a collaboration repository), build its
documentation, use cases, tags and metadata so it is fully integrated into the site.
Expand Down Expand Up @@ -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/<id>/`.
- `.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/<id>/`.
- `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
Expand Down
2 changes: 1 addition & 1 deletion docs/decisions/0003-agent-tooling.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
38 changes: 38 additions & 0 deletions docs/decisions/0014-project-skills-live-in-skills.md
Original file line number Diff line number Diff line change
@@ -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
<owner>/<repo>` 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/<name>/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/<repo>` 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.
2 changes: 1 addition & 1 deletion src/astro.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion src/scripts/check-projects.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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.`,
});
}

Expand Down
Loading