/skills-store

name: skills-store
description: >-
  Discover and use shared team skills stored in PostHog.
  Use when the user asks to list, browse, load, or manage "shared skills",
  "team skills", or references the "skills store" / "skill store".

PostHog Skills Store

Skills are reusable agent workflows stored in PostHog following the [Agent Skills specification](https://agentskills.io/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.

Available tools

| Tool | Purpose | | --------------------------- | ---------------------------------------------------------- | | `posthog:skill-list` | List all available skills (Level 1 — names + descriptions) | | `posthog:skill-get` | Fetch a skill by name (Level 2 — body + file manifest) | | `posthog:skill-file-get` | Fetch a single bundled file by path (Level 3 — on demand) | | `posthog:skill-create` | Store a new skill (optionally with bundled files) | | `posthog:skill-update` | Publish a new version (body, `edits`, or `file_edits`) | | `posthog:skill-file-create` | Add one bundled file to a skill (publishes a new version) | | `posthog:skill-file-delete` | Remove one bundled file from a skill | | `posthog:skill-file-rename` | Rename one bundled file (move without rewriting content) | | `posthog:skill-duplicate` | Duplicate an existing skill under a new name | | `posthog:skill-rename` | Rename a skill, keeping its versions, files, and owners | | `posthog:skill-archive` | Archive all versions of a skill by name (cannot be undone) |

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.

When the user names the skill, skip `skill-list` and call `skill-get` directly.

Loading and using a skill

Step 1 — Fetch the skill by name

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

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:

posthog:skill-file-get
{ "skill_name": "make-fractals", "file_path": "scripts/mandelbrot.py" }

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](https://agentskills.io/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:

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" }
  ]
}

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:

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.

Editing the body

Full replacement (good for substantial rewrites):

posthog:skill-update
{
  "skill_name": "make-fractals",
  "body": "# make-fractals\n\nUpdated instructions...",
  "base_version": 2
}

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

p