:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
SKILL.md API
One skill's SKILL.md as the store renders it, plus the same frontmatter as a JSON object.
It exists for a host that serves a skill as a file — the MCP skills extension serves
skill://<prefix>/<name>/SKILL.md and must list the file's frontmatter field for field.
A host that renders the frontmatter itself would drift from the store, and every digest taken over
the file would then disagree with the listing. So both halves of this response come from one
renderer.
Viewset: products/skills/backend/api/skills.py (LLMSkillViewSet.skill_md).
Rendering: products/skills/backend/marketplace/packaging.py (render_skill_md, frontmatter_document).
Endpoint
GET /api/projects/{team_id}/llm_skills/name/{skill_name}/skill-md/?version=N
| Param | Default | Behavior |
|---|---|---|
version |
latest version | Pins the response to one published version of the skill. |
Response:
{
"name": "my-skill",
"version": 3,
"content": "---\nname: my-skill\n...\n---\n\n<body>",
"frontmatter": { "name": "my-skill", "description": "...", "metadata": { "version": "3" } }
}
contentis the complete file: the frontmatter block, a blank line, then the body. Take a digest over this exact string.frontmatterequalsyaml.safe_loadof the block incontent. Keys use the spec's own names, so tool names arrive underallowed-tools.- The body is not paged.
MAX_SKILL_BODY_BYTEScaps it at 1 MB.
Authentication and access
- Session, personal API key and OAuth callers all work. The action requires the
llm_skill:readscope. - Object-level access control matches the other read actions on this viewset: a skill the caller cannot reach returns
403, not404. 404for an unknown skill name and for a version the skill never published.
Frontmatter shape
frontmatter_document maps storage shape to spec shape:
| Stored | Served |
|---|---|
name |
name |
description |
description |
license |
license, omitted when empty |
compatibility |
compatibility, omitted when empty |
metadata |
metadata, with version written last so it always wins |
allowed_tools |
allowed-tools, space separated, omitted when empty |
The spec has no top-level version field, so the platform version is parked under
metadata.version. It is a string, and it changes on every publish even when the body does not,
so the rendered file changes with it.
Resource manifests
Two read endpoints return what an MCP server needs to answer skills/get and skills/list:
every file of a skill, with the SHA-256 and byte size of the exact bytes the store serves for it.
A host rejects a skill whose bytes disagree with the listing, so both endpoints read the digests the store stamped on write.
They never load the skill body or any file content.
Viewset: products/skills/backend/api/skill_view_versions.py (manifest) and products/skills/backend/api/skills.py (manifests).
Builder: products/skills/backend/api/skill_manifest.py (build_skill_manifests).
One skill
GET /api/projects/{team_id}/llm_skills/name/{skill_name}/manifest/?version=N
Same version handling, llm_skill:read scope, object access check and 403/404 rules as skill-md.
An unservable skill also returns 200.
Many skills
GET /api/projects/{team_id}/llm_skills/manifests/?limit=&offset=&owner_id=&category=&exclude_category=
- The latest version of each skill, from the same access-filtered queryset and
limit/offsetpagination as the list. - Takes the list filters (
search,created_by_id,owner_id,category), plusexclude_categoryto leave one category out, for examplescout. - Weak
ETag,304onIf-None-Match,X-Skills-Version, private and no-cache headers, and the list throttles, all shared with the list. - One query for the page of skills and one for all their file rows, whatever the page size.
Entry shape
{
"name": "my-skill",
"version": 3,
"frontmatter": { "name": "my-skill", "description": "...", "metadata": { "version": "3" } },
"resources": [
{ "path": "SKILL.md", "sha256": "<hex>", "size": 1234, "content_type": "text/markdown" },
{ "path": "references/guide.md", "sha256": "<hex>", "size": 567, "content_type": "text/markdown" }
],
"file_count": 2,
"total_size": 1801,
"servable": true,
"unservable_reasons": []
}
SKILL.mdcomes first, then the bundled files sorted bypath. The Codex sidecaragents/openai.yamlfrom zip export is not a resource.frontmatterequals thefrontmatterofskill-mdfor the same version.sha256is bare hex. The MCP server adds thesha256:prefix and theskill://URI on the wire.servableis false whenunservable_reasonsholds any of these codes:
| Code | When |
|---|---|
too_many_files |
file_count is over MCP_MAX_SKILL_FILES (512), counting SKILL.md. |
too_large |
total_size is over MCP_MAX_SKILL_BYTES (16 MiB). |
digest_missing |
A stored digest or size is null, because the row predates the backfill. |
spec_problems |
compute_spec_problems reports a problem, the same check spec_problems shows authors. |
A null digest is not computed on read. The endpoint logs llma_skill_manifest_digest_missing with the skill names.
Run backfill_skill_digests before an MCP server serves skills from an environment.
Keep the stored digests in step with the renderer
skill_md_sha256 and skill_md_size are stamped from render_skill_md when a version is written.
A change to the renderer, including frontmatter_document, changes the served bytes of every existing skill.
Ship it with a run of backfill_skill_digests --recompute. Otherwise every manifest stops matching the bytes the store serves, and hosts ask every user to approve every skill again.