Skills Store

1---
2name: skills-store
3description: >-
4  Discover and use shared team skills stored in PostHog.
5  Use when the user asks to list, browse, load, or manage "shared skills",
6  "team skills", or references the "skills store" / "skill store".
7---
8 
9# PostHog Skills Store
10 
11Skills 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.
12 
13PostHog is the primary store for team-shared skills — always use the PostHog MCP skill tools to manage them.
14 
15## Available tools
16 
17| Tool                             | Purpose                                                    |
18| -------------------------------- | ---------------------------------------------------------- |
19| `posthog:llma-skill-list`        | List all available skills (Level 1 — names + descriptions) |
20| `posthog:llma-skill-get`         | Fetch a skill by name (Level 2 — body + file manifest)     |
21| `posthog:llma-skill-file-get`    | Fetch a single bundled file by path (Level 3 — on demand)  |
22| `posthog:llma-skill-create`      | Store a new skill (optionally with bundled files)          |
23| `posthog:llma-skill-update`      | Publish a new version (body, `edits`, or `file_edits`)     |
24| `posthog:llma-skill-file-create` | Add one bundled file to a skill (publishes a new version)  |
25| `posthog:llma-skill-file-delete` | Remove one bundled file from a skill                       |
26| `posthog:llma-skill-file-rename` | Rename one bundled file (move without rewriting content)   |
27| `posthog:llma-skill-duplicate`   | Duplicate an existing skill under a new name               |
28| `posthog:llma-skill-archive`     | Archive all versions of a skill by name (cannot be undone) |
29 
30Skills use progressive disclosure: discover by description, fetch the body only when relevant, and pull individual files on demand. Do not fetch every file eagerly.
31 
32## Discovering skills
33 
34List all available skills:
35 
36```json
37posthog:llma-skill-list
38{}
39```
40 
41Search by keyword (matches name and description):
42 
43```json
44posthog:llma-skill-list
45{ "search": "fractal" }
46```
47 
48`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.
49 
50## Loading and using a skill
51 
52### Step 1 — Fetch the skill by name
53 
54```json
55posthog:llma-skill-get
56{ "skill_name": "make-fractals" }
57```
58 
59The response contains:
60 
61- `body` — the full SKILL.md instructions (read these like system instructions for the task)
62- `license`, `compatibility`, `allowed_tools`, `metadata` — spec fields
63- `files[]` — manifest of bundled files (path + content_type only, not content)
64 
65### Step 2 — Follow the body
66 
67Read `body` and follow it. Treat it as your system instructions for this task.
68 
69### Step 3 — Fetch bundled files as needed
70 
71When the body references a script or reference doc, pull it on demand:
72 
73```json
74posthog:llma-skill-file-get
75{ "skill_name": "make-fractals", "file_path": "scripts/mandelbrot.py" }
76```
77 
78Only fetch files you actually need. If the body's decision tree points at one script, don't preload the others.
79 
80## Creating a skill
81 
82Follow the [Agent Skills specification](https://agentskills.io/specification) when creating skills:
83 
84- **`name`** — kebab-case, max 64 chars, no leading/trailing/consecutive hyphens
85- **`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.
86- **`body`** — keep under ~500 lines. Move detailed reference material, SQL, scripts, and long examples into bundled `files` so the body stays scannable.
87- **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.
88 
89Bundled files are optional and can be included in a single create call:
90 
91```json
92posthog:llma-skill-create
93{
94  "name": "make-fractals",
95  "description": "Generate fractal images as PNGs. Use when the user asks to make, render, or visualize fractals.",
96  "body": "# make-fractals\n\nWhen to use... Workflow... Output contract...",
97  "license": "MIT",
98  "compatibility": "Requires Python 3.10+ with Pillow and numpy",
99  "allowed_tools": ["Bash", "Write"],
100  "metadata": { "author": "posthog", "category": "visualization" },
101  "files": [
102    { "path": "scripts/mandelbrot.py", "content": "...", "content_type": "text/x-python" },
103    { "path": "references/primer.md", "content": "# Primer\n...", "content_type": "text/markdown" }
104  ]
105}
106```
107 
108## Updating a skill
109 
110Each write publishes a new immutable version. Always fetch first to get the current version, then update with `base_version` for concurrency checks:
111 
112```json
113posthog:llma-skill-get
114{ "skill_name": "make-fractals" }
115```
116 
117Pick 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.
118 
119### Editing the body
120 
121Full replacement (good for substantial rewrites):
122 
123```json
124posthog:llma-skill-update
125{
126  "skill_name": "make-fractals",
127  "body": "# make-fractals\n\nUpdated instructions...",
128  "base_version": 2
129}
130```
131 
132Incremental find/replace (good for small tweaks — no round-tripping the whole body):
133 
134```json
135posthog:llma-skill-update
136{
137  "skill_name": "make-fractals",
138  "edits": [
139    { "old": "Use Pillow for rendering.", "new": "Use Pillow ≥10.0 for rendering." }
140  ],
141  "base_version": 2
142}
143```
144 
145Each `edits[].old` must match exactly once. `body` and `edits` are mutually exclusive.
146 
147### Editing one bundled file
148 
149Use `file_edits` to patch a single file without resending any other file:
150 
151```json
152posthog:llma-skill-update
153{
154  "skill_name": "make-fractals",
155  "file_edits": [
156    {
157      "path": "scripts/mandelbrot.py",
158      "edits": [
159        { "old": "ITERATIONS = 100", "new": "ITERATIONS = 250" }
160      ]
161    }
162  ],
163  "base_version": 2
164}
165```
166 
167Non-targeted files carry forward unchanged. `file_edits` cannot add, remove, or rename files — use the per-file tools below for that.
168 
169### File-path parameter naming
170 
171The file-path parameter has two names depending on where it sits in the request, so don't guess:
172 
173- **`file_path`** — `llma-skill-file-get` and `llma-skill-file-delete` (the path is part of the URL).
174- **`path`** — `llma-skill-file-create`, plus the `files=[{path, …}]` array and `file_edits=[{path, …}]` (body fields on a file object).
175- **`old_path` / `new_path`** — `llma-skill-file-rename`.
176 
177Passing `path` to file-get produces a `/files/undefined/` 404. When in doubt, check the tool's input schema.
178 
179### Adding, removing, or renaming a file
180 
181Atomic per-file tools — each publishes a new version and returns the updated skill (read its `version` to chain further edits via `base_version`):
182 
183```json
184posthog:llma-skill-file-create
185{ "skill_name": "make-fractals", "path": "scripts/julia.py", "content": "...", "base_version": 2 }
186```
187 
188```json
189posthog:llma-skill-file-delete
190{ "skill_name": "make-fractals", "file_path": "scripts/old.py", "base_version": 3 }
191```
192 
193```json
194posthog:llma-skill-file-rename
195{ "skill_name": "make-fractals", "old_path": "scripts/julia.py", "new_path": "scripts/julia_set.py", "base_version": 4 }
196```
197 
198### Replacing the whole bundle (rare)
199 
200Passing `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.
201 
202## Archiving a skill
203 
204`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.
205 
206```json
207posthog:llma-skill-archive
208{ "skill_name": "make-fractals" }
209```
210 
211## Porting a local skill
212 
213To move a skill from a local SKILL.md directory (e.g. a local skills folder with `scripts/`, `references/`, `assets/` subdirs) into PostHog:
214 
2151. Read the local `SKILL.md` — use its frontmatter for `name`, `description`, `license`, `compatibility`, `allowed_tools`, `metadata`; the body after the frontmatter becomes `body`
2162. Walk the `scripts/`, `references/`, and `assets/` subdirs and collect each file as `{ path, content, content_type }`
2173. Call `posthog:llma-skill-create` with everything in one shot — the skill lands at v1 with its full bundle
218 
219The skill is then available to the whole team via `posthog:llma-skill-get`.
220 
221## Quick access: local bridge skill
222 
223Most 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".
224 
225Create a local skill in your agent's skills directory with these instructions:
226 
227```markdown
228---
229name: phs
230description: >-
231  Access and run shared team skills stored in PostHog.
232  Use when the user asks to list, run, or manage PostHog skills,
233  or references /phs, "ph skills", or "posthog skills".
234user-invocable: true
235allowed-tools: mcp__posthog__llma-skill-list, mcp__posthog__llma-skill-get, mcp__posthog__llma-skill-create, mcp__posthog__llma-skill-update, mcp__posthog__llma-skill-file-get, mcp__posthog__llma-skill-file-create, mcp__posthog__llma-skill-file-delete, mcp__posthog__llma-skill-file-rename, mcp__posthog__llma-skill-duplicate
236---
237 
238# PostHog Skills Store
239 
240Local bridge to the PostHog Skills Store.
241 
242## Load and run a skill
243 
244When the user says `/phs <skill-name>`:
245 
2461. `llma-skill-get(skill_name="<skill-name>")` to fetch body + file manifest
2472. Read the `body` field — follow it as system instructions for this task
2483. Use `llma-skill-file-get` to pull bundled scripts/references on demand
249 
250## List skills
251 
252llma-skill-list # all skills
253llma-skill-list(search="llma") # filter by keyword
254 
255## Create / update
256 
257llma-skill-create(name="my-skill", description="...", body="# Instructions...")
258llma-skill-get → note version → llma-skill-update(skill_name="...", base_version=N, body="...")
259 
260## Edit one part of an existing skill
261 
262llma-skill-get → note version → pick the smallest primitive:
263 
264- body tweak: llma-skill-update(skill_name="...", base_version=N, edits=[{old, new}])
265- one bundled file: llma-skill-update(skill_name="...", base_version=N, file_edits=[{path, edits:[{old, new}]}])
266- add/remove/rename a file: llma-skill-file-create / llma-skill-file-delete / llma-skill-file-rename
267```
268 
269The bridge is intentionally minimal — it just routes to the MCP tools. The real instructions live in PostHog and update without touching local files.
270 
271> **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.
272 
273## Default behavior
274 
275- **Always prefer PostHog MCP** for skill storage and retrieval
276- Only fall back to local files when PostHog MCP is unavailable
277- When asked to "save", "store", or "remember" a workflow, runbook, or multi-step procedure, store it as a PostHog skill
278- When asked to use a skill by name, use `llma-skill-get` first
279- When a skill references bundled files in its body, pull them with `llma-skill-file-get` only when needed — don't preload
280