writing-skills

为 PostHog Agent 编写技能

请阅读完整指南：docs/published/handbook/engineering/ai/writing-skills.md。

选择存放位置

• 对于通过 PostHog 工具、API 或客户代码开展的工作，请使用 products/<product>/skills/。这些技能会被发布。
• 对于需要检出 PostHog 仓库才能开展的工作，请使用 .agents/skills/。这些技能保留在仓库中。
• 仅限内部员工访问并不是移动技能的理由。不依赖检出的 MCP 工作流应保持发布状态。
• 对于混合型技能，请将客户诊断部分保持发布，并将 PostHog 开发步骤移入现有的内部技能或参考资料中。
• 已发布的工作流不得依赖内部技能文件。

hogli lint:skills 会检查这两个位置。下面的脚手架、构建和同步命令适用于已发布的产品技能。

快速工作流

# 1. Scaffold
hogli init:skill

# 2. Write your skill in products/{product}/skills/{skill-name}/SKILL.md

# 3. Lint
hogli lint:skills

# 4. Build to verify
hogli build:skills

# 5. Test locally with PostHog Desktop or a coding agent
hogli sync:skill -- --name <skill-name>

# 6. Delete the test skill (optional)
hogli unsync:skill -- --name <skill-name>

合并后会自动分发 —— CI 会发布到 PostHog/skills。

本仓库并不是唯一的来源。PostHog/context-mill 会发布综合技能 —— instrument-integration、instrument-product-analytics、instrument-feature-flags、instrument-error-tracking、instrument-llm-analytics、instrument-logs、instrument-metrics —— 并且每个实际使用的消费方都会将它们叠加在本仓库的技能之上，因此在同名技能上 context-mill 优先。如果你在 products/*/skills/ 下添加了上述名称之一，hogli lint:skills 会失败；请改为修改 context-mill 源。本地构建则是相反的情况：它们完全不包含综合技能，因此任何依赖综合技能的内容都必须叠加它，否则就会明确报错。合并位置参见 Context-mill 技能会覆盖本仓库的技能。

何时编写技能

当产品新增了功能，并且 Agent 需要知道如何使用它时。 技能讲的不是有哪些工具（那是 MCP 服务的事）—— 而是有经验的人会如何利用这些工具来处理一项工作。

问自己："如果客户让 Agent 用我的功能做 X，Agent 会知道正确的做法吗？" 如果不会，就编写一个技能。

多少个算太多？

技能数量是一种有预算的共享资源 —— Agent 会从_所有_技能描述组成的列表中进行选择，而许多 harness 会在该列表变长后将其截断，因此每多一个技能，都会让其他技能被触发的可能性降低。 与其编写许多单薄的技能，不如倾向于一小组聚焦的技能，每个技能都配有丰富的 references/：

• 新的触发场景 → 新的技能。 只有当某个技能的"何时使用它"与所有现有技能都明显不同时，它才值得拥有自己的入口。
• 更多细节 → references/，而不是新技能。 另一种失败模式、SDK 变体或查询目录，都是对现有工作的深入 —— 应将其添加到该技能的 references/ 中，而不是占用一个新名额。
• 合并近乎重复的同类技能。 共享同一诊断、缺陷类别或触发场景的技能应合并为一个带参考资料的技能，而不是两个。

关键规则

• 名称：小写 kebab-case，优先使用动名词形式（analyzing-llm-traces，而不是 llm-analytics）。绝不要以 posthog-* 为前缀。
• 描述：第三人称，具体，包含触发词以及何时使用它。最多 1024 个字符。
• 结构：SKILL.md 入口 + references/ 存放详细内容。保持 SKILL.md 在 500 行以内。
• Frontmatter：name 和 description 为必填项。
• 语气：描述工作流和推理过程，而不是僵化的脚本。相信 Agent 能够随机应变。
• 简洁：Agent 很聪明 —— 只包含它尚不具备的上下文。

技能结构

products/{product}/skills/{skill-name}/
    SKILL.md                         # entry point (required)
    references/                      # optional
        guidelines.md
        models-foo.md
        example-bar.md.j2            # Jinja2 template, rendered at build time
    scripts/                         # optional
        setup.sh

只会收集 references/ 和 scripts/ 子目录。其他目录会被忽略。

模板函数

以 .j2 结尾的文件在构建时由 products/posthog_ai/scripts/build_skills/ 使用 Jinja2 渲染。 扩展构建流水线，使 monorepo 始终保持为唯一可信来源 —— 当领域知识存在于代码中时（Pydantic 模型、查询运行器、函数注册表）， 应添加模板函数，而不是将其复制为会逐渐偏离的静态 markdown。

可用函数：

• pydantic_schema("dotted.path.to.Model") — 渲染 Pydantic 模型的 JSON Schema
• render_hogql_example({"kind": "TrendsQuery", ...}) — 将查询规格渲染为 HogQL SQL
• hogql_functions() — 返回所有可用的 HogQL 函数名

优秀示例：querying-posthog-data

• 清晰的入口点，链接到 30 多个参考文件
• 渐进式披露 —— Agent 只加载自己需要的内容
• 静态 .md 与生成的 .md.j2 内容混合
• 参见 products/posthog_ai/skills/querying-posthog-data/SKILL.md

反面示例：llm-analytics

一个涵盖 traces、experiments、evaluations、cost tracking、prompt management 的伞形技能。 范围太广 —— Agent 无法判断何时激活它。应拆分为多个聚焦的技能。