Hare/yoi
1
1
Fork 0
Code Actions Packages Releases Activity
29db1b6270
yoi/.yoi/tickets/00001KXKMX0QM/item.md

6.7 KiB
Raw Blame History

title state created_at updated_at assignee
Implement Agent Skills support planning 2026-07-15T19:43:46Z 2026-07-15T19:56:41Z 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 をディレクトリとして配置する。
.yoi/skills/
  <skill-name>/
    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/<name>/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/<name>/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-name>/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 が通る。