Skip to content
Open
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
27 changes: 14 additions & 13 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,12 +38,12 @@ promotion criterion live in
cli:
role: command # command | skill | internal
parentCommand: audit # optional — nests this command under another
command: events # the user-typed word; required when role is command
command: events # the user-typed word, defaults to the variant id
```

The parser is `parseCliBlock` in `scripts/lib/skill-generator.js`. It enforces:

- `role` is one of `command`, `skill`, `internal` (default: `skill` if no `cli:` block is set at all)
- `role` is required and is one of `command`, `skill`, `internal`. A skill with no `cli:` block gets no `cliEntries` entry.
- `command` and `parentCommand` are kebab-case, 2–20 characters
- Neither field is a yargs reserved word (`help`, `version`, `completion`) or a wizard internal flag (`playground`, `benchmark`, `yara-report`, `local-mcp`, `ci`, `skill`)
- `default` (optional, boolean) marks the leaf `wizard <family>` runs by default (and pre-highlights it in the picker once a family has several)
Expand All @@ -58,8 +58,8 @@ lands. See [CONTRIBUTING.md § Flat vs. family](CONTRIBUTING.md#flat-vs-family--
### When you're about to change a `cli:` block

1. Read [CONTRIBUTING.md § Promotion criterion for `role: command`](CONTRIBUTING.md#promotion-criterion-for-role-command).
2. Run `npm test` — the parser's suite (`scripts/lib/tests/cli-block.test.js`) covers every naming-convention case.
3. Run `npm run build` — confirm the entry appears (or disappears) under `cliEntries` in `dist/skills/skill-menu.json` with the values you expect.
2. Run `pnpm test` — the parser's suite (`scripts/lib/tests/cli-block.test.js`) covers every naming-convention case.
3. Run `pnpm run build` — confirm the entry appears (or disappears) under `cliEntries` in `dist/skills/skill-menu.json` with the values you expect.
4. The wizard resolves new entries at runtime, so no wizard release is required unless the change needs wizard-side hooks (custom outro, content blocks, abort cases).

## Wizard CLI command mapping (old → new)
Expand All @@ -80,8 +80,9 @@ longer exist — only some keep an alias.

| Subcommand | Backing skill |
|---|---|
| `wizard audit events` | `audit-events` (default leaf) |
| `wizard audit all` | `audit` |
| `wizard audit events` | `audit-events` |
| `wizard audit all` | `audit` (default leaf) |
| `wizard audit attribution` | `audit-attribution` |
| `wizard audit autocapture` | `audit-autocapture` |
| `wizard audit feature-flags` | `audit-feature-flags` |
| `wizard audit identify` | `audit-identify` |
Expand All @@ -105,19 +106,19 @@ caller instead.
## Commands

```bash
npm install # Install dependencies
npm test # vitest run (parsers, expander, plugins, cli block)
npm run build # Full build: emits dist/skills/<id>.zip + manifests
npm run dev # Partial-rebuild dev server with watch
pnpm install # Install dependencies
pnpm test # vitest run (parsers, expander, plugins, cli block)
pnpm run build # Full build: emits dist/skills/<id>.zip + manifests
pnpm run dev # Partial-rebuild dev server with watch
```

## Repository conventions

- Skill content lives in markdown, never in JS/TS. The build pipeline reads YAML configs and stitches markdown together; it doesn't generate prose.
- The `cli:` block is the **single source of truth** for the wizard's command surface for any skill. Don't duplicate command names in the wizard repo; they're derived from the manifest.
- `additionalProperties: false` is set on the JSON Schema — adding a new field to the manifest shape is a coordinated change (bump the schema, bump consumer types in the wizard). See [PostHog/wizard CONTRIBUTING.md](https://github.com/PostHog/wizard/blob/main/CONTRIBUTING.md) for the wizard-side contract.
- Changing the `skill-menu.json` shape is a coordinated change. Update the consumer types in the wizard too. See [PostHog/wizard AGENTS.md](https://github.com/PostHog/wizard/blob/main/AGENTS.md) for the wizard-side contract.

## Companion projects

- **[wizard](https://github.com/PostHog/wizard)** — the CLI that consumes the manifest at build time and turns each `role: command` entry into a registered command.
- **[warlock](https://github.com/PostHog/warlock)** — the security scanner used by the wizard. Unrelated to skill content but lives alongside in the same engineering scope.
- **[wizard](https://github.com/PostHog/wizard)** — the CLI that fetches `skill-menu.json` at runtime and turns each `role: command` entry into a registered command.
- **[warlock](https://github.com/PostHog/warlock)** — PostHog's security scanner for agentic flows. context-mill depends on `@posthog/warlock`, and CI scans the built skill bundles with it (`scripts/scan-warlock.js`).
22 changes: 13 additions & 9 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ description: Audit captured events
cli:
role: command # command | skill | internal
parentCommand: audit # the command this skill nests under (optional)
command: events # the user-typed word; required when role is command
command: events # the user-typed word, defaults to the variant id
default: true # optional — the leaf `wizard <family>` runs by default
```

Expand All @@ -32,10 +32,11 @@ Three values for `role`:
|---|---|
| `command` | Registered as `wizard <parentCommand> <command>` (or `wizard <command>` if no parent). The user-facing CLI. |
| `skill` | Reachable only via `wizard skill <id>`. The full discoverable set. |
| `internal` | Hidden everywhere. Only reachable via `wizard --skill=<id>` (a dev escape hatch). Useful for in-progress skills that aren't ready to expose. |
| `internal` | Hidden from `wizard skill list`. Still runs via `wizard skill <id>`. Useful for in-progress skills that aren't ready to expose. |

Skills with **no** `cli:` block default to the `skill` role — they're
discoverable via `wizard skill list` but don't get a top-level command.
Skills with **no** `cli:` block get no entry in `cliEntries`. They never
appear in `wizard skill list` and don't get a top-level command. They still
run via `wizard skill <id>`.

The same skill can be either surface: `audit-events` sets `role: command` so it's
`wizard audit events`; a `role: skill` skill is only `wizard skill <id>`. One
Expand Down Expand Up @@ -100,7 +101,7 @@ Use the **full PostHog product name** with hyphens, not abbreviations.
| Session replay audit | `wizard audit session-replay` | `wizard audit replay` |
| Revenue analytics | `wizard revenue-analytics` | `wizard revenue` |
| Web analytics | `wizard web-analytics` | `wizard web` |
| AI Observability | `wizard llm-analytics` | `wizard llms` |
| AI Observability | `wizard ai-observability` | `wizard llms` |

The kebab-case / length / reserved-word checks in `parseCliBlock`
enforce the mechanics; this rule is the naming taste layer on top of
Expand Down Expand Up @@ -194,8 +195,11 @@ The base path is the same regardless of the skill's CLI role:
3. Add a `description.md` template and any `references/*.md` files.
4. If the skill should be a wizard command, add a `cli:` block per the
schema above.
5. Run `npm test && npm run build`. The build emits the new skill into
`dist/skills/<your-skill>.zip` and lists it in the manifest.
5. Run `pnpm test && pnpm run build`. The build emits one ZIP per variant,
`dist/skills/<your-skill>-<variant>.zip`, and lists it in the manifest.
An `id: all` variant emits `dist/skills/<your-skill>.zip` instead. A
bundled group (`packaging: bundle`) emits one `dist/skills/<group>.json`
with every variant inside, and those variants get no manifest entry.

## Adding a new command

Expand All @@ -204,7 +208,7 @@ When you've decided your skill meets the `role: command` criterion:
1. Add the `cli:` block to the skill's `config.yaml` with `role:
command`, the right `parentCommand` (if it nests under an existing
family), and `command`.
2. Confirm `npm run build` emits the entry under `cliEntries` inside
2. Confirm `pnpm run build` emits the entry under `cliEntries` inside
`dist/skills/skill-menu.json` with the right `parentCommand` /
`command` values. The wizard picks it up on its next invocation
(no wizard release needed).
Expand Down Expand Up @@ -234,7 +238,7 @@ manifest is published before the wizard tries to consume it.
(`parseCliBlock`, `expandSkillGroups`, JSDoc typedef for the `cli:` block)
- CLI entries emit: `scripts/lib/build-phases.js` (`generateCliEntries`)
- Tests for the cli block parser: `scripts/lib/tests/cli-block.test.js`
- The wizard's side of the contract: [PostHog/wizard CONTRIBUTING.md](https://github.com/PostHog/wizard/blob/main/CONTRIBUTING.md)
- The wizard's side of the contract: [PostHog/wizard AGENTS.md](https://github.com/PostHog/wizard/blob/main/AGENTS.md)

Questions: drop a note in
[#team-docs-and-wizard](https://posthog.slack.com/archives/C09GTQY5RLZ) or
Expand Down
64 changes: 43 additions & 21 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ We'd love your pull request!

The context mill gathers up-to-date content from multiple sources, packaging PostHog developer docs, prompts, and working example code into a versioned manifest which can be shipped anywhere as a zip file.

The [PostHog MCP server](https://github.com/PostHog/posthog/tree/master/services/mcp) currently fetches the examples repo manifest and exposes it to any MCP-compatible client as resources and slash commands. This is what currently powers the PostHog [wizard](https://github.com/PostHog/wizard).
The [PostHog MCP server](https://github.com/PostHog/posthog/tree/master/services/mcp) currently fetches the examples repo manifest and exposes it to any MCP-compatible client as resources and slash commands. The PostHog [wizard](https://github.com/PostHog/wizard) fetches `skill-menu.json` and skill ZIPs from the context mill's GitHub releases itself. It falls back to the AWS mirror at `context-mill.posthog.com` when GitHub fails.

## Context engine

Expand All @@ -37,38 +37,54 @@ These are more like model airplanes. They're dramatically simplified to make it
But the leanness makes these useful for agent-driven development. Use these as context to help your agent make better integration decisions about PostHog.

```
examples/
├── basics/
│ ├── next-app-router/ # Next.js 15 with App Router
│ ├── next-pages-router/ # Next.js 15 with Pages Router
│ ├── react-react-router/ # React with React Router
context-mill/
├── context/ # Skill sources, agent prompts, and build config
├── example-apps/ # One flat folder per example app
│ ├── next-app-router/ # Next.js with App Router
│ ├── next-pages-router/ # Next.js with Pages Router
│ ├── react-react-router-7-framework/ # React with React Router 7 (framework mode)
│ ├── react-tanstack-router-file-based/ # React with TanStack Router (file-based)
│ ├── react-tanstack-router-code-based/ # React with TanStack Router (code-based)
│ ├── tanstack-start/ # TanStack Start
│ └── django/ # Django
├── mcp-commands/ # MCP command prompts (`/command` in agents)
│ ├── django/ # Django
│ └── ... # Every other example app
└── scripts/ # Build scripts
```

## Build outputs

Run `npm run build` to generate the release artifacts:
Run `pnpm run build` to generate the release artifacts:

| Output | Description |
|--------|-------------|
| `dist/skills/<id>.zip` | Per-skill bundles (SKILL.md + references + shared docs) |
| `dist/skills/manifest.json` | Versioned manifest of every bundled skill and its download URL |
| `dist/skills/skill-menu.json` | Category groupings and `cliEntries` — the wizard's command lookup table |
| `dist/skills/<group>.json` | One file per bundled group (`packaging: bundle`), holding every variant |
| `dist/skills-mcp-resources.zip` | `manifest.json` plus every skill ZIP and bundle JSON in one archive |

Releases are cut as GitHub releases. Consumers (the wizard, the MCP server,
anything else) fetch `manifest.json` / `skill-menu.json` from the latest
release and download the per-skill ZIPs on demand.
Releases are cut as GitHub releases and mirrored to `context-mill.posthog.com`.
Each release carries these assets:

- `skills-mcp-resources.zip`, which holds `manifest.json`, the skill ZIPs, and the bundle JSONs
- one ZIP per skill
- `skill-menu.json`
- one `<group>.json` per bundled group
- `agent-menu.json` and the `agents-*.md` orchestrator prompts
- any reference docs (`*.md`) in `dist/skills/`

`manifest.json` is not a standalone release asset. It only ships inside
`skills-mcp-resources.zip`. The wizard fetches `skill-menu.json` from the
latest release and downloads skill ZIPs or bundle JSONs on demand.

### Manifest structure

The manifest describes the built skills — one resource per skill, with `id`,
`name`, `description`, `tags`, `uri`, and a `downloadUrl` pointing at the
GitHub release asset. Each bundled skill contains a `SKILL.md`, `references/`
GitHub release asset. Bundled variants (`packaging: bundle`) ship inside their
group's JSON, so they have no manifest entry. The manifest also has one
resource per doc in `context/docs.yaml`, with the doc's Markdown inline
instead of a `downloadUrl`. Each bundled skill contains a `SKILL.md`, `references/`
step files, and any shared docs pulled from posthog.com at build time.

### Adding a new skill
Expand Down Expand Up @@ -102,8 +118,9 @@ surface. If you (or your agent) knew an older command, here's where it went:

| Subcommand | Backing skill |
|---|---|
| `wizard audit events` | `audit-events` (the default leaf) |
| `wizard audit all` | `audit` |
| `wizard audit events` | `audit-events` |
| `wizard audit all` | `audit` (the default leaf) |
| `wizard audit attribution` | `audit-attribution` |
| `wizard audit autocapture` | `audit-autocapture` |
| `wizard audit feature-flags` | `audit-feature-flags` |
| `wizard audit identify` | `audit-identify` |
Expand All @@ -130,19 +147,24 @@ review to their owning team instead.
| Path | Owning team |
|---|---|
| `*` (everything else, including all other skills) | `@PostHog/team-wizard-docs` |
| `context/skills/integration/` | `@PostHog/team-wizard-docs` |
| `context/skills/error-tracking-upload-source-maps/` | `@PostHog/team-error-tracking` |
| `context/skills/error-tracking-link-releases/` | `@PostHog/team-error-tracking` |
| `context/skills/mcp-analytics/` | `@PostHog/team-mcp-analytics` |
| `context/skills/revenue-analytics/` | `@PostHog/team-web-analytics` |
| `context/skills/self-driving/` | `@PostHog/team-self-driving` |
| `context/skills/data-warehouse-source/` | `@PostHog/team-warehouse-sources` |
| `context/skills/mcp-analytics/` | `@PostHog/team-mcp-analytics` |
| `context/skills/metrics/` | `@PostHog/apm` |
| `context/agents/metrics/` | `@PostHog/apm` |
| `context/skills/revenue-analytics/` | `@PostHog/team-web-analytics` |
| `context/skills/web-analytics/` | `@PostHog/team-web-analytics` |
| `context/skills/integration/` | `@PostHog/team-wizard-docs` |
| `context/skills/replay-vision*/` | `@PostHog/team-replay` |
| `context/skills/ai-observability/` | `@PostHog/team-ai-observability` |
| `context/skills/llm-analytics/` | `@PostHog/team-ai-observability` |

Ownership is by directory. Skills not listed above (`audit`, `audit-*`,
`cost-cutting`, `creating-product-tours`, `error-tracking`, `events-audit`,
`feature-flags`, `llm-analytics`, `logs`, `migrate`, `omnibus`,
`posthog-best-practices`, `quack`, `tools-and-features`) fall through the
`creating-product-tours`, `error-tracking`, `events-audit`, `feature-flags`,
`integration-v2`, `logs`, `migrate`, `omnibus`, `posthog-best-practices`,
`quack`, `tools-and-features`, `tracing`) fall through the
default and are owned by `team-wizard-docs`. Today CODEOWNERS only
auto-requests review — approval is not a merge gate.

Expand Down
Loading
Loading