skills-store

PostHog 技能商店

技能是存储在 PostHog 中、可重复使用的 Agent 工作流，遵循 Agent Skills specification —— 包含一组指令（SKILL.md）以及可选的捆绑文件（脚本、参考资料、素材）、结构化元数据和 allowed_tools 列表。

PostHog 是团队共享技能的主要存储库——始终使用 PostHog MCP 技能工具来管理技能。

可用工具

工具	用途
posthog:skill-list	列出所有可用技能（第 1 级 — 名称 + 描述）
posthog:skill-get	按名称获取技能（第 2 级 — 正文 + 文件清单）
posthog:skill-file-get	按路径获取单个捆绑文件（第 3 级 — 按需获取）
posthog:skill-create	存储新技能（可选包含捆绑文件）
posthog:skill-update	发布新版本（正文、edits 或 file_edits）
posthog:skill-file-create	向技能添加一个捆绑文件（发布新版本）
posthog:skill-file-delete	移除技能中的一个捆绑文件
posthog:skill-file-rename	重命名一个捆绑文件（移动文件，不重写内容）
posthog:skill-duplicate	使用新名称复制现有技能
posthog:skill-rename	重命名技能，同时保留其版本、文件和所有者
posthog:skill-archive	按名称归档技能的所有版本（无法撤销）

技能采用渐进式披露：通过描述发现技能，仅在相关时获取正文，并按需提取单个文件。不要预先获取所有文件。

发现技能

列出所有可用技能：

posthog:skill-list
{}

按关键词搜索（匹配名称和描述）：

posthog:skill-list
{ "search": "fractal" }

skill-list 仅返回名称 + 描述，不会返回正文。根据描述判断要获取哪个技能。描述的目的就是让你无需加载任何正文，也能选出合适的技能。

当用户说出技能名称时，跳过 skill-list，直接调用 skill-get。

加载和使用技能

第 1 步 — 按名称获取技能

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

响应包含：

• body — 完整的 SKILL.md 指令（将其视为此任务的系统指令来阅读）
• license、compatibility、allowed_tools、metadata — 规范字段（参见下文的 allowed_tools）
• files[] — 捆绑文件清单（仅包含路径 + content_type，不含内容）

第 2 步 — 遵循正文

阅读 body 并遵循其中的内容。将其视为此任务的系统指令。

第 3 步 — 按需获取捆绑文件

当正文引用脚本或参考文档时，按需提取：

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

只获取实际需要的文件。如果正文的决策树指向某个脚本，不要预先加载其他脚本。

创建技能

创建技能时，请遵循 Agent Skills 规范：

• name — 使用 kebab-case，最多 64 个字符，不能以连字符开头或结尾，也不能包含连续连字符
• description — 说明技能的功能以及适用场景。加入 Agent 会搜索的关键词。这是发现技能时唯一可见的内容，因此请认真撰写。
• body — 控制在约 500 行以内。将详细的参考资料、SQL、脚本和长示例移至随附的 files，以便快速浏览正文。
• 文件 — 可执行代码放在 scripts/，文档放在 references/，模板和数据放在 assets/。Agent 会通过 skill-file-get 按需获取这些文件，因此拆分文件有助于精简上下文。
• allowed_tools — 技能请求使用的工具。通过文件读取技能的框架（zip 导出、git marketplace、content=full 包）会将此列表视为预先批准。通过 MCP 加载技能的框架（包括默认的 content=stub 包）会忽略此列表，直到用户批准该授权，因此不要指望它能扩大访问权限。

随附文件为可选项，也可以在一次创建调用中一并添加：

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

更新技能

每次写入都会发布一个新的不可变版本。请务必先获取当前版本，然后使用 base_version 执行更新以进行并发检查：

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

请选择最适合修改内容的原子操作 — API 提供了多种操作，因此只需修改某个部分时，无需往返传输整个技能。未修改的内容会从当前最新版本中沿用。

编辑正文

完整替换（适用于大幅改写）：

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

增量查找/替换（适用于小幅调整，无需往返传输整个正文）：

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

每个 edits[].old 必须且只能匹配一次。body 和 edits 不能同时使用。

编辑一个随附文件

使用 file_edits 修补单个文件，无需重新发送其他文件：

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

未指定的文件会保持不变。file_edits 不能添加、删除或重命名文件 — 请使用下文介绍的逐文件工具。

文件路径参数命名

文件路径参数根据其在请求中的位置有两种名称，因此请勿猜测：

• file_path — skill-file-get 和 skill-file-delete（路径是 URL 的一部分）。两者也接受 path，因此可以直接复制清单条目使用。
• path — skill-file-create，以及 files=[{path, …}] 数组和 file_edits=[{path, …}]（文件对象上的正文参数）。
• old_path / new_path — skill-file-rename。

如有疑问，请查看工具的输入架构。

添加、删除或重命名文件

原子逐文件工具 — 每个工具都会发布一个新版本并返回更新后的技能（读取其 version，即可通过 base_version 继续进行后续编辑）：

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

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

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

替换整个文件包（少见）

向 skill-update 传入 files 会替换所有随附文件 — 数组中未列出的内容都会被删除。仅当你确实想清空并重新填充文件包时才使用此操作。其他情况下，优先使用 file_edits 或上述逐文件 CRUD 工具。

归档技能

skill-archive 会按名称隐藏该技能的所有活跃版本。此操作无法撤销 — 整个团队都无法再通过 skill-list 和 skill-get 查看该技能。请用它彻底弃用某项技能；如需删除单个文件，请使用 skill-file-delete；如需回滚内容，请发布一个新版本。

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

移植本地技能

要将技能从本地 SKILL.md 目录（例如，包含 scripts/、references/、assets/ 子目录的本地技能文件夹）迁移到 PostHog：

1. 读取本地 SKILL.md——使用其中的 frontmatter 填写 name、description、license、compatibility、allowed_tools、metadata；frontmatter 之后的正文将成为 body
2. 遍历 scripts/、references/ 和 assets/ 子目录，将每个文件收集为 { path, content, content_type }
3. 一次性调用 posthog:skill-create 并传入所有内容——该技能会以 v1 版本及其完整资源包创建

之后，整个团队都可以通过 posthog:skill-get 使用该技能。

快速访问：本地桥接技能

大多数编码 Agent 都支持本地技能或斜杠命令。本地桥接技能可提供快捷方式（例如，/phs my-github），将请求直接路由到 PostHog 技能 API——比让 Agent“使用 PostHog 技能库加载 my-github”更快、更确定。

在 Agent 的技能目录中创建一个本地技能，并添加以下说明：

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

该桥接技能有意保持精简——它只负责将请求路由到 MCP 工具。真正的说明保存在 PostHog 中，更新时无需改动本地文件。

针对特定 Agent 的设置： 保存位置取决于所用的 Agent。对于 Claude Code，请保存为 ~/.claude/skills/phs/SKILL.md。对于其他 Agent，请查阅其关于本地技能或斜杠命令配置的文档。

默认行为

• 始终优先使用 PostHog MCP 存储和检索技能
• 只有在 PostHog MCP 不可用时才回退到本地文件
• 当有人要求“保存”“存储”或“记住”工作流、运行手册或多步骤流程时，将其存储为 PostHog 技能
• 当有人按名称要求使用技能时，通过 skill-get 获取
• 当技能正文引用了随附文件时，仅在需要时通过 skill-file-get 获取——不要预加载

相关技能

• working-with-skills — 在写入技能之前使用；了解技能的适用场景（项目中心、目录、运行手册、交接）
• authoring-scouts — 将技能转化为按计划运行的 scout