skill-creator

実装との対応

スキルの種類とパス

スキルと手続きは別レイアウトで管理される。

create_skill が生成するのは上表のスキル（個人または共通）のみ。手続きは write_memory_file 等で procedures/*.md として別途作成する。

read_memory_file でのスキル読み込み

スキル・手続きの本文は read_memory_file(path="...") で記憶ツリー相対パスを指定して読む。システムプロンプトのスキルカタログに、利用可能なパス（例: skills/foo/SKILL.md, common_skills/bar/SKILL.md, procedures/baz.md）が示される。

• 個人スキル: skills/{name}/SKILL.md
• 共通スキル: common_skills/{name}/SKILL.md
• 手続き: procedures/{name}.md

path は Anima ディレクトリ基準の相対パス（共有ツリーは common_skills/ 等のプレフィックス）で渡す。

フロントマターと本文

SKILL.md 先頭の YAML は core/memory/frontmatter.parse_frontmatter() で除去して読む。区切り線 --- は行単位のみ認識されるため、YAML 値や本文中に --- が含まれても誤分割しにくい。

本文のプレースホルダ（*-tool ガイド）

スキル本文では {{now_local}}, {{anima_name}}, {{anima_dir}} 等のプレースホルダが使われる場合がある。外部ツール向けスキル（名前が *-tool で終わる）は、許可設定に応じて animaworks-tool 行のゲート処理が行われる（core/tooling/guide.py の filter_gated_from_guide() 等）。

カタログと description

スキルカタログの Level 1 では name + description がバジェット内に載る。スキル数が多いほど省略されやすいので、description は短く具体的に保つ。全文が必要なときはカタログのパスを read_memory_file で開く。

レガシー互換: description が空のとき、extract_skill_meta() は本文の ## 概要 セクションの最初の非空行をフォールバックとして使う。新規スキルではフロントマターを正とする。

レイアウト上の注意

個人 skills/ 直下の ***.md（フラット単一ファイル）**は、カタログやメタ抽出の対象になりうるが、推奨パスは skills/{name}/SKILL.md。運用上は create_skill によるディレクトリ形式を正とする。

スキルファイルの構造

SKILL.md はYAMLフロントマターとMarkdown本文で構成される。 フロントマターには name と description を必須とする。

create_skill は allowed_tools だけでなく、信頼・出自・分類・ルーティング補助のメタデータも書き出せる。必須は name / description / body で、任意キーは用途が明確なときだけ使う。

---
name: skill-name
description: >-
  スキルが行うことの簡潔な説明（三人称）。
  Use when: このスキルを使う具体的な場面をカンマ区切りで列挙する。
allowed_tools:
  - read_memory_file
  - web_search
trust_level: trusted
source:
  type: anima
  origin: manual
category: communication
use_when:
  - drafting partner emails
trigger_phrases:
  - draft a partner email
negative_phrases:
  - personal diary
domains:
  - gmail
routing_examples:
  - Prepare a reply draft for the bank thread
---

主な任意フィールド: allowed_tools, trust_level, source_type, source_origin, category, promotion_status, skill_policy, use_when, trigger_phrases, negative_phrases, domains, routing_examples。create_skill の引数名では source.type は source_type、source.origin は source_origin として渡す。

description の役割

新規スキルの記述は Agent Skills 標準に沿い、Use when: で利用シーンを書く（詳細は references/description_guide.md）。作成後は python scripts/lint_skill.py で形式を検証できる。

• read_memory_file でパスを指定して読んだ場合: ファイルが存在すれば description のマッチに関係なく 本文が得られる（フロントマター処理・*-tool 関連の扱いは読み込み経路に依存）。
• システムプロンプトのスキルカタログ: Level 1 として name + description がバジェット付きで載る。全文は載らないため、手順が必要なら read_memory_file(path="skills/.../SKILL.md") 等で開く。

レガシー互換: description が空のとき、extract_skill_meta() は本文先頭付近の ## 概要 セクションの最初の非空行を description のフォールバックとして使う。新規スキルではフロントマターを正とし、## 概要 依存は避ける。

description の書き方（Use when: パターン・lint）は references/description_guide.md を参照。

Progressive Disclosure（段階的開示）

スキルの情報は概ね次の段階で開示される。

Level 1 はカタログでコンテキストを消費しやすいため description は簡潔に。Level 2 は手順の中核。Level 3 で長大な参照を分離する。

※ Priming のスキル本文注入経路は廃止済み。本文が必要なら read_memory_file でスキルパスを開く。

作成手順

Step 1: ヒアリング

ユーザーの要求を理解する。以下を確認する:

• 何を自動化・手順化したいか
• 対象は個人スキルか共通スキルか（手続きなら procedures/ への別設計）
• Use when: に書く利用シーン（いつこのスキルを選ぶか）

Step 2: 設計

以下を決定する:

• name: スキル名（ケバブケース、例: my-skill）。外部ツールガイドなら *-tool 規約を検討
• description: 三人称の要約 + Use when: 行（references/description_guide.md を参照）
• body: 手順の構成（セクション分け）。必要なら {{now_local}} 等のプレースホルダを利用
• references / templates: 必要なら外部ファイルの設計
• allowed_tools: 推奨ツールを絞りたい場合のみ
• trust/source/category/policy/routing: 信頼レベル、出自、分類、prompt policy、use_when / trigger_phrases / negative_phrases / domains / routing_examples を必要に応じて設計

Step 3: 作成

create_skill ツールでスキルをディレクトリ構造として作成する。

基本（個人スキル）:

create_skill(skill_name="{name}", description="{description}", body="{body}")

共通スキル:

create_skill(skill_name="{name}", description="{description}", body="{body}", location="common")

references と templates を含める場合:

create_skill(
  skill_name="{name}",
  description="{description}",
  body="{body}",
  location="personal",
  references=[
    {"filename": "description_guide.md", "content": "..."},
  ],
  templates=[
    {"filename": "skill_template.md", "content": "..."},
  ],
  allowed_tools=["read_memory_file", "write_memory_file"]
)

references / templates の filename にパス成分は含めない。_validate_filename() で親ディレクトリ外に解決されないことを確認し、不正なら黙ってスキップ（そのファイルは作られない）。

※ 新規スキルには必ず create_skill を使うこと。write_memory_file で skills/foo.md のような直下の単一ファイルだけを作る方法は非推奨。この形式は read_memory_file(path="skills/foo/SKILL.md") では開けないため、推奨は skills/foo/SKILL.md のディレクトリ形式。

※ 手続きは procedures/{name}.md（フラット1ファイル）。フロントマターはスキルと同様に name / description（＋任意 allowed_tools）を推奨。

Step 4: 確認

• 個人スキル: read_memory_file(path="skills/{name}/SKILL.md") で内容確認
• 共通スキル: read_memory_file(path="common_skills/{name}/SKILL.md") 等、カタログに示されたパスで確認
• 手続き: read_memory_file(path="procedures/{name}.md") で解決できることを確認
• python scripts/lint_skill.py で SKILL.md の frontmatter / description を検証（任意だが推奨）

チェックリスト

保存前に以下を確認する:

• --- で始まり --- で閉じるYAMLフロントマターがある
• name フィールドがある
• description フィールドがある
• description に Use when: があり、かつドメイン固有の具体語を含める（旧 「」 列挙は使わない）
• descriptionがドメイン固有で具体的（「管理を行う」「確認する」のような汎用表現を避け、ツール名・操作名・対象を明記）
• bodyに具体的な手順が記載されている
• 新規ではフロントマターに description を置き、## 概要 だけに説明を依存しない（## 発動条件 等の旧テンプレート形式も避ける）
• 任意メタデータ（trust_level, source, category, skill_policy, use_when, trigger_phrases, negative_phrases, domains, routing_examples）は実際の用途と一致している
• スキルは create_skill で {name}/SKILL.md を作成している（手続きは procedures/*.md で意図通りか）

テンプレート

本スキル同梱の templates/skill_template.md を参照する。または以下をコピーして使用:

---
name: {スキル名}
description: >-
  {具体的な対象}の{具体的な操作}スキル（三人称の短い要約）。
  Use when: {利用シーンをカンマ区切り}
---

# {スキル名}

## 手順

1. ...
2. ...

## 注意事項

- ...

注意事項

• スキルはMarkdown手順書であり、Pythonコード（ツール）とは異なる
• フロントマターの必須フィールドは name と description
• create_skill は信頼・出自・分類・policy・routing補助メタデータも設定できる。不要なキーは増やさず、説明文だけで十分な場合はシンプルに保つ
• bodyが長くなりすぎるとコンテキストを圧迫するため、150行以内を目安にする
• 外部リソース参照（Level 3）は references/ を活用して本文を簡潔に保つ