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.

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.

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.

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.

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.

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

posthog:skill-create
{
  "name": "make-fractals",
  "description": "Generate fractal images as PNGs. Use when the user asks to make, render, or visualize fractals.",
  "body": "# make-fractals\n\nWhen to use... Workflow... Output contract...",
  "license": "MIT",
  "compatibility": "Requires Python 3.10+ with Pillow and numpy",
  "allowed_tools": ["Bash", "Write"],
  "metadata": { "author": "posthog", "category": "visualization" },
  "files": [
    { "path": "scripts/mandelbrot.py", "content": "...", "content_type": "text/x-python" },
    { "path": "references/primer.md", "content": "# Primer\n...", "content_type": "text/markdown" }
  ]
}

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

posthog:skill-get
{ "skill_name": "make-fractals" }

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.

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.

posthog:skill-archive
{ "skill_name": "make-fractals" }

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.

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:

---
name: phs
description: >-
  Access and run shared team skills stored in PostHog.
  Use when the user asks to list, run, or manage PostHog skills,
  or references /phs, "ph skills", or "posthog skills".
user-invocable: true
allowed-tools: mcp__posthog__skill-list, mcp__posthog__skill-get, mcp__posthog__skill-create, mcp__posthog__skill-update, mcp__posthog__skill-file-get, mcp__posthog__skill-file-create, mcp__posthog__skill-file-delete, mcp__posthog__skill-file-rename, mcp__posthog__skill-duplicate, mcp__posthog__skill-rename
---

# PostHog Skills Store

Local bridge to the PostHog Skills Store.

## Load and run a skill

When the user says `/phs <skill-name>`:

1. `skill-get(skill_name="<skill-name>")` to fetch body + file manifest
2. Read the `body` field — follow it as system instructions for this task
3. Use `skill-file-get` to pull bundled scripts/references on demand

## List skills

skill-list # all skills
skill-list(search="llma") # filter by keyword

## Create / update

skill-create(name="my-skill", description="...", body="# Instructions...")
skill-get → note version → skill-update(skill_name="...", base_version=N, body="...")

## Edit one part of an existing skill

skill-get → note version → pick the smallest primitive:

- body tweak: skill-update(skill_name="...", base_version=N, edits=[{old, new}])
- one bundled file: skill-update(skill_name="...", base_version=N, file_edits=[{path, edits:[{old, new}]}])
- add/remove/rename a file: skill-file-create / skill-file-delete / skill-file-rename

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.

• 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