Skip to content

authoring.md

Latest commit

 

History

History
118 lines (78 loc) · 5.06 KB

authoring.md

File metadata and controls

118 lines (78 loc) · 5.06 KB
Raw

アセット執筆ガイド

スケルトンの TODO を埋めるときの指針。

インストラクションとスキルの使い分け

判断基準は 「毎回コンテキストに載せる価値があるか」 の一点。

インストラクション（AGENTS.md） スキル（SKILL.md）
ロード 全セッションの開始時に常時 エージェントが必要と判断したときのみ
コスト 常にトークンを消費する 使わなければゼロ
向く内容 概要、地図、毎回守らせたい規約 手順、特定領域の実装方法、コード例
分量 200 行以内が目安 500 行 / 5000 トークン以内が目安

迷ったらスキルへ置く。インストラクションが長くなるほど、そこに書いた指示の追従率が全体的に下がる。

インストラクションの書き方

検証可能な粒度で書く。 エージェントは曖昧な指示を恣意的に解釈する。

悪い: 適切にエラーハンドリングする
良い: 業務例外は XXX を送出する。P層で捕捉し、B層では捕捉しない。

矛盾を残さない。 2つの指示が衝突すると、どちらが選ばれるかは不定になる。

コードから読み取れることは書かない。 ディレクトリ一覧や依存関係の羅列は、エージェントが自分で読める。 書く価値があるのは、読んでも分からないこと — 規約の理由、落とし穴、既定値と異なる判断。

スキルの書き方

description が最重要

エージェントは起動時に name と description だけを見て、そのスキルを読むかどうかを決める。 本文がどれだけ良くても、description が弱いとそもそも起動しない。

  • 何をするか と いつ使うか の両方を書く
  • 実際のクラス名・メソッド名・用語をキーワードとして含める （エージェントはユーザーの語彙と description を照合する）
  • 最大 1024 文字
# 悪い
description: D層の実装を助けます。

# 良い
description: OpenTouryo の D層（データアクセス層）を実装する。CmnDao による参照系SQL、
  D層生成ツールが生成する Dao による更新系CRUD、動的パラメタライズドクエリ、
  タイムスタンプによる楽観排他を扱う。Dao / Dam / SQL ファイル / DB アクセス を伴う作業のときに使う。

コード例が本体

エージェントはスキル内のコード例を最も強く模倣する。説明文より効く。

  • 断片ではなく、ビルドが通る完結した例を貼る
  • 実際のコードベースからコピーするのが最も確実
  • 「こう書く」の例と同じくらい「こう書かない」の例が効く

Progressive Disclosure

スキルは3段階でロードされる。この構造を前提に配置する。

  1. name + description（約100トークン） — 全スキル分が常時ロードされる
  2. SKILL.md 本文 — スキル起動時にロードされる
  3. references/ scripts/ assets/ — 本当に必要なときだけ読まれる

網羅的な API 一覧、DBMS 差異、仕様の細部は references/ へ。 SKILL.md には「判断に必要なこと」だけを残す。

参照は SKILL.md から1階層に留める。深い参照チェーンは辿られない。

命名規則（標準の制約）

name は以下を満たす必要がある。親ディレクトリ名と一致していなければならない。

  • 1〜64文字
  • 小文字英数字（a-z 0-9）とハイフン（-）のみ
  • ハイフンで開始・終了しない
  • 連続ハイフン（--）を含まない

スキルの粒度

1スキル = 1つのまとまった作業。肥大化してきたら分割する。

opentouryo-layer-p が MVC / WebAPI / WebForms / WPF を全部抱えている
  → opentouryo-layer-p-mvc / opentouryo-layer-p-webapi ... へ分割

opentouryo-common が例外 / ログ / 認証 / 設定を全部抱えている
  → opentouryo-exception / opentouryo-logging / opentouryo-auth ... へ分割

HTML コメントの扱い

スケルトン内の <!-- ... --> は執筆者向けのメモ。

Claude Code はブロックレベルの HTML コメントをコンテキスト注入前に除去するため、 残したままでもトークンを消費しない。ただし他プロダクトでは除去されない。 配布前に不要なものは削除するのが安全。

検証

Agent Skills 標準への準拠は公式の参照実装で検証できる。

skills-ref validate ./src/skills/opentouryo-layer-d

https://github.com/agentskills/agentskills/tree/main/skills-ref

参考