Skills — 能力の正本と改善履歴

skillはagentが繰り返し使う能力・手順であり、正本はGit repo内の<skill-name>/SKILL.mdである。このページは「skillをどこに置くか」「同名なら何が使われるか」「実際に使われたかをどう改善へつなぐか」の正本である。agent repo自体の構造とpush後の反映はagentsを先に読む。

4つのsource

source	正本	用途
Team	Sessionのworkspace repoにgit管理された`.agents/skills/`または`.claude/skills/`	そのrepoで働く全agentに共通する手順
Agent	agent repoの`.agents/skills/`。`.claude/skills/`もClaude互換または既存assetのsourceとして読み込む	agent自身がprojectをまたいで持ち回る能力。同名時は`.agents/skills/`を採用する
Plugin	agent repoの`.agents/plugins/<name>/`に追加したPluginのskill	Discoverから追加した束。追加手順はDiscover
Platform	aachatがSessionへ提供するskill（`aachat-project`、`aachat-self-improvement`、`aachat-brainstorm`、`aachat-mindmap`など）	aachatのproject、documents、Ask等を正しく操作する契約

各skillにはSKILL.mdが必要で、通常fileのUTF-8 textとしてgit管理する。symlinkや特殊fileを含むskillは投影できない。agent repo直下のskills/は読み込まれない（ホストのログに警告が出る。.agents/skills/へ移す）。

投影と優先順位

Session開始時、各sourceのskillは、そのSessionのRuntimeのskill置き場へ投影される。Claudeは.claude/skills/、Codexは.agents/skills/である。

workspace repoのTeam skillは、Runtimeの置き場と違う側にあっても投影される。たとえばClaudeのSessionでも、workspace repoの.agents/skills/*が.claude/skills/に入る。対象は、git管理された実directoryで、通常fileのSKILL.mdを持つものだけである。workspace repo内の両方に同名skillがあれば、Runtime自身の置き場の側が優先され、repoが管理しているファイルは上書きされない。

同名skillがあるときの結果は次のとおりである。

衝突	結果
Team skill と Agent / Plugin skill	Team skillが優先（Agent側はそのSessionでは使われない）
Team skill と Platform skill	setup error。Sessionは起動しない
Agent skill と Platform skill	Platform skillが優先。SessionはPlatform版で開始する
Plugin skill と Agent / Platform skill	Agent / Platform側が優先。Plugin側は読み込まれない
Plugin同士	Plugin directory名の辞書順で先のものが優先

SKILL.mdがないagent skill directoryもsetup errorになる。source別のcollisionと回復手順はtroubleshooting。以前のplatform skill名（aachat-session、aachat-askなど）を使ったagent skillとplugin skillは投影されない。

aachat initがrepoに書くaachat skillはPlatform名ではないので、他のworkspace skillと同じに投影される。Sessionの中では使わないことは、そのSKILL.md自身が述べる。

repoが正本なので、skillを変えたらcommit / pushし、新しいSessionを起動する。稼働中Sessionへのhot reloadはない。

Skill Ledger

Skill Ledgerは、一覧を開いたときに確認したrepositoryの保存一覧と、Sessionで観測した利用・feedbackの履歴を分けて表示する。WebUIでは、AgentのプロフィールのSkillsタブ（agents）と、Team全体のSkills画面（/t/<team>/skills）で見る。Teamのサイドバーには Skills画面へのリンクはないため、URLを開くか、Skill詳細の戻るリンクから移動する。一覧を開くと接続済みrepositoryの現在版を自動確認する。Sessionの起動や手動更新は不要。

Team全体のSkills画面では、上部の Team / Agent / Platform でsourceを選ぶ。Agentを選んだときは、フィルターで対象Agentを選ぶ。ProjectからSkillsを開いた場合は、そのProjectのrepositoryとbranchが使われる
AgentのSkillsタブでは、名前・説明の検索と Agent レポジトリ / Team レポジトリ のチェックで絞り込む。両方のチェックを外すと0件になる。aaChat標準Skillは一覧と件数に含めない。詳細から戻っても検索条件を保持する
初回はrepositoryの取得完了を待つ。再訪時にブラウザのキャッシュがあれば、前回分に Checking for updates… を添えて表示する。Agentのdefault branch、または選択したworkspaceのbranchを確認し、Skillとidentity.mdを同じcommitに揃える。確認済み0件、接続が必要、確認失敗は別の状態である
一時的な失敗では Retry を表示し、同じ接続で確認できた前回分があればその旨を示して表示する。切断・失効時には旧本文を表示しない
Connect repository でGitHub App接続を保存する。Agentの接続は所有者、workspaceの接続はTeam owner/adminが行う。Project overrideも対象。通常の閲覧者は保存された接続を使い、都度OAuthは求められない。必要なら Configure GitHub App からApp設定を開く
利用は直近30日の集計で、保存できたtoolの観測回数である。未使用の断定や全体の利用率ではない。未取得、観測欠損、観測済み0件を区別する。Agentの一覧には「集計期間　過去30日」と「12 回利用」の形式で表示する。Team全体の画面では「期間内の利用記録なし」「フィードバックあり」で絞り込める
詳細は内容 / フィードバック / 変更履歴 の3タブ。直接URLでも先に保存元を確認する。本文と追加ファイルは選択した版に揃え、版が変わった場合は一覧から開き直す。本文下の 取得バージョン でsource、branch、commitを確認する。旧Sessionの本文は履歴資料として区別して表示する
repositoryとcommitが確認できた本文の相対リンクは、同じcommitの参照先をGitHubの新しいタブで開く。ファイル一覧は画面内で切り替える。GitHubでの閲覧には、そのrepositoryへのアクセス権が必要
フィードバックは投稿者種別と本文、変更履歴は日時・内容ハッシュ・コミットを表示する。取得範囲は最新100イベントのため、表示範囲外の記録がある場合もある
保存一覧の更新前でも、Sessionの利用記録とchat skill feedbackは保存できる

AgentのSkillsタブは、通常はAgent repositoryと現在のTeam repositoryを確認する。Projectから開いた場合は、そのProjectが選択するworkspace repositoryを使う。Teamのスキル候補直下にあるsymlinkは除外し、両方のスキル配置先の実ディレクトリは表示する。これはrepositoryの一覧であり、特定のSessionへ注入されたスキルの一覧ではない。Agent repositoryの読取承認はAgentの実行用接続とは別に必要で、ownerの承認待ちでも取得できたTeamスキルは表示する。

feedbackと改善Session

Skillの詳細からfeedback（内容、ファイル・手順、改善案）を保存できる。Session内のagentはchat skill feedback <skill-name> "<内容>"で記録する。同名候補があるときは、エラーに示される指定を使う。

保存済みのフィードバックは詳細画面の「フィードバック」から「さらに読み込む」で遡れます。Agent は本人Session内で chat skill feedback-list <skill-id> --team <slug> を使い、next_page で続きを、detail_read で元Sessionを読みます。各読取は本人Sessionの現在のProject閲覧権限と受理済みsourceに従います。

Platform以外のskillでは、詳細から改善Sessionを開始できる。

フィードバックを書く から必須の「困ったこと・改善したいこと」を入力する。通常は フィードバックを保存 だけを行う
保存したフィードバックで改善を依頼する を選び、Project・担当Agentを選択して 保存して改善Sessionを開始 を押す。保存後に開始だけ失敗した場合は 改善Sessionの開始を再試行 で開始だけをやり直す
改善Sessionは対象のrepository・root・branch・commitを固定して始まる。同じ対象の再送は同じSessionに戻る

確認済みの版（commit）がないskillでは開始できない。先にSkills一覧を開き、接続や取得のエラーを解消する。

Platform skillはread-onlyである。改善案はfeedbackとしてaachat側へ渡し、project repoやagent repoで直接編集しない。

改善の基本ループ

Skill Ledgerの利用範囲とfeedbackを読み、手順を見直す候補を選ぶ
Team固有ならworkspace repo、agent固有ならAA_AGENT_DIRのagent repoを編集する
testしてcommit / pushする
新しいSessionで使い、利用とfeedbackを確認する。repositoryの現在版はAgentのSkillsタブを開き直して確認する

agentに最近の仕事から新しいSkillを提案させるには、Agentのプロフィールの Improve agent を使う（agents）。

補助コマンドは.agents/skills/へ追加するaachat skills add <skill-name>とchat skill feedback <skill-name> ...。syntaxはcli。

Discoverから導入して記録する

Discoverの スキル は公開カタログで、Skill Ledgerとは別物である。先に公開Skillの取得元ファイルと前提条件を読む。Skillの詳細で 自分のエージェントに追加 を選び、repositoryと接続済みruntimeを持つ自分のAgentを選ぶ。準備用の会話を確認し、明示的に導入を承認する。対象選択と利用できない場合の経路はDiscoverを参照する。

導入ではSkillと関連ファイルをAgent repoの.agents/skills/<skill-name>/へコピー・適応し、検証・commit・pushする。同名Skillがあれば、既存の有用な動作を上書きする前に差分と適応方法を確認する。依存の宣言だけではpackageのインストールやsecretの許可は行われないため、Environmentに従って準備する。

push成功後に使うカタログ操作は次である。

bash

aachat skill install <skill-catalog-id> --agent <agent-name>

導入フローで得た実際のカタログUUIDと対象Agent名を使う。これは installation receipt（導入記録） を保存する操作である。ダウンロード、commitのpush、Session再起動、利用検証は行わない。同じAgentへの登録を繰り返すと記録済みと返る。登録できるのは対象Agentのownerだけである。

操作	行うこと	完了の確認
`aachat skills add <skill-name>`	外部skills installerで現在のディレクトリの`.agents/skills/`（または`--target`）へsourceを配置	ファイルを確認・検証し、意図したrepoへcommit・push
`aachat skill install <skill-catalog-id> --agent <agent-name>`	所有Agentへのカタログ導入を記録	登録結果。runtimeでの利用の証拠ではない
Skill Ledgerの利用 / feedback	投影されたSkillを観測し、利用や改善feedbackを記録	新しいSessionでsource commitと実際の利用を確認

ファイルのpush後に登録だけ失敗した場合は、認証、ownership、カタログIDを直して登録だけ再試行する。receiptがあるのにSessionにSkillがなければ、pushしたcommit、新規Sessionの開始時点、sourceの優先順位を確認する。Team skillが導入したAgent skillを隠す場合がある。

Skillを単体で公開する

AgentをDiscoverへ公開せず、所有するSkillだけを公開できる。元AgentのGitHub repositoryはprivateのままで構わない。AgentのプロフィールのSkillsタブの スキルの取得元 を開き、そのAgentが所有するSkillの Publish を選ぶか、Discoverの公開管理で Publish something new を選び、種類で スキル を選ぶ。repositoryと接続済みruntimeがあるAgentが、対象Skillと必要ファイルだけを別の公開用repositoryへ準備する。公開内容を確認してから公開する。Team・Platform・Pluginから提供されたSkillには、この公開操作はない。

Skill単体の公開にはAgent用の.aachat/public.yamlや公開プロフィールは不要である。公開先に.agents/skills/<skill-name>/SKILL.mdと関連ファイルを置き、下記metadataのaachat.discovery.listedを"true"にする。準備済みrepositoryで使うCLIはaachat skill publish .agents/skills/<skill-name> --agent <agent-name>である。privateの準備と明示的なpublic化の手順はDiscoverを参照する。

公開管理の一覧から対象Skillを開き、本文・同梱ファイルの確認、同期、掲載停止ができる。掲載停止後も一覧には残り、中身はGitHubで確認する。元Agentの掲載停止や公開先変更では、単体公開したSkillは削除されない。同期は公開repositoryの変更をカタログへ反映する操作であり、導入済みAgentへ更新を配布する操作ではない。

公開用metadataとAgent同梱Skill

Skillの公開用metadataに求められる条件は、公開の種類で異なる。

場面	metadataの扱い
Skill単体の公開	通常のUTF-8ファイルで、次の5つの日英・掲載metadataをすべて用意する。2つのheadlineと2つのdescriptionは空にできず、`aachat.discovery.listed`は`"true"`にする
Agentの公開	同梱Skillにfrontmatterや日英metadataがなくてもAgentを公開できる。Skillのファイルは公開repositoryに含まれる
同梱SkillのSkillカタログ掲載	Agentの公開・同期時に、公開repositoryの`.agents/skills/`にあるSkillが読み込まれる。metadataが不正なSkill（値が文字列でない、`aachat.discovery.listed`が`"true"`/`"false"`以外など）はSkillカタログへの登録から外れ、Agentの公開は続く。headlineやdescriptionがないときは、Skillの`name`・`description`などで代わりに表示する

.agents/skills/source-review/SKILL.mdの内容全体の例である。

yaml

---
name: source-review
description: Review public sources and record citations.
metadata:
  aachat.headline.ja: 公開情報を出典付きで整理する
  aachat.headline.en: Review public sources with citations
  aachat.description.ja: 公開情報を比較し、事実と推定を分けて報告する手順。
  aachat.description.en: Compare public sources and separate facts from estimates.
  aachat.discovery.listed: "true"
---

# Source review

Read the supplied public sources. Record each source URL, distinguish facts
from estimates, and write a referenced summary. Do not contact third parties.

Agent同梱の場合、aachat.discovery.listedを"true"にしたSkillだけがDiscoverに単体掲載される。"false"や指定なしは単体掲載しない扱いだが、ファイルはAgent repositoryとともに公開されたままである。Skill単体の公開では"true"が必要である。カタログの選択であり、アクセス制御ではない。日英metadataはDiscoverの説明で、Skillの指示本文を自動翻訳するものでもない。

人間ownerが公開する前に、repositoryのライセンス、private情報、関連ファイルを確認する。公開プロフィール、明示的なpublic化、同期、AgentとSkillの掲載停止はDiscoverに従う。カタログのlineageは取得元との関係を示し、既存Agentへupstream更新を自動導入しない。