--- title: 'Implement Agent Skills support' state: 'planning' created_at: '2026-07-15T19:43:46Z' updated_at: '2026-07-15T19:56:41Z' assignee: null --- ## 背景 Yoi は再利用可能な作業手順、作法、報告形式、補助資料を、LLM-facing な手順資源として扱う必要がある。これらは external state や authority を直接動かす仕組みではなく、Agent が必要な時に参照・活用する procedural guidance として定義する。 Agent Skills 標準に従い、workspace-local Skills は `.yoi/skills/` 配下の `SKILL.md` package として扱う。Ticket、Worker、workdir、repository、network などの外部状態変更は typed feature/tool surface が持ち、Skill はその使い方や作業の進め方を記述する。 ## 要件 ### Agent Skills 形式 - Skill の workspace ディレクトリは `.yoi/skills/` とする。 - Skill は Agent Skills 標準に従い、各 Skill をディレクトリとして配置する。 ```text .yoi/skills/ / SKILL.md # required scripts/ # optional references/ # optional assets/ # optional ``` - `SKILL.md` は YAML frontmatter + Markdown body とする。 - `SKILL.md` frontmatter は少なくとも以下を扱う。 - `name` required。 - parent directory name と一致する。 - 1-64 characters。 - lowercase letters / numbers / hyphen のみ。 - 先頭/末尾 hyphen と連続 hyphen を禁止する。 - `description` required。 - 1-1024 characters。 - Skill が何をするか、いつ使うかを具体的に書く。 - `license` optional。 - `compatibility` optional。 - `metadata` optional string map。 - `allowed-tools` optional / experimental。実装可否は要決定事項とする。 - `SKILL.md` body は LLM-facing procedural guidance として読み込む。 - 推奨内容: step-by-step instructions、input/output examples、edge cases、report shape。 - main `SKILL.md` は大きくしすぎず、詳細は `references/` 等へ分ける。 - `scripts/` / `references/` / `assets/` は Skill root 相対 path で参照する。 - `references/` は必要時に読む追加 docs。 - `scripts/` は agent が実行し得る補助 code。 - `assets/` は templates / static resources。 ### Progressive disclosure / loading - Skill metadata は startup / Worker initialization 時に軽量 catalog として読めるようにする。 - model-visible な常時情報は `name` と `description` を中心にする。 - Full `SKILL.md` body は Skill が activate / select された時だけ LLM context に入れる。 - `references/` / `scripts/` / `assets/` の内容はさらに必要時だけ読む。 - Builtin skill と workspace skill の discovery / override / provenance を定義する。 - workspace `.yoi/skills//SKILL.md` が同名 builtin skill を override できるかを明示する。 - Skill catalog には source / provenance / override status を含める。 ### Skill と他概念の境界 - Knowledge と Skill の境界を明確にする。 - Knowledge は facts / rationale / reference。 - Skill は task execution guidance / reusable procedure / report shape。 - Plugin / feature との境界を明確にする。 - Skill は prompt/resource であり、外部状態を直接制御しない。 - Ticket / Worker / workdir / queue / repository / network などの authority と状態変更は typed feature/tool surface が持つ。 - Coder review cycle や Orchestrator queue consumption は、Skill + Workspace/Ticket/Worker feature tools の組み合わせで設計する。 - 既存 role prompts / internal prompts / docs は Skill の利用を前提に整理する。 ### Validation / tooling - Skill lint を追加する。 - `SKILL.md` frontmatter required fields / naming convention / parent directory match を検証する。 - unknown / unsupported fields は方針に従って warning または error にする。 - relative file references の安全性を検証する。 - Skill discovery tests を追加する。 - builtin skill loading。 - workspace `.yoi/skills` loading。 - override priority。 - provenance reporting。 - invalid Skill diagnostics。 ## 要決定事項 - Skill activation surface。 - `/skill-name` のような slash command を持つか、Skill selection / activation tool にするか。 - Skill catalog を model-visible にする方法。 - 起動時 prompt に metadata 一覧を常時載せるか、SkillList / SkillRead のような tools で探索させるか。 - `allowed-tools` の扱い。 - Agent Skills 標準では experimental なので、Yoi で authority として尊重するか、lint metadata として読むだけにするか。 - 尊重する場合、既存 feature/tool permission とどう合成するか。 - `scripts/` の実行 authority。 - Skill bundled script を通常 Bash / tool authority で実行するだけにするか、Skill script 実行専用 tool を作るか。 - script dependencies / shebang / executable bit / sandbox の扱い。 - Skill file access。 - `references/` / `assets/` を通常 `Read` で読むだけにするか、Skill resource read tool を作るか。 - deeply nested reference chain をどこまで許すか。 - Builtin skill の配置場所。 - `resources/skills//SKILL.md` とするか、別の runtime resource layout にするか。 - Workspace override policy。 - workspace skill が builtin skill を完全 override するか、同名 conflict を error にするか。 - Profile / role との接続。 - Profile で default active skills / advertised skills を指定するか。 - Orchestrator / Coder / Reviewer roles にどの Skill catalog を見せるか。 - Web Workspace UI。 - `.yoi/skills` の一覧 / validation / edit を Web で扱うか、初期実装では backend / CLI のみにするか。 ## 受け入れ条件 - `.yoi/skills//SKILL.md` が Agent Skills 標準の required frontmatter と naming rules で lint される。 - builtin/workspace Skill の loading、override priority、provenance、lint が tests で確認されている。 - Full `SKILL.md` body は activation 時にのみ LLM context に入り、metadata catalog と progressive disclosure の分離が tests で確認されている。 - role prompts / internal prompts / docs が Skill 前提に更新されている。 - Ticket queue、Worker spawn、workdir 管理などの外部状態制御は Skill ではなく feature/tool surface に残る。 - Skill implementation decision points のうち初期実装で決めないものは、明示的に unsupported / ignored / warning として扱われる。 - affected crates の `cargo test` と `nix build .#yoi` が通る。