用途：这是 PostHog 编写 agent skills 的指南。skill 不是罗列 MCP 工具，而是描述有经验的人如何使用这些工具完成一项工作。当产品新增功能、需要让 agent 知道正确做法时，就应编写 skill。判断标准：若客户让 agent 用该功能做 X，agent 是否知道正确路径；若不知道就写一个 skill。
主要能力与结构：skill 位于 products/{product}/skills/{skill-name}/，入口文件为 SKILL.md（必填），可选的 references/ 与 scripts/ 子目录会被收集，其他目录忽略。references/ 内可放 guidelines.md、models-foo.md，以及以 .j2 结尾的 Jinja2 模板（构建时渲染）。命名用 lower kebab-case，倾向动名词形式（如 analyzing-llm-traces），不要加 posthog- 前缀。description 用第三人称，具体并含触发词与使用时机，最多 1024 字符。frontmatter 必填 name 和 description。SKILL.md 建议控制在 500 行以内，正文描述工作流与推理而非死板脚本，只写 agent 尚不具备的上下文。
必要用法：按给出的快速流程操作——hogli init:skill 生成骨架；在 products/{product}/skills/{skill-name}/SKILL.md 编写；hogli lint:skills 检查；hogli build:skills 构建验证；用 PostHog Code 或编码 agent 本地测试；hogli sync:skill -- --name <名称> 同步；可选 hogli unsync:skill -- --name <名称> 删除测试 skill。合并后分发自动进行，由 CI 发布到 PostHog/skills。
模板函数：.j2 文件由 products/posthog_ai/scripts/build_skills.py 在构建时用 Jinja2 渲染。可用 pydantic_schema("dotted.path.to.Model") 渲染 Pydantic 模型的 JSON Schema；render_hogql_example({"kind": "TrendsQuery", ...}) 将查询规范渲染为 HogQL SQL；hogql_functions() 返回全部可用 HogQL 函数名。若领域知识在代码中，应扩展构建管线加模板函数，而不是复制静态 markdown 以免漂移。
适用场景：为产品新功能编写聚焦的 skill。反面例子是 llm-analytics 这类覆盖 traces、experiments、evaluations、成本追踪、prompt 管理的大而全 skill，太宽泛导致 agent 无法判断何时启用，应拆分为多个聚焦 skill。正面例子是 querying-posthog-data：入口清晰，链接 30 多个参考文件，渐进式披露，混合静态 .md 与生成的 .md.j2 内容。
限制：资料未提供价格、收费、平台支持范围等信息。完整指南见 docs/published/handbook/engineering/ai/writing-skills.md。