fix: install the published skills from the repo source

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

@@ -1,6 +1,8 @@
 ---
 name: create-evlog-adapter
 description: Create a new built-in evlog adapter to send wide events to an external observability platform. Use when adding a new drain adapter (e.g., for Elasticsearch, Honeycomb, SigNoz, etc.) to the evlog package. Covers source code, build config, package exports, tests, e2e, and all documentation.
+metadata:
+  internal: true
 ---
 
 # Create evlog Adapter
@@ -29,7 +31,7 @@ Recent examples: `feat(loki): add the Grafana Loki drain adapter`, `feat(clickho
 | 6 | `packages/evlog/test/toolkit/__snapshots__/api-surface.test.ts.snap` | Regenerated by running the tests after a build (`pnpm run build` then `pnpm test`) |
 | 7 | `apps/docs/content/4.integrate/adapters/{category}/{NN}.{name}.md` | Create adapter doc page in the right category |
 | 8 | `apps/docs/content/4.integrate/adapters/01.overview.md` | Add adapter to overview (frontmatter link + card) |
-| 9 | `apps/docs/skills/review-logging-patterns/SKILL.md` | Add adapter row in the Drain Adapters table + frontmatter description |
+| 9 | `skills/review-logging-patterns/SKILL.md` | Add adapter row in the Drain Adapters table + frontmatter description |
 | 10 | `.changeset/{name}-adapter.md` | Create changeset (`minor`) describing the adapter |
 | 11 | `.github/workflows/semantic-pull-request.yml` + `.github/pull_request_template.md` | Register `{name}` as a PR scope in both files |
 
@@ -166,7 +168,7 @@ Edit `apps/docs/content/4.integrate/adapters/01.overview.md` in **two** places (
 
 ## Step 8: Update the Public Skill
 
-In `apps/docs/skills/review-logging-patterns/SKILL.md` (published on evlog.dev via `/.well-known/skills/`):
+In `skills/review-logging-patterns/SKILL.md` (published on evlog.dev via `/.well-known/skills/`):
 
 1. Add a row to the **Drain Adapters** table: `| {Name} | evlog/{name} | {NAME}_API_KEY, ... |`
 2. Add the adapter name to the `description:` line in the YAML frontmatter

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

@@ -1,6 +1,8 @@
 ---
 name: create-evlog-enricher
 description: Create a new built-in evlog enricher to add derived context to wide events. Use when adding a new enricher (e.g., for deployment metadata, tenant context, feature flags, etc.) to the evlog package. Covers source code, tests, and all documentation.
+metadata:
+  internal: true
 ---
 
 # Create evlog Enricher
@@ -23,7 +25,7 @@ Enrichers live in the core package surface (`evlog/enrichers`), so use the `core
 | 2 | Same file — `createDefaultEnrichers()` | Decide whether the enricher belongs in the default composition (see below) |
 | 3 | `packages/evlog/test/toolkit/enrichers.test.ts` | Add tests (one `describe` block per enricher) |
 | 4 | `apps/docs/content/5.use-cases/5.enrichers.md` | Add a section for the enricher + update the import list and, if applicable, the "All built-in enrichers" default composition text |
-| 5 | `apps/docs/skills/review-logging-patterns/SKILL.md` | Add the enricher to the `Built-in:` line in the Enrichers section |
+| 5 | `skills/review-logging-patterns/SKILL.md` | Add the enricher to the `Built-in:` line in the Enrichers section |
 | 6 | `packages/evlog/README.md` | Add the enricher to the Built-in Enrichers section (root `README.md` is a symlink to it) |
 | 7 | `.changeset/{name}-enricher.md` | Create changeset (`minor`) |
 
@@ -119,7 +121,7 @@ Custom-enricher authoring docs live separately at `apps/docs/content/6.extend/5.
 
 ## Step 4: Update the Public Skill
 
-In `apps/docs/skills/review-logging-patterns/SKILL.md` (published on evlog.dev), find the **Enrichers** section and add the new enricher to the `Built-in:` line.
+In `skills/review-logging-patterns/SKILL.md` (published on evlog.dev), find the **Enrichers** section and add the new enricher to the `Built-in:` line.
 
 ## Step 5: Update README
 

.agents/skills/create-framework-integration/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: create-evlog-framework-integration
 description: Create a new evlog framework integration to add automatic wide-event logging to an HTTP framework. Use when adding middleware/plugin support for a framework (e.g., Koa, H3 standalone, Deno Fresh, etc.) to the evlog package. Covers source code, build config, package exports, tests, example app, and all documentation.
+metadata:
+  internal: true
 ---
 
 # Create evlog Framework Integration
@@ -45,7 +47,7 @@ feat({framework}): add {Framework} middleware integration
 | 8 | `apps/docs/content/1.start/3.installation.md` | Add card in "Choose Your Framework" |
 | 9 | `apps/docs/content/0.landing.md` | Add framework code snippet slot |
 | 10 | `apps/docs/app/components/features/FeatureFrameworks.vue` | Add framework tab |
-| 11 | `apps/docs/skills/review-logging-patterns/SKILL.md` | Add framework setup section + update frontmatter description |
+| 11 | `skills/review-logging-patterns/SKILL.md` | Add framework setup section + update frontmatter description |
 | 12 | `packages/evlog/README.md` | Add framework section + row in the Framework Support table |
 | 13 | `examples/{framework}/` | Create example app with test UI (auto-discovered by `pnpm example {framework}` — no root script needed) |
 | 14 | `.changeset/{framework}-integration.md` | Create changeset (`minor`) |
@@ -287,7 +289,7 @@ Icons use Simple Icons format: `i-simple-icons-{name}`.
 
 ## Step 9: Update the Public Skill
 
-In `apps/docs/skills/review-logging-patterns/SKILL.md` (published on evlog.dev):
+In `skills/review-logging-patterns/SKILL.md` (published on evlog.dev):
 
 1. Add `### {Framework}` in the **"Framework Setup"** section, in the same order as the docs
 2. Include: import + `initLogger` + middleware setup; native logger access; a `useLogger()` snippet, or the accessor that replaces it when the integration has no ALS; full pipeline example (`drain`, `enrich`, `keep`)

.agents/skills/create-map-rule/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: create-evlog-map-rule
 description: Add a new rule or a new framework adapter to `evlog map` in @evlog/cli. Use when adding a coverage check (requirement or opportunity) that scores entry points, or when extending the map scanner to a new framework. Covers rule source, registry, types, tests, docs, and the published skill.
+metadata:
+  internal: true
 ---
 
 # Create an `evlog map` Rule (or Framework Adapter)
@@ -43,7 +45,7 @@ Current requirements: `wide-event` (40), `audit` (25), `structured-errors` (20),
 | 4 | `packages/cli/test/map/rules.test.ts` | Add cases (the file has an ESLint-`RuleTester`-style `Case` harness — `runRuleSet` exercises one rule in isolation) |
 | 5 | `apps/docs/content/3.cli/3.rules.md` | Add a row to the Requirements or Opportunities table + a `### {title}` section |
 | 6 | `apps/docs/content/3.cli/4.scoring.md` | Requirements only: reflect the new weight in the scoring explanation |
-| 7 | `apps/docs/skills/review-logging-patterns/references/code-review.md` | Add a row to the matching rules table |
+| 7 | `skills/review-logging-patterns/references/code-review.md` | Add a row to the matching rules table |
 | 8 | `.changeset/{id}-map-rule.md` | Changeset for `"@evlog/cli": minor` |
 
 **Important**: Do NOT consider the task complete until all applicable touchpoints have been addressed.
@@ -118,7 +120,7 @@ Read `apps/docs/AGENTS.md` before touching anything under `apps/docs/`. Then in
 
 ## Step 7: Published Skill
 
-`apps/docs/skills/review-logging-patterns/references/code-review.md` mirrors the rules tables (requirements + opportunities) and maps each rule to a skill section. Add the row and, if the rule promotes a feature the skill documents elsewhere, link the section.
+`skills/review-logging-patterns/references/code-review.md` mirrors the rules tables (requirements + opportunities) and maps each rule to a skill section. Add the row and, if the rule promotes a feature the skill documents elsewhere, link the section.
 
 ## Step 8: Changeset
 
@@ -149,7 +151,7 @@ Teaching `evlog map` a new framework is a different, heavier change: the adapter
 | 5 | `packages/cli/test/map/adapters.test.ts` + `detect.test.ts` + `fixtures/` | Route extraction + detection tests against a fixture tree |
 | 6 | `packages/cli/src/lib/init/` | Decide whether `evlog init` gains the framework too (separate scope of work — flag it explicitly in the PR if not) |
 | 7 | `apps/docs/content/3.cli/2.map.md` + `0.overview.md` | Update the supported-frameworks statements |
-| 8 | `apps/docs/skills/review-logging-patterns/SKILL.md` | Update every "Nuxt, Nitro, Next.js, and TanStack Start" list (frontmatter description + CLI section) — same in `references/code-review.md` and `apps/docs/skills/build-audit-logs/SKILL.md` (Pass 2) and `analyze-logs/SKILL.md` (init suggestion) |
+| 8 | `skills/review-logging-patterns/SKILL.md` | Update every "Nuxt, Nitro, Next.js, and TanStack Start" list (frontmatter description + CLI section) — same in `references/code-review.md` and `skills/build-audit-logs/SKILL.md` (Pass 2) and `analyze-logs/SKILL.md` (init suggestion) |
 | 9 | `scripts/cli-sandbox.mjs` | Add the framework to `APPS` (reuse the map fixture) so `pnpm cli:sandbox` covers it and `--smoke` exercises every CLI command against it |
 | 10 | `.changeset/{framework}-map-adapter.md` | Changeset for `"@evlog/cli": minor` |
 

.agents/skills/write-evlog-content/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: write-evlog-content
-description: Write, review, and rewrite any evlog content: a docs page, the landing, a blog post, a package README, a skill, an AGENTS.md, a changeset. Load before drafting or editing prose in apps/docs/content, before writing a blog post, before touching a SKILL.md or an AGENTS.md, and whenever content is reviewed for voice, accuracy, or AI-generated slop. Carries the evlog voice, the atomic rules, the terminology, the competitor dossiers, and the AI-tell corpus with the legitimate twin for each tell.
+description: "Write, review, and rewrite any evlog content: a docs page, the landing, a blog post, a package README, a skill, an AGENTS.md, a changeset. Load before drafting or editing prose in apps/docs/content, before writing a blog post, before touching a SKILL.md or an AGENTS.md, and whenever content is reviewed for voice, accuracy, or AI-generated slop. Carries the evlog voice, the atomic rules, the terminology, the competitor dossiers, and the AI-tell corpus with the legitimate twin for each tell."
+metadata:
+  internal: true
 ---
 
 # Writing evlog content
@@ -41,7 +43,7 @@ Everything evlog ships as prose, on both sides of the line:
 | Read by | Surfaces | What decides quality |
 | --- | --- | --- |
 | People | docs pages, the landing, blog posts, the package READMEs | Whether the reader can act, and whether they believe the page |
-| Agents | `.agents/skills/`, `apps/docs/skills/`, the `AGENTS.md` files | Whether an agent does the right thing having read only this |
+| Agents | `.agents/skills/`, `skills/`, the `AGENTS.md` files | Whether an agent does the right thing having read only this |
 
 The house rules cross the line: punctuation, terminology, accuracy, dead links. Rhythm does not. A skill whose four steps read as four parallel imperatives is a procedure, and the scanner leaves rhythm alone there. See `rules/machine.md`.
 

.agents/skills/write-evlog-content/references/rules/machine.md

@@ -1,6 +1,6 @@
 # Rules for the surfaces an agent reads
 
-Applies to `.agents/skills/`, `apps/docs/skills/`, and every `AGENTS.md`. Read `universal.md` first: the house rules hold here too, punctuation included.
+Applies to `.agents/skills/`, `skills/`, and every `AGENTS.md`. Read `universal.md` first: the house rules hold here too, punctuation included.
 
 What changes is who is reading. A docs page is read by someone who can tell that a sentence is vague and go look elsewhere. A skill is read by a model that will act on it, at the altitude the file sets, without the option of doubting it. So the failure modes invert: rhythm stops mattering, and precision, ordering, and scope start deciding outcomes.
 

.agents/skills/write-evlog-content/references/surfaces/skill.md

@@ -3,7 +3,7 @@
 Two sets, and they are not the same product.
 
 - `.agents/skills/` is internal. It is loaded by agents working in this repository, and it can assume the checkout, the commands, and the conventions.
-- `apps/docs/skills/` is published, served from the docs site under `.well-known/skills`. It is loaded by someone else's agent, in someone else's repository, against evlog as a dependency.
+- `skills/` is published, served from the docs site under `.well-known/skills`. It is loaded by someone else's agent, in someone else's repository, against evlog as a dependency.
 
 A skill written for one and moved to the other is wrong in both directions: the internal one leaks repo paths, the published one is vague about a codebase it should know.
 

AGENTS.md

@@ -48,7 +48,8 @@ apps/docs/                 Docus documentation site — has its own AGENTS.md
 apps/*                     Framework playgrounds (next, nitro, nitro-v2, nuxthub, lab, telemetry, ...) — `pnpm playground` to pick one
 examples/                  ~22 runnable examples, one per framework — includes the community-*-skeleton dirs used by the create-adapter/enricher/framework skills
 scripts/                   Repo tooling (run-app, cli-sandbox, release-notes, content-lint)
-.agents/skills/            Internal skills for creating adapters, enrichers, and framework integrations, and for writing content
+.agents/skills/            Internal skills for creating adapters, enrichers, and framework integrations, and for writing content — each carries `metadata: internal: true` in its frontmatter so the skills CLI skips them for public installs
+skills/                     Published skills (analyze-logs, build-audit-logs, review-logging-patterns) — served by the docs site via `/.well-known/skills/` and discovered by `npx skills add hugorcd/evlog`
 ```
 
 ## Conventions
@@ -68,7 +69,7 @@ scripts/                   Repo tooling (run-app, cli-sandbox, release-notes, co
   - `.agents/skills/create-framework-integration/SKILL.md`
   - `.agents/skills/create-map-rule/SKILL.md` (also covers new `evlog map` framework adapters)
 - Writing or reviewing prose, a docs page, the landing, a blog post, a package README, a skill, an AGENTS.md, a changeset? Read `.agents/skills/write-evlog-content/SKILL.md` first, and run `pnpm content:lint <path>` before the review. It carries the voice, the atomic rules, the terminology, the competitor dossiers, and the AI-tell corpus with the legitimate twin for each tell. These files are content too: `pnpm content:lint --surface skill` and `--surface agents` rank them.
-- **Skills must stay in sync with the code.** There are two sets: internal skills in `.agents/skills/` and published skills in `apps/docs/skills/` (served from the docs site via `.well-known/skills`). When a change touches something a skill documents (an adapter, enricher, integration, API surface, or workflow), update the affected SKILL.md (and its `references/`) in the same PR. A skill that describes the old behavior is worse than no skill.
+- **Skills must stay in sync with the code.** There are two sets: internal skills in `.agents/skills/` and published skills in `skills/` at the repo root (served from the docs site via `.well-known/skills`, and discovered by a bare `npx skills add hugorcd/evlog`). When a change touches something a skill documents (an adapter, enricher, integration, API surface, or workflow), update the affected SKILL.md (and its `references/`) in the same PR. A skill that describes the old behavior is worse than no skill.
 
 ### Code style: no slop
 
@@ -135,7 +136,7 @@ A task is complete when **all** of the following pass:
 4. New public APIs have JSDoc
 5. New exports are registered in `package.json#exports`, `package.json#typesVersions`, and `tsdown.config.ts`
 6. If adapter/enricher/integration: the matching `.agents/skills/create-*/SKILL.md` was followed
-7. Any skill (internal `.agents/skills/` or published `apps/docs/skills/`) documenting the changed behavior was updated in the same PR
+7. Any skill (internal `.agents/skills/` or published `skills/`) documenting the changed behavior was updated in the same PR
 8. A changeset is included for any user-facing change (`pnpm changeset`)
 
 ## Boundaries

apps/docs/nuxt.config.ts

@@ -6,6 +6,16 @@ const contentCommitDates = readContentCommitDates(import.meta.dirname)
 export default defineNuxtConfig({
   extends: ['docus'],
 
+  docus: {
+    skills: {
+      // The published skills live at the repo root (`skills/`) so a bare
+      // `npx skills add hugorcd/evlog` discovers them: the installer only scans
+      // conventional root-level directories. Docus defaults to `skills/` inside
+      // the app, so point it back at the shared source of truth.
+      dir: '../../skills',
+    },
+  },
+
   experimental: {
     appManifest: true,
     emitRouteChunkError: 'automatic-immediate',

apps/evi/agent/lib/content/selection.test.ts

@@ -29,8 +29,8 @@ describe('groupOf', () => {
   it('groups a skill by its own directory, not by the whole tree', () => {
     expect(groupOf(page('.agents/skills/create-adapter/references/test-template.md', 100, 0, 'skill')))
       .toBe('.agents/skills/create-adapter')
-    expect(groupOf(page('apps/docs/skills/analyze-logs/SKILL.md', 100, 0, 'skill')))
-      .toBe('apps/docs/skills/analyze-logs')
+    expect(groupOf(page('skills/analyze-logs/SKILL.md', 100, 0, 'skill')))
+      .toBe('skills/analyze-logs')
   })
 
   it('keeps the flat surfaces in one group each', () => {

apps/evi/agent/skills/contributing/SKILL.md

@@ -18,7 +18,7 @@ What follows is the shape of the answer, so you know what to look for and what t
 - **The scope list is a closed set, and you read it before you write the title.** `.github/workflows/semantic-pull-request.yml` holds the only scopes CI accepts. Anything else fails `Validate PR title`, and a scope that merely sounds plausible (`evlog`, the package name, the app directory) is the usual way that happens. A change confined to `apps/docs` is `docs:`, with no scope: `docs` is already the type.
 - **A bug fix needs a failing regression test first**, then the fix.
 - **New exports** go in `packages/evlog/package.json` (`exports` and `typesVersions`) *and* `tsdown.config.ts`.
-- **Skills must stay in sync.** If a change touches something a skill documents, the SKILL.md changes in the same PR, both the internal `.agents/skills/` and the published `apps/docs/skills/`.
+- **Skills must stay in sync.** If a change touches something a skill documents, the SKILL.md changes in the same PR, both the internal `.agents/skills/` and the published `skills/`.
 
 ## The Definition of Done
 

apps/evi/agent/skills/repo-health-sweep/SKILL.md

@@ -33,7 +33,7 @@ describes.
 
 - Internal: `.agents/skills/*` (create-adapter, create-enricher,
   create-framework-integration, create-map-rule) and `apps/evi/agent/skills/*`.
-- Published: `apps/docs/skills/*` (analyze-logs, build-audit-logs,
+- Published: `skills/*` (analyze-logs, build-audit-logs,
   review-logging-patterns).
 - What to check: every API name, option, default, or adapter the skill shows.
   An `evlog.X` option must exist under that name; a function signature must be

apps/evi/agent/skills/self-review/SKILL.md

@@ -41,7 +41,7 @@ Something is produced and nothing consumes it. For each connection, extension an
 | Root `AGENTS.md` | Every framework integration exposes the same contract: `evlog()`, `useLogger()`, `log.fork()`. `evlog/workers` is the documented exception. |
 | `apps/evi/docs/capability-placement.md` | The two-layer rule: a file under `agent/` outside `agent/lib/` holding logic instead of wiring, an `agent/lib/` module with no colocated `*.test.ts`, or a caller check written inline instead of going through `agent/lib/trust.ts`. |
 | `packages/evlog/test/README.md` | A framework test driving the app by hand instead of through its real request driver. |
-| Root `AGENTS.md` | A behavior change whose matching `.agents/skills/` or `apps/docs/skills/` SKILL.md still describes the old shape. |
+| Root `AGENTS.md` | A behavior change whose matching `.agents/skills/` or `skills/` SKILL.md still describes the old shape. |
 
 ## C. Prose that outran the tools