skills-store

PostHog Skills Store

Skills are reusable agent workflows stored in PostHog following the Agent Skills specification — a body of instructions (SKILL.md) plus optional bundled files (scripts, references, assets), structured metadata, and an allowed_tools list.

PostHog is the primary store for team-shared skills — always use the PostHog MCP skill tools to manage them.

Reading skills through MCP cli mode

When the MCP exposes the learn command, use it for progressive-disclosure reads across both sources:

learn skills
learn -s "retention runbook"
learn project:team-retention
learn project:team-retention "references/query guide.md" -s weekly
learn project:team-retention "references/query guide.md" --lines 20:60

project: identifies skills in the current project's Skills store. posthog: identifies skills bundled and published by PostHog. Global search checks both and returns PostHog results first. Quote a file path when it contains spaces.

Use the skill tools below for writes, version management, and MCP clients that do not expose learn.

Available tools

Skills use progressive disclosure: discover by description, fetch the body only when relevant, and pull individual files on demand. Do not fetch every file eagerly.

Discovering skills

List all available skills:

posthog:skill-list
{}

Search by keyword (matches name and description):

posthog:skill-list
{ "search": "fractal"

skill-list returns only name + description — never the body. Use descriptions to decide which skill to fetch. The whole point of descriptions is that you can pick the right skill without loading any bodies.

Loading and using a skill

Step 1 — Fetch the skill by name

The response contains:

• body — the full SKILL.md instructions (read these like system instructions for the task)
• license, compatibility, allowed_tools, metadata — spec fields (see allowed_tools below)
• files[] — manifest of bundled files (path + content_type only, not content)

Step 2 — Follow the body

Read body and follow it. Treat it as your system instructions for this task.

Step 3 — Fetch bundled files as needed

When the body references a script or reference doc, pull it on demand:

Only fetch files you actually need. If the body's decision tree points at one script, don't preload the others.

Creating a skill

Follow the Agent Skills specification when creating skills:

• name — kebab-case, max 64 chars, no leading/trailing/consecutive hyphens
• description — explain what it does AND when to use it. Include keywords agents will search for. This is the only thing visible at discovery time — make it count.
• body — keep under ~500 lines. Move detailed reference material, SQL, scripts, and long examples into bundled files so the body stays scannable.
• Files — use scripts/ for executable code, references/ for docs, assets/ for templates/data. Agents pull these on demand via skill-file-get, so splitting keeps context lean.
• allowed_tools — the tools the skill asks to use. A harness that reads the skill from a file (zip export, git marketplace, a content=full bundle) treats the list as pre-approved. A harness that loads the skill over MCP, including the default content=stub bundle, ignores the list until the user approves that grant, so do not rely on it to widen access.

Bundled files are optional and can be included in a single create call:

Updating a skill

Each write publishes a new immutable version. Always fetch first to get the current version, then update with base_version for concurrency checks:

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. Anything you don't touch is carried forward from the current latest.

Editing the body

Full replacement (good for substantial rewrites):

Incremental find/replace (good for small tweaks — no round-tripping the whole body):

Each edits[].old must match exactly once. body and edits are mutually exclusive.

Editing one bundled file

Use file_edits to patch a single file without resending any other file:

Non-targeted files carry forward unchanged. file_edits cannot add, remove, or rename files — use the per-file tools below for that.

File-path parameter naming

The file-path parameter has two names depending on where it sits in the request, so don't guess:

• file_path — skill-file-get and skill-file-delete (the path is part of the URL). Both also accept path, so a manifest entry copied straight across works.
• path — skill-file-create, plus the files=[{path, …}] array and file_edits=[{path, …}] (body fields on a file object).
• old_path / new_path — skill-file-rename.

When in doubt, check the tool's input schema.

Adding, removing, or renaming a file

Atomic per-file tools — each publishes a new version and returns the updated skill (read its version to chain further edits via base_version):

Replacing 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.

Archiving a skill

skill-archive hides every active version of a skill by name. It cannot be undone — the skill disappears from skill-list and skill-get for the whole team. Use it to retire a skill entirely; to remove a single file use skill-file-delete, and to roll back content publish a new version instead.

Porting a local skill

To move a skill from a local SKILL.md directory (e.g. a local skills folder with scripts/, references/, assets/ subdirs) into PostHog:

1. Read the local SKILL.md — use its frontmatter for name, description, license, compatibility, allowed_tools, metadata; the body after the frontmatter becomes body
2. Walk the scripts/, references/, and assets/ subdirs and collect each file as { path, content, content_type }
3. Call posthog:skill-create with everything in one shot — the skill lands at v1 with its full bundle

The skill is then available to the whole team via posthog:skill-get.

Quick access: local bridge skill

Most coding agents support local skills or slash commands. A local bridge skill gives you a shortcut (e.g. /phs my-github) that routes straight to the PostHog skills API — faster and more deterministic than asking the agent to "use the PostHog skills store to load my-github".

Create a local skill in your agent's skills directory with these instructions:

The bridge is intentionally minimal — it just routes to the MCP tools. The real instructions live in PostHog and update without touching local files.

Agent-specific setup: Where to save this depends on your agent. For Claude Code, save as ~/.claude/skills/phs/SKILL.md. For other agents, consult your agent's docs on local skill or slash command configuration.

Default behavior

• Always prefer PostHog MCP for skill storage and retrieval
• Only fall back to local files when PostHog MCP is unavailable
• When asked to "save", "store", or "remember" a workflow, runbook, or multi-step procedure, store it as a PostHog skill
• When asked to use a skill by name, use learn project:<name> in MCP cli mode and skill-get in tools mode
• When a skill references bundled files in its body, pull them with learn project:<name> <path> or skill-file-get only when needed — don't preload