为 PostHog 编写 Agent Skills从 SKILL.md 到构建、分发与测试的完整工程实践【免费下载链接】posthog: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.项目地址: https://gitcode.com/GitHub_Trending/po/posthog本篇技术指南以 PostHog 仓库的官方工程手册《Writing skills》docs/published/handbook/engineering/ai/writing-skills.md为骨架系统讲解 PostHog 中 Agent Skills 的本质、编写规范、目录结构、模板引擎、构建流水线与自动分发机制并逐层对照仓库中的真实实现构建脚本、模板函数、CLI 命令与大量已落地的 skill 示例加以印证。读完本文你将掌握如何在自己的产品目录下创建一个可被 PostHog Desktop、Claude Code 等编码代理自动发现与执行的 Skill理解SKILL.mdreferences/渐进式披露的创作方法以及hogli全生命周期命令的用法与背后的源码原理。Skills 是什么任务的待办模板而非命令脚本Skills 是 PostHog 体系中面向待完成工作job-to-be-done的模板它们教给 Agent如何使用一组能力去达成目标。官方手册开篇给出了一条核心写作原则Skills 读起来应当像一个有经验的人如何着手一项工作而不是一份僵硬的命令脚本。描述工作流、每一步背后的推理以及需要注意的事项——然后信任 Agent 去灵活适配。过于死板的指令在上下文变化时会失效解释得足够清楚的方法才能泛化。这句话区分了 Skill 与普通 PromptSkill 关注为什么这么做与什么算成功把具体编排留给 Agent 的推理能力。当前仓库中已沉淀了大量遵循该原则的 skill例如 products/ai_observability/skills/exploring-llm-traces/SKILL.md引导 Agent 从 trace URL 分类 → 摘要浏览 → 全文读取 → 脚本解析四个步骤排查 LLM 调用问题、products/posthog_ai/skills/querying-posthog-data/SKILL.mdHogQL 查询前的必读材料以及覆盖 feature flags、experiments、error tracking、logs、replay 等 40 多个产品目录下的上百个 skill。一句话速览TL;DR官方手册给出了一条从脚手架到上线的完整命令链路# 1. 在你的产品下脚手架一个新的 skill hogli init:skill # 2. 编写 products/{product}/skills/{skill-name}/SKILL.md # 详细内容放 references/模板用 .md.j2 后缀 # 3. Lint快速无需 Django hogli lint:skills # 4. 本地构建验证渲染输出 hogli build:skills # 5. 用 PostHog Desktop 或编码代理本地测试 hogli sync:skill -- --name skill-name # 6. 可选删除测试用的 skill hogli unsync:skill -- --name skill-name # 7. 合并到 master —— CI 自动构建并分发后面各节将逐条展开每条命令背后的细节与源码依据。Skill 放哪里发布目录 vs 仓库内部目录Skill 的存放位置由这项工作需要什么决定而不是由权限决定位置适用场景去向products/product/skills/用户可通过 PostHog 工具、API 或自己的代码运行的 skill构建后发布到下游仓库.agents/skills/需要 checkout PostHog 仓库才能开发、测试或调试 PostHog 自身的 skill留在仓库内两个位置都使用带name与descriptionfrontmatter 的SKILL.md且hogli lint:skills都会检查。官方手册特别强调了几条判断准则Staff-only 权限不决定存放位置。例如checking-deploy-timing通过 MCP 即可工作、无需 checkout因此留在发布目录中实现在 products/posthog_ai/skills/checking-deploy-timing/SKILL.md一个会修改客户应用的 skill 也保持发布因为它不需要 PostHog 源码。混合场景要拆分客户诊断部分保持发布PostHog 开发指引移入内部 skill 或 reference。官方示例中debugging-surveys覆盖配置与响应而内部的survey-sdk-audit覆盖后端与 SDK 的改动。发布出去的 skill 主工作流绝不能依赖内部 skill 文件。hogli init:skill只脚手架发布型产品 skill内部指引优先扩展现有.agents/skills/条目。从源码看SkillDiscoverer.discover() 实际只扫描products/*/skills/两层结构深度 0 是skills/下的松散.md/.md.j2文件skill 名取文件名主干深度 1 是含SKILL.md(.j2)的子目录skill 名取目录名README.md、AGENTS.md、CLAUDE.md被明确排除在候选之外它们只是旁注约定文档。Skills vs Tools能力与编排的分工Tools是原子能力——经由 MCP server 暴露的 CRUD 操作与简单动作。它们回答我能做什么列出 feature flags、执行 SQL、创建 survey。Skills回答我如何完成 X它们把工具、领域知识、查询模式与逐步工作流组合成一个模板供 Agent 解决一类问题。官方手册点出了这一分离的关键价值Agent 擅长组合简单工具但需要指引用哪些工具、按什么顺序、带什么约束。一个 skill 可能引用多个工具、包含 HogQL 查询示例、解释查询前要核验什么数据、描述客户期望的结果。在 skill 中引用 MCP 工具时应使用posthog:命名空间前缀如posthog:execute-sql、posthog:feature-flag-get-all这与 Agent 消费 PostHog MCP server 时看到工具的方式一致能帮助 Agent 无歧义地解析工具名。exploring-llm-traces的Available tools一节就是典型posthog:query-llm-traces-list、posthog:query-llm-trace、posthog:read-data-schema、posthog:execute-sql各司其职。值得一提的还有构建脚本内置的工具引用校验lint_all()会加载 services/mcp/schema/tool-definitions.json 与generated-tool-definitions.json中的工具注册表通过短语正则use the X tool、调用式正则read_data(...)与 snake_case 误写检查把 skill 里看起来像工具但实际不存在的悬空引用以advisory不阻断的方式报告出来并在 GitHub Actions 中渲染为 PR diff 上的行级 annotation见 build_skills.py 的_check_tool_references。SDK 函数名如get_feature_flag、emit_signal被列入豁免名单避免误报。什么时候该写一个 skill官方给出了决策流先让 PostHog Desktop 或 Claude Code 去做 X。如果它能独立完成你就不需要 skill。做不了就优先修工具提示。工具的名称、描述与 schema 是最便宜的杠杆——大多数Agent 不会做 X的问题本质是工具描述没有解释如何做 X。修了工具提示仍不奏效、或 Agent 在摸索该做哪项工作上烧掉大量 token 时再写 skill。即便工具提示已经很完善以下信号仍说明 skill 是正确选择复杂的输入或输出AI observability、logs 等查询类端点具有嵌套且不直观的载荷形状让 skill 帮 Agent 免去每次对话都重新发现该形状。指引天然分为入口 referencesSQL 类 skill 是典型——顶层工作流 按需加载的可选 schema、查询模式与函数索引因此应组织成带references/的 skill。不要为 Agent 凭通用知识就能一次搞定的东西写 skill。官方评审实例creating-isolated-project、finding-experiments是多余的Agent 无需帮助即可完成setting-up-reverse-proxy则是正确的决定Agent 之前失败了skill 需要提供它无法推导出的代码片段。判断标准是一个聪明的通用型 Agent 不具备的 PostHog 专属判断力而不是它已能处理的工程搭建。多少个 skill 算太多skill 数量是一项有预算、共享的资源而不是可以自由扩张的维度Agent 从全部可用描述的列表里挑选 skill而许多 harness 在列表变长后会截断它——每个多余的 skill 都会稀释其他 skill 的发现率。新增 skill 前要判断这是真正的新工作还是已有工作的更多细节新触发点 → 新 skill。只有当 skill 有 Agent 能独立匹配到的独特触发点时才配拥有独立的入口。更多细节 → 放进references/而不是开一个兄弟 skill。失败模式、SDK 变体、更长的查询目录都应作为已有 skill 的深度补充入口保持精简、细节按需加载——获得覆盖而不消耗 skill 名额。合并近重复的兄弟 skill。两个 skill 共享同一诊断/缺陷类/触发点、仅细节不同就合并成一个带 references 的 skill。经验法则偏爱少量聚焦的 skill 各自丰富的 references/胜过大量单薄的 skill。先伸手拿 reference 文件只有当工作与触发点确实不同时才新增整个 skill。Skill 的结构单文件与目录两种形态发布型 skill 位于products/*/skills/分为两种形态如果产品尚未迁移到products/文件夹先创建产品文件夹再把 skill 放进去——skill 设计上就从 products 目录结构内部工作。简单 skill单文件products/{product}/skills/ analyzing-llm-traces.md # 或 .md.j2 以使用 Jinja2 模板skill 名 文件名主干。源码中深度 0 的发现逻辑build_skills.py会去掉.j2与.md后缀得到名字。目录 skill带 referencesproducts/{product}/skills/{skill-name}/ SKILL.md # 入口必填 references/ # 可选递归收集 guidelines.md models-actions.md example-trends.md.j2 scripts/ # 可选递归收集 setup.shskill 名 目录名。只有references/和scripts/子目录会进入构建输出其他子目录一律忽略。源码中的_ALLOWED_SUBDIRS {references, scripts}build_skills.py与collect_skill_files()的显式白名单收集逻辑直接印证了这一点且.j2文件渲染后会剥掉后缀。Frontmatter每个 skill 入口必须包含 YAML frontmattername与description两个字段必填并在构建时校验--- name: querying-posthog-data description: Required reading before writing any HogQL/SQL or calling execute-sql against PostHog... ---源码侧由 Pydantic 模型 SkillFrontmatter 强制执行name: strdescription: str Field(max_length_MAX_SKILL_DESCRIPTION_LENGTH)上限 1024 字符。validate_frontmatter()使用正则_FRONTMATTER_RE解析---包裹的 YAML 块缺失或非法都会抛出ValueError进而让 lint 失败build_skills.py。渐进式披露Progressive disclosureSKILL.md充当总览按需把 Agent 引向详细材料。初始只读取入口文件reference 文件按需加载。官方建议保持SKILL.md在500 行以内把详细内容拆进references/。querying-posthog-data是教科书级的实践其入口 SKILL.md 链接了65 个reference 文件references/目录实际数量覆盖各领域模型 schemaactivity logs、flags experiments、AI observability events 等、HogQL 扩展person property modes、可用函数等与 20 个分析查询示例trends、funnel、retention、paths、lifecycle、stickiness、LLM traces、logs、session replay……。其中的 schema 表并非手写而是由模板函数从 HogQL catalog 实时生成见下文模板引擎保证reference 与执行器永不出分歧。命名与描述规范官方手册要求遵循 Anthropic 的 skill 创作最佳实践关键点总结如下。命名约定使用小写 kebab-case优先动名词形式动词 -ing模式示例动名词首选querying-posthog-data、exploring-llm-traces、managing-feature-flags名词短语可接受error-tracking-guide禁止以posthog-*前缀命名——该前缀会根据消费方 Agent 自动添加。名称中不得包含保留词anthropic或claude。name字段只允许小写字母、数字与连字符最长 64 字符。仓库中随处可见符合该约定的命名如exploring-llm-traces、diagnosing-missing-recordings、authoring-data-quality-checks、triaging-error-issues等分布在 products/ai_observability/skills、products/replay/skills、products/error_tracking/skills 等目录。描述写法description是 skill 发现的关键——Agent 从可能很多的 skill 中决定激活哪一个就靠它。最长 1024 字符。规则用第三人称书写Analyzes LLM traces...而不是I can help you analyze...。同时包含 skill 做什么与何时用它。要具体——包含 Agent 会匹配的关键词。好描述# 具体、包含触发词与关键术语 description: HogQL query examples and reference material for PostHog data. Read when writing SQL queries to find patterns for analytics (trends, funnels, retention, lifecycle, paths, stickiness, web analytics, error tracking, logs, sessions, LLM traces) and system data (insights, dashboards, cohorts, feature flags, experiments, surveys, data warehouse). description: Debug and inspect LLM/AI agent traces using PostHogs MCP tools. Use when the user pastes a trace URL (e.g. /ai-observability/traces/id), asks to debug a trace, figure out what went wrong, check if an agent used a tool correctly, verify context/files were surfaced, inspect subagent behavior, investigate LLM decisions, or analyze token usage and costs.坏描述# 太模糊——Agent 无法判断何时使用 description: Helps with AI observability # 太宽泛——一个雨伞式描述不是 skill description: Everything about PostHog AI features好与坏的 skill 示例好exploring-llm-traces这是聚焦型 skill 的代表products/ai_observability/skills/exploring-llm-traces/SKILL.md声明了它依赖的精确 MCP 工具posthog:query-llm-traces-list、posthog:query-llm-trace、posthog:execute-sql等。解释$ai_trace/$ai_span/$ai_generation/$ai_embedding事件层级以及事件如何通过$ai_parent_id关联。走具体的排查工作流从 URL 调试 trace、成本分析、工具使用核验而不是罗列泛化指令。使用渐进式披露——完整事件 schema 等细节放在references/入口保持聚焦。随附scripts/中的预写 Python 辅助脚本print_summary.py、print_timeline.py、extract_span.py、extract_conversation.py、search_traces.py、show_structure.pyAgent 直接运行它们而不是每次重新推导 trace JSON 的形状、手工切片嵌套载荷、或把 token 烧在探索式解析上——这精简了它的轨迹并保持上下文窗口干净。Agent 知道用哪些工具、按什么顺序、以及成功结果长什么样——这正是 skill 与普通 prompt 的区别。好querying-posthog-data一个入口清晰、带 65 个 reference 文件的参考型 skill入口SKILL.md链接到模型 schema、查询模式与 HogQL 扩展。guidelines 文件references/guidelines.md解释 schema 核验工作流、时间范围、join 与 HogQL 差异。使用渐进式披露——Agent 只加载自己需要的 references。值得注意其入口还专门讲了回答治理型业务/遥测指标MRR、激活率、计费用量……的流程先查数据目录的语义层system.information_schema.metrics中的 canonical 指标只有statusapproved且is_driftedfalse的结果才能作为权威结论呈现否则自行推导并标注非权威——这类判断正是PostHog 专属经验的体现。坏llm-analytics一个试图包揽一切的雨伞式 skilltraces、experiments、evaluations、cost tracking、prompt management。太宽泛而无用——Agent 无法判断何时激活它指令也太泛化而无法引导任何具体工作流。应拆成聚焦的 skill。坏糟糕的描述# 名称模糊 name: helper description: Helps with stuff # 名称使用保留前缀 name: posthog-queries description: Query helper模板引擎让 monorepo 成为 skill 内容的唯一真相源Skill 支持 Jinja2 中的配置外加keep_trailing_newlineTrue与autoescapeFalse。内置模板函数所有.j2模板可用三个全局函数实际实现中还注册了audit_constants与schema_columns见 SkillRenderer.__init__pydantic_schema(dotted_path, indent2)按全限定路径导入 Pydantic 模型并返回其 JSON Schema{{ pydantic_schema(products.feature_flags.backend.max_tools.FeatureFlagCreationSchema) }}Pydantic 模型的变更会在下次构建时自动更新 skill 输出。实现位于 products/posthog_ai/scripts/pydantic_schema/init.py_import_model用importlib.import_module解析module.ClassName并校验其为 Pydantic 模型随后调用model_cls.model_json_schema()并以指定缩进序列化。render_hogql_example(query_dict)接收一个 PostHog 查询 spec 并渲染为 HogQL SQL{{ render_hogql_example({kind: TrendsQuery, series: [{kind: EventsNode, event: $pageview}], dateRange: {date_from: -7d}}) }}时间被冻结在2025-12-10T00:00:00以保证输出确定性。实现products/posthog_ai/scripts/hogql_example/init.py会通过get_query_runner拿到对应的 query runner用_pin_runner_now把 runner 的context.now与query_date_range钉在冻结时刻再走to_query()→replace_filters()→to_printed_hogql()的完整 HogQL 打印管线对RecordingsQuery有专门分支对 ErrorTracking/Logs/Trace 三类 runner 还有各自的 filter 与 placeholder 处理。它要求DEBUGTrue且数据库中存在至少一个 Team。hogql_functions()返回全部公开 HogQL 函数名的排序列表{% for fn in hogql_functions() %} {{ fn }} {% endfor %}实现products/posthog_ai/scripts/hogql_functions/init.py从HOGQL_CLICKHOUSE_FUNCTIONS与HOGQL_AGGREGATIONS聚合函数名排除下划线开头的内部函数、UDF以及存在基础函数的*If组合变体如countIf/sumIf最后按小写字母排序。扩展模板引擎构建流水线的设计意图是monorepo 永远是所有 skill 内容的真相源。当领域知识存在于代码中Pydantic 模型、query runner、函数注册表时应添加模板函数在构建时提取它而不是复制成会漂移的静态 markdown。新增模板函数的步骤在products/posthog_ai/scripts/下创建模块参照pydantic_schema/、hogql_example/等既有模式。在SkillRenderer.__init__()中注册通过_create_jinja_env(**extra_globals)加入self.env.globals。仓库中schema_columns正是这一理念的体现它从static_column_rows与system.information_schema.columns相同的收集器直接渲染models-*.md的列表面使 reference 与执行器永远一致见 products/posthog_ai/scripts/schema_columns/init.py 的模块 docstring。构建流水线发现 → 渲染 → 打包流水线负责发现、渲染与打包 skills真相源是 products/posthog_ai/scripts/build_skills.py。流水线步骤Discovery Scan products/*/skills/ for skills (loose files or directories with SKILL.md) │ ▼ Rendering Render .j2 files through Jinja2, pass .md files through unchanged │ ▼ Building Collect entry point references/scripts into SkillResource with frontmatter metadata │ ▼ Output Write to dist/skills/{skill-name}/ and package into dist/skills.zip各步骤对应源码中的类SkillDiscoverer扫描、SkillRendererJinja2 渲染、SkillBuilder收集资源、生成SkillManifest、写盘与打包。build_all()在写盘前会清空dist/skills/目录pack()用ZIP_DEFLATED打包并以固定时间戳_ZIP_FIXED_TIME (2025, 1, 1, 0, 0, 0)写入每个条目实现可复现构建build_skills.py。CLI 命令hogli build:skills # 构建全部 skills 并生成 dist/skills.zip hogli build:skills --list # 仅列出发现的 skills不构建 hogli lint:skills # 校验 skill 源码无需 Django hogli init:skill # 脚手架新 skill 目录 hogli sync:skill # 构建并把 skill 同步到 .agents/skills/ 用于本地测试 hogli unsync:skill # 从 .agents/skills/ 移除已同步的 skilllint:skills校验语法、frontmatter、二进制文件检测与重复名称无需 Django因此在 CI 中很快。具体检查项在 lint_all()二进制检测读前 8192 字节查 null 字节、跨产品重复名检测、Jinja2 仅解析parse-only语法校验、入口 frontmatter 校验、以及上文提到的工具/技能引用启发式校验advisory。它还会检查SKILL.md中指向references//scripts/的 Markdown 链接在构建后的包里是否真实存在_check_reference_links会捕获指向.md.j2模板而非剥壳后.md的坏链接。build:skills需要完整 Python 环境因为模板函数会导入 Django 模型与 Pydantic schema——_setup_django()会设置DJANGO_SETTINGS_MODULEposthog.settings并预设OPT_OUT_CAPTURE1避免构建时依赖外网 feature flag 端点且要求环境变量如SECRET_KEY齐全。init:skill会在products/{product}/skills/{skill-name}/下创建SKILL.md或--j2时的SKILL.md.j2与references/子目录并写入带name/description: TODO的 boilerplatebuild_skills.py。sync:skill/unsync:skill通过--name按products/*/skills/下的源码目录名定位 skill并把构建产物复制到.agents/skills/sync_skill还会在.agents/skills/.gitignore中登记该目录确保同步产物不被误提交。在 hogli 命令体系中build:skills还挂入了统一的智能变更检测管线tools/hogli-commands/hogli_commands/build.py的TRIGGERS表中build:skills的触发 glob 是products/*/skills/*——只有 skills 相关文件变更时才会触发重构建build.py并有 tests/test_build.py 的参数化测试覆盖products/posthog_ai/skills/foo/SKILL.md触发build:skills这一映射。输出构建后的 skills 写入products/posthog_ai/dist/skills/gitignored人可读并打包为dist/skills.zip固定时间戳可复现。实测当前仓库没有dist目录——因为它被 gitignore只有本地hogli build:skills或 CI 构建才会生成。分发合并即发布分发是全自动的——skill 一旦落到masterCI 构建出dist/skills.zip工件并发布到两个下游仓库PostHog/skills规范分发仓库。每个构建好的 skill 作为独立目录推送可直接同步进任何遵循 Anthropic skills 布局的 AgentClaude Code、Claude Desktop 等。PostHog/ai-plugin供消费 PostHog 能力的编码代理PostHog Desktop、PostHog AI使用的插件分发。插件把 skills 与 MCP 工具定义捆绑在一起让 Agent 同时拿到怎么做与能做什么。PostHog Desktop 已自动消费 skillsPostHog AI 消费同一套。因为两个仓库都由每次合并到master时的同一个dist/skills.zip更新你无需自行处理分发——合并你的 skill下一次 CI 运行时它就会出现在两处。context-mill skills 覆盖本仓库的 skills本仓库不是已发布 skills 的唯一来源。PostHog/context-mill从 posthog.com 文档汇编omnibus skills 并发布为skills-mcp-resources.zipinstrument-integration、instrument-product-analytics、instrument-feature-flags、instrument-error-tracking、instrument-llm-analytics、instrument-logs。这些是 PostHog Desktop 的设置按钮与 wizard 背后的 skills。每个消费方都先解压dist/skills.zip、再把 context-mill 解压覆盖在上面因此两者都定义的 skill 以 context-mill 为准。在这里添加同名 skill其SKILL.md会被覆盖而多余 reference 文件会作为孤儿残留在另一来源的目录里。Desktop harness bundle 是例外它单独打包 context-mill所以本仓库的 skill 在那里是缺席而非被覆盖。消费方合并位置PostHog Desktop 构建products/desktop/apps/code/vite-main-plugins.mtscopyPosthogPluginPostHog Desktop 运行时每 30 分钟products/desktop/packages/workspace-server/src/services/posthog-plugin/update-skills-saga.tsDesktop harness bundleproducts/desktop/packages/harness/tsup.config.ts—— 仅 context-mill本仓库 skills 缺席而非被覆盖Tasks sandbox 基础镜像.github/workflows/cd-sandbox-base-image.ymlTasks golden snapshot.github/workflows/cd-tasks-golden-snapshot.ymlPostHog/skills镜像该仓库的.github/workflows/sync-omnibus.ymlPostHog/ai-plugin插件该仓库的.github/workflows/sync-skills.yml注意表中缺失的本地构建。LocalSkillsCache.ensure_built()只渲染products/*/skills/且先清空 dist 目录因此本地构建的 sandbox完全没有 omnibus skills。依赖 omnibus skill 的 eval 或手动运行必须自行叠加 context-mill或检查 skill 存在性并在缺失时响亮失败——见 products/feature_flags/evals/eval_instrument_flags.py。这一冲突甚至被构建脚本硬性拦截OMNIBUS_SKILL_NAMES常量build_skills.py列出了六个保留名build_skill()与lint_all()都会检查渲染后/未渲染的 frontmattername命中即报错——包括渲染后才变成保留名的情况Jinja 模板如instrument-{{ logs }}。所以写 skill 前先核对上面的 omnibus 名单如果你的工作属于其中之一就去改 context-mill 的源头。本地测试用 Claude Code 验证在本地用 Claude Code 测试产品 skill可把它同步到.agents/skills/# 构建并同步指定 skill hogli sync:skill -- --name querying-posthog-data # 该 skill 现在位于 .agents/skills/querying-posthog-data/ # Claude Code 通过 .claude/skills - .agents/skills 符号链接拾取它 # 测试完成后移除同步副本 hogli unsync:skill -- --name querying-posthog-data同步的 skills 会被自动 gitignore写入.agents/skills/.gitignore不应提交。sync:skill与unsync:skill都接受--name按源码目录名定位 skillunsync_skill还会解析 frontmattername尝试匹配可能的别名目录build_skills.py。更完整的端到端验证本地运行 MCP server 并核验 skill 行为参见手册中How to develop and test一节。写出有效的 skills上下文窗口是共享资源上下文窗口是共享资源。你的 skill 与系统 prompt、对话历史、其他 skills 和用户的请求竞争。默认假设Agent 已经非常聪明。只包含它还不具备的上下文。质疑每条信息Agent 真的需要这段解释吗官方手册建议的进阶实践包括渐进式披露入口精简、细节按需、反馈回路在 skill 中描述成功标准让 Agent 自我核验、工作流设计步骤间明确产物以及评估驱动开发用真实任务评测 skill 是否让 Agent 更可靠地达成目标。核心取舍始终如一skill 要封装通用型 Agent 没有的 PostHog 专属判断力把领域知识沉淀为可复用资产同时为发现性discovery与上下文预算负责——小集合、富 references、每个 skill 一个清晰触发点是让整套体系长期可维护的关键。延伸阅读手册姊妹篇Adding tools to the MCP server能力本身的实现与注册构建真相源products/posthog_ai/scripts/build_skills.py发现、渲染、校验、打包、同步的全部逻辑模板函数实现pydantic_schema、hogql_example、hogql_functions、schema_columns实战范例exploring-llm-traces聚焦工作流型、querying-posthog-data入口 65 个 references 的参考型hogli 命令管线tools/hogli-commands/hogli_commands/build.py 及其 测试MCP 工具注册表lint 引用校验的数据源services/mcp/schema/tool-definitions.json【免费下载链接】posthog: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.项目地址: https://gitcode.com/GitHub_Trending/po/posthog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
为 PostHog 编写 Agent Skills：从 SKILL.md 到构建、分发与测试的完整工程实践
为 PostHog 编写 Agent Skills从 SKILL.md 到构建、分发与测试的完整工程实践【免费下载链接】posthog: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.项目地址: https://gitcode.com/GitHub_Trending/po/posthog本篇技术指南以 PostHog 仓库的官方工程手册《Writing skills》docs/published/handbook/engineering/ai/writing-skills.md为骨架系统讲解 PostHog 中 Agent Skills 的本质、编写规范、目录结构、模板引擎、构建流水线与自动分发机制并逐层对照仓库中的真实实现构建脚本、模板函数、CLI 命令与大量已落地的 skill 示例加以印证。读完本文你将掌握如何在自己的产品目录下创建一个可被 PostHog Desktop、Claude Code 等编码代理自动发现与执行的 Skill理解SKILL.mdreferences/渐进式披露的创作方法以及hogli全生命周期命令的用法与背后的源码原理。Skills 是什么任务的待办模板而非命令脚本Skills 是 PostHog 体系中面向待完成工作job-to-be-done的模板它们教给 Agent如何使用一组能力去达成目标。官方手册开篇给出了一条核心写作原则Skills 读起来应当像一个有经验的人如何着手一项工作而不是一份僵硬的命令脚本。描述工作流、每一步背后的推理以及需要注意的事项——然后信任 Agent 去灵活适配。过于死板的指令在上下文变化时会失效解释得足够清楚的方法才能泛化。这句话区分了 Skill 与普通 PromptSkill 关注为什么这么做与什么算成功把具体编排留给 Agent 的推理能力。当前仓库中已沉淀了大量遵循该原则的 skill例如 products/ai_observability/skills/exploring-llm-traces/SKILL.md引导 Agent 从 trace URL 分类 → 摘要浏览 → 全文读取 → 脚本解析四个步骤排查 LLM 调用问题、products/posthog_ai/skills/querying-posthog-data/SKILL.mdHogQL 查询前的必读材料以及覆盖 feature flags、experiments、error tracking、logs、replay 等 40 多个产品目录下的上百个 skill。一句话速览TL;DR官方手册给出了一条从脚手架到上线的完整命令链路# 1. 在你的产品下脚手架一个新的 skill hogli init:skill # 2. 编写 products/{product}/skills/{skill-name}/SKILL.md # 详细内容放 references/模板用 .md.j2 后缀 # 3. Lint快速无需 Django hogli lint:skills # 4. 本地构建验证渲染输出 hogli build:skills # 5. 用 PostHog Desktop 或编码代理本地测试 hogli sync:skill -- --name skill-name # 6. 可选删除测试用的 skill hogli unsync:skill -- --name skill-name # 7. 合并到 master —— CI 自动构建并分发后面各节将逐条展开每条命令背后的细节与源码依据。Skill 放哪里发布目录 vs 仓库内部目录Skill 的存放位置由这项工作需要什么决定而不是由权限决定位置适用场景去向products/product/skills/用户可通过 PostHog 工具、API 或自己的代码运行的 skill构建后发布到下游仓库.agents/skills/需要 checkout PostHog 仓库才能开发、测试或调试 PostHog 自身的 skill留在仓库内两个位置都使用带name与descriptionfrontmatter 的SKILL.md且hogli lint:skills都会检查。官方手册特别强调了几条判断准则Staff-only 权限不决定存放位置。例如checking-deploy-timing通过 MCP 即可工作、无需 checkout因此留在发布目录中实现在 products/posthog_ai/skills/checking-deploy-timing/SKILL.md一个会修改客户应用的 skill 也保持发布因为它不需要 PostHog 源码。混合场景要拆分客户诊断部分保持发布PostHog 开发指引移入内部 skill 或 reference。官方示例中debugging-surveys覆盖配置与响应而内部的survey-sdk-audit覆盖后端与 SDK 的改动。发布出去的 skill 主工作流绝不能依赖内部 skill 文件。hogli init:skill只脚手架发布型产品 skill内部指引优先扩展现有.agents/skills/条目。从源码看SkillDiscoverer.discover() 实际只扫描products/*/skills/两层结构深度 0 是skills/下的松散.md/.md.j2文件skill 名取文件名主干深度 1 是含SKILL.md(.j2)的子目录skill 名取目录名README.md、AGENTS.md、CLAUDE.md被明确排除在候选之外它们只是旁注约定文档。Skills vs Tools能力与编排的分工Tools是原子能力——经由 MCP server 暴露的 CRUD 操作与简单动作。它们回答我能做什么列出 feature flags、执行 SQL、创建 survey。Skills回答我如何完成 X它们把工具、领域知识、查询模式与逐步工作流组合成一个模板供 Agent 解决一类问题。官方手册点出了这一分离的关键价值Agent 擅长组合简单工具但需要指引用哪些工具、按什么顺序、带什么约束。一个 skill 可能引用多个工具、包含 HogQL 查询示例、解释查询前要核验什么数据、描述客户期望的结果。在 skill 中引用 MCP 工具时应使用posthog:命名空间前缀如posthog:execute-sql、posthog:feature-flag-get-all这与 Agent 消费 PostHog MCP server 时看到工具的方式一致能帮助 Agent 无歧义地解析工具名。exploring-llm-traces的Available tools一节就是典型posthog:query-llm-traces-list、posthog:query-llm-trace、posthog:read-data-schema、posthog:execute-sql各司其职。值得一提的还有构建脚本内置的工具引用校验lint_all()会加载 services/mcp/schema/tool-definitions.json 与generated-tool-definitions.json中的工具注册表通过短语正则use the X tool、调用式正则read_data(...)与 snake_case 误写检查把 skill 里看起来像工具但实际不存在的悬空引用以advisory不阻断的方式报告出来并在 GitHub Actions 中渲染为 PR diff 上的行级 annotation见 build_skills.py 的_check_tool_references。SDK 函数名如get_feature_flag、emit_signal被列入豁免名单避免误报。什么时候该写一个 skill官方给出了决策流先让 PostHog Desktop 或 Claude Code 去做 X。如果它能独立完成你就不需要 skill。做不了就优先修工具提示。工具的名称、描述与 schema 是最便宜的杠杆——大多数Agent 不会做 X的问题本质是工具描述没有解释如何做 X。修了工具提示仍不奏效、或 Agent 在摸索该做哪项工作上烧掉大量 token 时再写 skill。即便工具提示已经很完善以下信号仍说明 skill 是正确选择复杂的输入或输出AI observability、logs 等查询类端点具有嵌套且不直观的载荷形状让 skill 帮 Agent 免去每次对话都重新发现该形状。指引天然分为入口 referencesSQL 类 skill 是典型——顶层工作流 按需加载的可选 schema、查询模式与函数索引因此应组织成带references/的 skill。不要为 Agent 凭通用知识就能一次搞定的东西写 skill。官方评审实例creating-isolated-project、finding-experiments是多余的Agent 无需帮助即可完成setting-up-reverse-proxy则是正确的决定Agent 之前失败了skill 需要提供它无法推导出的代码片段。判断标准是一个聪明的通用型 Agent 不具备的 PostHog 专属判断力而不是它已能处理的工程搭建。多少个 skill 算太多skill 数量是一项有预算、共享的资源而不是可以自由扩张的维度Agent 从全部可用描述的列表里挑选 skill而许多 harness 在列表变长后会截断它——每个多余的 skill 都会稀释其他 skill 的发现率。新增 skill 前要判断这是真正的新工作还是已有工作的更多细节新触发点 → 新 skill。只有当 skill 有 Agent 能独立匹配到的独特触发点时才配拥有独立的入口。更多细节 → 放进references/而不是开一个兄弟 skill。失败模式、SDK 变体、更长的查询目录都应作为已有 skill 的深度补充入口保持精简、细节按需加载——获得覆盖而不消耗 skill 名额。合并近重复的兄弟 skill。两个 skill 共享同一诊断/缺陷类/触发点、仅细节不同就合并成一个带 references 的 skill。经验法则偏爱少量聚焦的 skill 各自丰富的 references/胜过大量单薄的 skill。先伸手拿 reference 文件只有当工作与触发点确实不同时才新增整个 skill。Skill 的结构单文件与目录两种形态发布型 skill 位于products/*/skills/分为两种形态如果产品尚未迁移到products/文件夹先创建产品文件夹再把 skill 放进去——skill 设计上就从 products 目录结构内部工作。简单 skill单文件products/{product}/skills/ analyzing-llm-traces.md # 或 .md.j2 以使用 Jinja2 模板skill 名 文件名主干。源码中深度 0 的发现逻辑build_skills.py会去掉.j2与.md后缀得到名字。目录 skill带 referencesproducts/{product}/skills/{skill-name}/ SKILL.md # 入口必填 references/ # 可选递归收集 guidelines.md models-actions.md example-trends.md.j2 scripts/ # 可选递归收集 setup.shskill 名 目录名。只有references/和scripts/子目录会进入构建输出其他子目录一律忽略。源码中的_ALLOWED_SUBDIRS {references, scripts}build_skills.py与collect_skill_files()的显式白名单收集逻辑直接印证了这一点且.j2文件渲染后会剥掉后缀。Frontmatter每个 skill 入口必须包含 YAML frontmattername与description两个字段必填并在构建时校验--- name: querying-posthog-data description: Required reading before writing any HogQL/SQL or calling execute-sql against PostHog... ---源码侧由 Pydantic 模型 SkillFrontmatter 强制执行name: strdescription: str Field(max_length_MAX_SKILL_DESCRIPTION_LENGTH)上限 1024 字符。validate_frontmatter()使用正则_FRONTMATTER_RE解析---包裹的 YAML 块缺失或非法都会抛出ValueError进而让 lint 失败build_skills.py。渐进式披露Progressive disclosureSKILL.md充当总览按需把 Agent 引向详细材料。初始只读取入口文件reference 文件按需加载。官方建议保持SKILL.md在500 行以内把详细内容拆进references/。querying-posthog-data是教科书级的实践其入口 SKILL.md 链接了65 个reference 文件references/目录实际数量覆盖各领域模型 schemaactivity logs、flags experiments、AI observability events 等、HogQL 扩展person property modes、可用函数等与 20 个分析查询示例trends、funnel、retention、paths、lifecycle、stickiness、LLM traces、logs、session replay……。其中的 schema 表并非手写而是由模板函数从 HogQL catalog 实时生成见下文模板引擎保证reference 与执行器永不出分歧。命名与描述规范官方手册要求遵循 Anthropic 的 skill 创作最佳实践关键点总结如下。命名约定使用小写 kebab-case优先动名词形式动词 -ing模式示例动名词首选querying-posthog-data、exploring-llm-traces、managing-feature-flags名词短语可接受error-tracking-guide禁止以posthog-*前缀命名——该前缀会根据消费方 Agent 自动添加。名称中不得包含保留词anthropic或claude。name字段只允许小写字母、数字与连字符最长 64 字符。仓库中随处可见符合该约定的命名如exploring-llm-traces、diagnosing-missing-recordings、authoring-data-quality-checks、triaging-error-issues等分布在 products/ai_observability/skills、products/replay/skills、products/error_tracking/skills 等目录。描述写法description是 skill 发现的关键——Agent 从可能很多的 skill 中决定激活哪一个就靠它。最长 1024 字符。规则用第三人称书写Analyzes LLM traces...而不是I can help you analyze...。同时包含 skill 做什么与何时用它。要具体——包含 Agent 会匹配的关键词。好描述# 具体、包含触发词与关键术语 description: HogQL query examples and reference material for PostHog data. Read when writing SQL queries to find patterns for analytics (trends, funnels, retention, lifecycle, paths, stickiness, web analytics, error tracking, logs, sessions, LLM traces) and system data (insights, dashboards, cohorts, feature flags, experiments, surveys, data warehouse). description: Debug and inspect LLM/AI agent traces using PostHogs MCP tools. Use when the user pastes a trace URL (e.g. /ai-observability/traces/id), asks to debug a trace, figure out what went wrong, check if an agent used a tool correctly, verify context/files were surfaced, inspect subagent behavior, investigate LLM decisions, or analyze token usage and costs.坏描述# 太模糊——Agent 无法判断何时使用 description: Helps with AI observability # 太宽泛——一个雨伞式描述不是 skill description: Everything about PostHog AI features好与坏的 skill 示例好exploring-llm-traces这是聚焦型 skill 的代表products/ai_observability/skills/exploring-llm-traces/SKILL.md声明了它依赖的精确 MCP 工具posthog:query-llm-traces-list、posthog:query-llm-trace、posthog:execute-sql等。解释$ai_trace/$ai_span/$ai_generation/$ai_embedding事件层级以及事件如何通过$ai_parent_id关联。走具体的排查工作流从 URL 调试 trace、成本分析、工具使用核验而不是罗列泛化指令。使用渐进式披露——完整事件 schema 等细节放在references/入口保持聚焦。随附scripts/中的预写 Python 辅助脚本print_summary.py、print_timeline.py、extract_span.py、extract_conversation.py、search_traces.py、show_structure.pyAgent 直接运行它们而不是每次重新推导 trace JSON 的形状、手工切片嵌套载荷、或把 token 烧在探索式解析上——这精简了它的轨迹并保持上下文窗口干净。Agent 知道用哪些工具、按什么顺序、以及成功结果长什么样——这正是 skill 与普通 prompt 的区别。好querying-posthog-data一个入口清晰、带 65 个 reference 文件的参考型 skill入口SKILL.md链接到模型 schema、查询模式与 HogQL 扩展。guidelines 文件references/guidelines.md解释 schema 核验工作流、时间范围、join 与 HogQL 差异。使用渐进式披露——Agent 只加载自己需要的 references。值得注意其入口还专门讲了回答治理型业务/遥测指标MRR、激活率、计费用量……的流程先查数据目录的语义层system.information_schema.metrics中的 canonical 指标只有statusapproved且is_driftedfalse的结果才能作为权威结论呈现否则自行推导并标注非权威——这类判断正是PostHog 专属经验的体现。坏llm-analytics一个试图包揽一切的雨伞式 skilltraces、experiments、evaluations、cost tracking、prompt management。太宽泛而无用——Agent 无法判断何时激活它指令也太泛化而无法引导任何具体工作流。应拆成聚焦的 skill。坏糟糕的描述# 名称模糊 name: helper description: Helps with stuff # 名称使用保留前缀 name: posthog-queries description: Query helper模板引擎让 monorepo 成为 skill 内容的唯一真相源Skill 支持 Jinja2 中的配置外加keep_trailing_newlineTrue与autoescapeFalse。内置模板函数所有.j2模板可用三个全局函数实际实现中还注册了audit_constants与schema_columns见 SkillRenderer.__init__pydantic_schema(dotted_path, indent2)按全限定路径导入 Pydantic 模型并返回其 JSON Schema{{ pydantic_schema(products.feature_flags.backend.max_tools.FeatureFlagCreationSchema) }}Pydantic 模型的变更会在下次构建时自动更新 skill 输出。实现位于 products/posthog_ai/scripts/pydantic_schema/init.py_import_model用importlib.import_module解析module.ClassName并校验其为 Pydantic 模型随后调用model_cls.model_json_schema()并以指定缩进序列化。render_hogql_example(query_dict)接收一个 PostHog 查询 spec 并渲染为 HogQL SQL{{ render_hogql_example({kind: TrendsQuery, series: [{kind: EventsNode, event: $pageview}], dateRange: {date_from: -7d}}) }}时间被冻结在2025-12-10T00:00:00以保证输出确定性。实现products/posthog_ai/scripts/hogql_example/init.py会通过get_query_runner拿到对应的 query runner用_pin_runner_now把 runner 的context.now与query_date_range钉在冻结时刻再走to_query()→replace_filters()→to_printed_hogql()的完整 HogQL 打印管线对RecordingsQuery有专门分支对 ErrorTracking/Logs/Trace 三类 runner 还有各自的 filter 与 placeholder 处理。它要求DEBUGTrue且数据库中存在至少一个 Team。hogql_functions()返回全部公开 HogQL 函数名的排序列表{% for fn in hogql_functions() %} {{ fn }} {% endfor %}实现products/posthog_ai/scripts/hogql_functions/init.py从HOGQL_CLICKHOUSE_FUNCTIONS与HOGQL_AGGREGATIONS聚合函数名排除下划线开头的内部函数、UDF以及存在基础函数的*If组合变体如countIf/sumIf最后按小写字母排序。扩展模板引擎构建流水线的设计意图是monorepo 永远是所有 skill 内容的真相源。当领域知识存在于代码中Pydantic 模型、query runner、函数注册表时应添加模板函数在构建时提取它而不是复制成会漂移的静态 markdown。新增模板函数的步骤在products/posthog_ai/scripts/下创建模块参照pydantic_schema/、hogql_example/等既有模式。在SkillRenderer.__init__()中注册通过_create_jinja_env(**extra_globals)加入self.env.globals。仓库中schema_columns正是这一理念的体现它从static_column_rows与system.information_schema.columns相同的收集器直接渲染models-*.md的列表面使 reference 与执行器永远一致见 products/posthog_ai/scripts/schema_columns/init.py 的模块 docstring。构建流水线发现 → 渲染 → 打包流水线负责发现、渲染与打包 skills真相源是 products/posthog_ai/scripts/build_skills.py。流水线步骤Discovery Scan products/*/skills/ for skills (loose files or directories with SKILL.md) │ ▼ Rendering Render .j2 files through Jinja2, pass .md files through unchanged │ ▼ Building Collect entry point references/scripts into SkillResource with frontmatter metadata │ ▼ Output Write to dist/skills/{skill-name}/ and package into dist/skills.zip各步骤对应源码中的类SkillDiscoverer扫描、SkillRendererJinja2 渲染、SkillBuilder收集资源、生成SkillManifest、写盘与打包。build_all()在写盘前会清空dist/skills/目录pack()用ZIP_DEFLATED打包并以固定时间戳_ZIP_FIXED_TIME (2025, 1, 1, 0, 0, 0)写入每个条目实现可复现构建build_skills.py。CLI 命令hogli build:skills # 构建全部 skills 并生成 dist/skills.zip hogli build:skills --list # 仅列出发现的 skills不构建 hogli lint:skills # 校验 skill 源码无需 Django hogli init:skill # 脚手架新 skill 目录 hogli sync:skill # 构建并把 skill 同步到 .agents/skills/ 用于本地测试 hogli unsync:skill # 从 .agents/skills/ 移除已同步的 skilllint:skills校验语法、frontmatter、二进制文件检测与重复名称无需 Django因此在 CI 中很快。具体检查项在 lint_all()二进制检测读前 8192 字节查 null 字节、跨产品重复名检测、Jinja2 仅解析parse-only语法校验、入口 frontmatter 校验、以及上文提到的工具/技能引用启发式校验advisory。它还会检查SKILL.md中指向references//scripts/的 Markdown 链接在构建后的包里是否真实存在_check_reference_links会捕获指向.md.j2模板而非剥壳后.md的坏链接。build:skills需要完整 Python 环境因为模板函数会导入 Django 模型与 Pydantic schema——_setup_django()会设置DJANGO_SETTINGS_MODULEposthog.settings并预设OPT_OUT_CAPTURE1避免构建时依赖外网 feature flag 端点且要求环境变量如SECRET_KEY齐全。init:skill会在products/{product}/skills/{skill-name}/下创建SKILL.md或--j2时的SKILL.md.j2与references/子目录并写入带name/description: TODO的 boilerplatebuild_skills.py。sync:skill/unsync:skill通过--name按products/*/skills/下的源码目录名定位 skill并把构建产物复制到.agents/skills/sync_skill还会在.agents/skills/.gitignore中登记该目录确保同步产物不被误提交。在 hogli 命令体系中build:skills还挂入了统一的智能变更检测管线tools/hogli-commands/hogli_commands/build.py的TRIGGERS表中build:skills的触发 glob 是products/*/skills/*——只有 skills 相关文件变更时才会触发重构建build.py并有 tests/test_build.py 的参数化测试覆盖products/posthog_ai/skills/foo/SKILL.md触发build:skills这一映射。输出构建后的 skills 写入products/posthog_ai/dist/skills/gitignored人可读并打包为dist/skills.zip固定时间戳可复现。实测当前仓库没有dist目录——因为它被 gitignore只有本地hogli build:skills或 CI 构建才会生成。分发合并即发布分发是全自动的——skill 一旦落到masterCI 构建出dist/skills.zip工件并发布到两个下游仓库PostHog/skills规范分发仓库。每个构建好的 skill 作为独立目录推送可直接同步进任何遵循 Anthropic skills 布局的 AgentClaude Code、Claude Desktop 等。PostHog/ai-plugin供消费 PostHog 能力的编码代理PostHog Desktop、PostHog AI使用的插件分发。插件把 skills 与 MCP 工具定义捆绑在一起让 Agent 同时拿到怎么做与能做什么。PostHog Desktop 已自动消费 skillsPostHog AI 消费同一套。因为两个仓库都由每次合并到master时的同一个dist/skills.zip更新你无需自行处理分发——合并你的 skill下一次 CI 运行时它就会出现在两处。context-mill skills 覆盖本仓库的 skills本仓库不是已发布 skills 的唯一来源。PostHog/context-mill从 posthog.com 文档汇编omnibus skills 并发布为skills-mcp-resources.zipinstrument-integration、instrument-product-analytics、instrument-feature-flags、instrument-error-tracking、instrument-llm-analytics、instrument-logs。这些是 PostHog Desktop 的设置按钮与 wizard 背后的 skills。每个消费方都先解压dist/skills.zip、再把 context-mill 解压覆盖在上面因此两者都定义的 skill 以 context-mill 为准。在这里添加同名 skill其SKILL.md会被覆盖而多余 reference 文件会作为孤儿残留在另一来源的目录里。Desktop harness bundle 是例外它单独打包 context-mill所以本仓库的 skill 在那里是缺席而非被覆盖。消费方合并位置PostHog Desktop 构建products/desktop/apps/code/vite-main-plugins.mtscopyPosthogPluginPostHog Desktop 运行时每 30 分钟products/desktop/packages/workspace-server/src/services/posthog-plugin/update-skills-saga.tsDesktop harness bundleproducts/desktop/packages/harness/tsup.config.ts—— 仅 context-mill本仓库 skills 缺席而非被覆盖Tasks sandbox 基础镜像.github/workflows/cd-sandbox-base-image.ymlTasks golden snapshot.github/workflows/cd-tasks-golden-snapshot.ymlPostHog/skills镜像该仓库的.github/workflows/sync-omnibus.ymlPostHog/ai-plugin插件该仓库的.github/workflows/sync-skills.yml注意表中缺失的本地构建。LocalSkillsCache.ensure_built()只渲染products/*/skills/且先清空 dist 目录因此本地构建的 sandbox完全没有 omnibus skills。依赖 omnibus skill 的 eval 或手动运行必须自行叠加 context-mill或检查 skill 存在性并在缺失时响亮失败——见 products/feature_flags/evals/eval_instrument_flags.py。这一冲突甚至被构建脚本硬性拦截OMNIBUS_SKILL_NAMES常量build_skills.py列出了六个保留名build_skill()与lint_all()都会检查渲染后/未渲染的 frontmattername命中即报错——包括渲染后才变成保留名的情况Jinja 模板如instrument-{{ logs }}。所以写 skill 前先核对上面的 omnibus 名单如果你的工作属于其中之一就去改 context-mill 的源头。本地测试用 Claude Code 验证在本地用 Claude Code 测试产品 skill可把它同步到.agents/skills/# 构建并同步指定 skill hogli sync:skill -- --name querying-posthog-data # 该 skill 现在位于 .agents/skills/querying-posthog-data/ # Claude Code 通过 .claude/skills - .agents/skills 符号链接拾取它 # 测试完成后移除同步副本 hogli unsync:skill -- --name querying-posthog-data同步的 skills 会被自动 gitignore写入.agents/skills/.gitignore不应提交。sync:skill与unsync:skill都接受--name按源码目录名定位 skillunsync_skill还会解析 frontmattername尝试匹配可能的别名目录build_skills.py。更完整的端到端验证本地运行 MCP server 并核验 skill 行为参见手册中How to develop and test一节。写出有效的 skills上下文窗口是共享资源上下文窗口是共享资源。你的 skill 与系统 prompt、对话历史、其他 skills 和用户的请求竞争。默认假设Agent 已经非常聪明。只包含它还不具备的上下文。质疑每条信息Agent 真的需要这段解释吗官方手册建议的进阶实践包括渐进式披露入口精简、细节按需、反馈回路在 skill 中描述成功标准让 Agent 自我核验、工作流设计步骤间明确产物以及评估驱动开发用真实任务评测 skill 是否让 Agent 更可靠地达成目标。核心取舍始终如一skill 要封装通用型 Agent 没有的 PostHog 专属判断力把领域知识沉淀为可复用资产同时为发现性discovery与上下文预算负责——小集合、富 references、每个 skill 一个清晰触发点是让整套体系长期可维护的关键。延伸阅读手册姊妹篇Adding tools to the MCP server能力本身的实现与注册构建真相源products/posthog_ai/scripts/build_skills.py发现、渲染、校验、打包、同步的全部逻辑模板函数实现pydantic_schema、hogql_example、hogql_functions、schema_columns实战范例exploring-llm-traces聚焦工作流型、querying-posthog-data入口 65 个 references 的参考型hogli 命令管线tools/hogli-commands/hogli_commands/build.py 及其 测试MCP 工具注册表lint 引用校验的数据源services/mcp/schema/tool-definitions.json【免费下载链接】posthog: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.项目地址: https://gitcode.com/GitHub_Trending/po/posthog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考