skills-store

What this skill does

# 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:llma-skill-list`        | List all available skills (Level 1 — names + descriptions) |
| `posthog:llma-skill-get`         | Fetch a skill by name (Level 2 — body + file manifest)     |
| `posthog:llma-skill-file-get`    | Fetch a single bundled file by path (Level 3 — on demand)  |
| `posthog:llma-skill-create`      | Store a new skill (optionally with bundled files)          |
| `posthog:llma-skill-update`      | Publish a new version (body, `edits`, or `file_edits`)     |
| `posthog:llma-skill-file-create` | Add one bundled file to a skill (publishes a new version)  |
| `posthog:llma-skill-file-delete` | Remove one bundled file from a skill                       |
| `posthog:llma-skill-file-rename` | Rename one bundled file (move without rewriting content)   |
| `posthog:llma-skill-duplicate`   | Duplicate an existing skill under a new name               |
| `posthog:llma-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:

```json
posthog:llma-skill-list
{}
```

Search by keyword (matches name and description):

```json
posthog:llma-skill-list
{ "search": "fractal" }
```

`llma-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

```json
posthog:llma-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
- `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:

```json
posthog:llma-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 `llma-skill-file-get`, so splitting keeps context lean.

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

```json
posthog:llma-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:

```json
posthog:llma-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):

```json
posthog:llma-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):

```json
posthog:llma-skill-update
{
  "skill_name": "make-fractals",
  "edits": [
    { "old": "Use Pillow for rendering.", "new": "Use Pillow ≥10.0 for rendering." }
  ],
  "base_version": 2
}
```

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:

```json
posthog:llma-skill-update
{
  "skill_name": "make-fractals",
  "file_edits": [
    {
      "path": "scripts/mandelbrot.py",
      "edits": [
        { "old": "ITERATIONS = 100", "new": "ITERATIONS = 250" }
      ]
    }
  ],
  "base_version": 2
}
```

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`** — `llma-skill-file-get` and `llma-skill-file-delete` (the path is part of the URL).
- **`path`** — `llma-skill-file-create`, plus the `files=[{path, …}]` array and `file_edits=[{path, …}]` (body fields on a file object).
- **`old_path` / `new_path`** — `llma-skill-file-rename`.

Passing `path` to file-get produces a `/files/undefined/` 404. 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`):

```json
posthog:llma-skill-file-create
{ "skill_name": "make-fractals", "path": "scripts/julia.py", "content": "...", "base_version": 2 }
```

```json
posthog:llma-skill-file-delete
{ "skill_name": "make-fractals", "file_path": "scripts/old.py", "base_version": 3 }
```

```json
posthog:llma-skill-file-rename
{ "skill_name": "make-fractals", "old_path": "scripts/julia.py", "new_path": "scripts/julia_set.py", "base_version": 4 }
```

### Replacing the whole bundle (rare)

Passing `files` to `llma-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

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

```json
posthog:llma-skill-archive
{ "skill_name": "make-fractals" }
```

## Porting a local skill

To move a skill from a lo