Using the PostHog skills store
Contents
Your team's coding agents (Claude Code, Cursor, Codex, Windsurf, and others) all support MCP. PostHog's skills store gives you a centralized, versioned place to store and share reusable agent skills — following the Agent Skills specification — across any tool, for any team member.
Shortcut: install the PostHog AI plugin. The PostHog AI plugin ships an official
skills-storeskill — maintained alongside the canonical version in the PostHog monorepo — that teaches your agent exactly how to discover, load, create, and update skills via the PostHog MCP tools. Install the plugin in Claude Code, Codex, Cursor, or Gemini CLI and your agent already knows how to use the store. The rest of this guide covers the same concepts in case you want to understand what's happening under the hood or roll your own bridge.
Why use PostHog as your skills store?
- Works in any MCP-connected agent — Claude Code, Cursor, Codex, Windsurf, VS Code, and more
- Centrally managed — Update a skill once, every team member gets the latest version on their next fetch
- Full version history — Every edit creates an immutable version, with
base_versionconcurrency checks - Bundled files — Skills can include scripts, references, and assets alongside the instructions
- Progressive disclosure — Agents list skills by description, load bodies on demand, and fetch bundled files only when needed
- No vendor lock-in — Not tied to a specific agent or IDE
- Non-engineers can contribute — Anyone on your team can create and maintain skills through the PostHog UI
How it works
A PostHog skill follows the Agent Skills specification: a body of instructions (the equivalent of a SKILL.md), plus optional bundled files, structured metadata, and an allowed_tools list.
The MCP server exposes the skills store through a dedicated family of tools:
| Tool | Purpose |
|---|---|
skill-list | List all available skills (name + description only) |
skill-get | Fetch a skill by name — returns the body and a manifest of bundled files |
skill-file-get | Fetch a single bundled file by path (on demand) |
skill-create | Store a new skill, optionally with bundled files |
skill-update | Publish a new version — provide full body, incremental edits, or file_edits |
skill-file-create | Add one bundled file to a skill (publishes a new version) |
skill-file-delete | Remove one bundled file from a skill |
skill-file-rename | Rename one bundled file (move without rewriting content) |
skill-duplicate | Duplicate an existing skill under a new name |
Agents use these with progressive disclosure: discover by description, fetch the body only when relevant, and pull individual files on demand — rather than loading everything up front.
Prerequisites
- A PostHog account with LLM analytics enabled
- The PostHog MCP server configured in your coding agent
Step 1: Create a skill
Let's create a skill called hog-release-notes that writes release notes in PostHog's voice.
Via the PostHog UI
- Navigate to LLM analytics > Skills
- Click New skill
- Name it
hog-release-notes - Add a description that explains when to use the skill — this is what agents use to discover it
- Paste your skill body (see example below)
- Optionally add bundled files,
allowed_tools,license,compatibility, or metadata - Click Create skill
Via MCP
Ask your agent to create the skill:
Or call skill-create directly:
Example skill body
A good skill body gives the agent all the context it needs — where to find information, what format to use, and any project-specific knowledge:
The more context you bake into the body, the less you need to explain each time you run the skill.
Bundled files (optional)
If your skill needs scripts, reference docs, or assets, include them in the same skill-create call:
The body can reference bundled files by path. Agents pull them with skill-file-get only when they actually need them.
Step 2: Use a skill from any agent
Once a skill exists in PostHog, any team member with the MCP server configured can use it.
Discover available skills
This calls skill-list and returns every skill's name + description — never the body. Agents pick the right skill from the description alone, without loading any bodies.
You can also filter:
Fetch and run a skill
The agent calls skill-get with skill_name: "hog-release-notes", receives the body + file manifest, reads the body as its system instructions, and gets to work — fetching any referenced bundled files via skill-file-get on demand.
This works identically in Claude Code, Cursor, Codex, or any other MCP-connected agent. The skill lives in PostHog, not in any particular tool.
Step 3: Set up a bridge skill (optional shortcut)
Step 2 is all you need. If you've installed the PostHog AI plugin, you can skip this step entirely — the plugin's skills-store skill already provides the bridge.
Otherwise, if your agent supports local skills (like Claude Code's .claude/skills/ directory), you can drop in a tiny DIY bridge that bootstraps into the PostHog skills store. You only need one generic bridge:
Claude Code example
Create a file at .claude/skills/posthog-skills-store/SKILL.md:
The bridge is intentionally thin — it just points at the canonical skills-store skill in PostHog, where the real instructions live. Updates to that remote skill automatically reach everyone on the team.
One local file, unlimited remote skills. But again, this is purely a convenience — everything the bridge does, you can do by asking your agent to use PostHog MCP skills directly.
Example: a full session
Here's what using the skills store looks like in practice — from running a skill, to updating it mid-session, to a teammate picking up the changes automatically.
Running the skill
The agent had everything it needed — the body told it where to find what's already published, how to discover what's new, and how to format the output.
Updating the skill mid-session
After reviewing the output, you decide the skill could be better:
That's it — the skill is updated in PostHog. You can review the diff in the PostHog UI to see exactly what changed.
A teammate benefits automatically
The next day, a teammate runs the same skill from their own agent (Claude Code, Cursor, or anything with PostHog MCP):
No sync, no PR, no "hey I updated the skill" message in Slack. The skill evolved, and everyone got the new version on their next fetch.
Updating and versioning skills
Every skill-update publishes a new immutable version.
Edit a skill
Via the UI: open the skill, click Edit latest, make changes, and click Publish version.
Via MCP: ask your agent to update it. Always fetch first so you have the current base_version:
The agent calls skill-get to read the current version, then skill-update with the new body and base_version. Fields you don't pass are carried forward. Pick the most surgical primitive for what you're changing — the API offers several so you don't have to round-trip the whole skill to tweak one part.
Use incremental edits
Instead of rewriting the entire skill body, you can use incremental find/replace edits via the edits parameter. This is useful for making small changes without risking accidental drift:
Each edit must have:
old— the exact text to find (must match exactly once in the body)new— the replacement text
Edits are applied sequentially. If old matches zero times or more than once, the update fails with an error indicating which edit failed.
You can use either body (full replacement) or edits (incremental), but not both in the same request.
Edit a single bundled file
Use file_edits to patch one bundled file without resending every file:
Non-targeted files carry forward unchanged. file_edits cannot add, remove, or rename files — use the per-file tools below for that.
Add, remove, or rename a file
Use atomic per-file tools when you need to add, delete, or rename a single bundled file. Each publishes a new version:
Add a file:
Delete a file:
Rename a file:
Replace the whole bundle (rare)
Passing files to skill-update replaces ALL bundled files — anything not in the array is dropped. Only use this when you intentionally want to wipe and reseed the bundle. For everything else, prefer file_edits or the per-file CRUD tools above.
Review changes
Use the compare view in the PostHog UI to see a diff between any two versions. This is especially useful when an agent has updated a skill — you can review exactly what it changed before the rest of your team picks it up.
Automatic propagation
Team members get the latest version on their next skill-get. No PRs, no syncing, no manual updates — just one source of truth in PostHog.
Porting a local skill
To move a skill from a local SKILL.md directory (e.g. ~/.claude/skills/<name>/ with scripts/, references/, and assets/ subdirs) into PostHog:
- Read the local
SKILL.md— use its frontmatter forname,description,license,compatibility,allowed_tools, andmetadata; the body after the frontmatter becomesbody - Walk the
scripts/,references/, andassets/subdirs and collect each file as{ path, content, content_type } - Call
skill-createwith everything in one shot — the skill lands at v1 with its full bundle
The skill is then available to the whole team via skill-get.
Skills vs prompts
PostHog also has a separate prompts tool family (prompt-list, prompt-get, prompt-create, prompt-update) for plain single-text prompts — LLM system prompts, short reusable text, and anything the SDK fetches at runtime for generations. Skills are the right choice whenever the workflow needs structured metadata, bundled files, or an allowed_tools surface. When in doubt, use skills.
Team workflow tips
- Use descriptive, kebab-case names —
review-frontend-pr,write-api-docs,check-security-headers - Invest in descriptions — discovery depends entirely on them; an agent decides whether to load your skill based on its description alone
- Discover before you create — run
skill-listto see what skills your team already has before creating a duplicate - Port local skills to PostHog — if you have useful
SKILL.mdfiles saved locally, move them (with their bundled files) to PostHog so the whole team benefits - Keep skills focused — one task per skill. A skill that does "everything" is a skill that does nothing well
- Don't preload bundled files — let the agent fetch them on demand via
skill-file-get; that's the whole point of progressive disclosure - Let agents update skills — after an agent follows a skill, ask it to suggest improvements, then update via
skill-update