writing-skills

PostHog エージェント向けスキルの書き方

完全なガイドは docs/published/handbook/engineering/ai/writing-skills.md で読むことができます。

配置場所を選ぶ

• PostHog のツール、API、または顧客のコードを通じた作業には products/<product>/skills/ を使用します。これらのスキルは公開されます。
• PostHog リポジトリのチェックアウトが必要な作業には .agents/skills/ を使用します。これらのスキルはリポジトリ内に留まります。
• スタッフ限定アクセスは、スキルを移動する理由にはなりません。チェックアウトを必要としない MCP ワークフローは公開されたままにします。
• 混在するスキルの場合は、顧客の診断は公開したままにし、PostHog の開発手順は既存の内部スキルまたはリファレンスに移します。
• 公開されたワークフローは、内部スキルファイルに依存してはなりません。

hogli lint:skills は両方の配置場所をチェックします。以下の scaffold、build、sync コマンドは、公開された製品スキルに適用されます。

クイックワークフロー

# 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 は omnibus スキル — 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 のソースを変更してください。ローカルビルドは逆のケースです。ローカルビルドには omnibus スキルが一切含まれないため、いずれかに依存するものはそれを重ねて適用するか、はっきりと失敗しなければなりません。マージ箇所については Context-mill のスキルはこのリポジトリのものを上書きする を参照してください。

スキルを書くのはいつか

製品に新しい機能が追加され、エージェントがその扱い方を知る必要があるときです。 スキルは、どのようなツールが存在するか（それは MCP サーバーです）についてのものではなく、 経験を積んだ人がそれらのツールを使って仕事にどう取り組むかについてのものです。

自問してください。「顧客がエージェントに自分の機能で X を行うよう依頼したら、エージェントは正しいアプローチを理解できるだろうか?」 できないなら、スキルを書きましょう。

多すぎるとはどのくらいか?

スキルの数は予算が決まった共有リソースです — エージェントは すべての スキルの説明の一覧から選び、多くのハーネスはその一覧が長くなると切り詰めるため、余分なスキルが1つ増えるごとに他のスキルが発動しにくくなります。 薄いスキルを多数用意するよりも、それぞれが充実した references/ を持つ、焦点を絞った少数のスキルを優先してください。

• 新しいトリガー → 新しいスキル。 スキルが独自のエントリーポイントを得るのは、その「いつ使うか」が既存のすべてのスキルと明確に区別できる場合だけです。
• 詳細を増やす → references/ であり、新しいスキルではありません。 別の失敗モード、SDK のバリアント、クエリカタログは、既存の仕事に対する深みです — 新しい枠を消費するのではなく、そのスキルの references/ に追加してください。
• ほぼ重複する兄弟を統合する。 診断、バグの種類、トリガーを共有するスキルは、2つではなくリファレンス付きの1つのスキルにすべきです。

主なルール

• 名前: 小文字のケバブケース、可能なら動名詞形を優先（llm-analytics ではなく analyzing-llm-traces）。posthog-* を接頭辞にしないでください。
• 説明: 三人称で、具体的に、トリガーとなる用語と、いつ使うかを含めてください。最大 1024 文字。
• 構造: SKILL.md のエントリーポイント + 詳細な内容のための references/。SKILL.md は 500 行未満に保ってください。
• Frontmatter: name と description は必須です。
• トーン: 厳格な台本ではなく、ワークフローと推論を記述してください。エージェントが適応することを信頼してください。
• 簡潔さ: エージェントは賢いので、すでに持っていない文脈だけを含めてください。

スキルの構造

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 で終わるファイルは、ビルド時に Jinja2 によって products/posthog_ai/scripts/build_skills/ でレンダリングされます。 ビルドパイプラインを拡張して、モノレポが引き続き信頼できる唯一の情報源となるようにしてください — ドメイン知識がコード内（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 以上のリファレンスファイルにリンクする明確なエントリーポイント
• 段階的な開示 — エージェントは必要なものだけを読み込みます
• 静的な .md コンテンツと生成された .md.j2 コンテンツの組み合わせ
• products/posthog_ai/skills/querying-posthog-data/SKILL.md を参照してください

悪い例: llm-analytics

トレース、実験、評価、コスト追跡、プロンプト管理をカバーする包括的なスキル。 範囲が広すぎるため — エージェントはいつこれを有効化すべきかを判断できません。代わりに焦点を絞ったスキルに分割してください。