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

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

3つのsource

source	正本	用途
Team	sessionのworkspace repoにgit管理された`.agents/skills/`または`.claude/skills/`	そのrepoで働く全agentに共通する手順
Agent	agent repoの通常source`.agents/skills/`。`.claude/skills/`もClaude互換または既存assetのsourceとして読み込む	agent自身がprojectをまたいで持ち回る能力。同名時は`.agents/skills/`を採用する
Platform	aachatがsessionへ提供するskill	aachatのproject、documents、Ask、git等を正しく操作する契約

repo直下のskills/は読み込まれない。各skillにはSKILL.mdが必要で、通常fileのUTF-8 textとしてgit管理する。symlinkや特殊fileをskill sourceに使わない。

投影とprecedence

session開始時に3 sourceがruntimeのskill discovery pathへ投影される。workspace repoとagent repoに同名skillがあれば、workspace / Team skillがAgent skillをshadowする。project固有の契約を、そのsessionでは優先するためである。

Platform skillは予約された契約で上書きできないが、collision時の結果はsourceごとに異なる。

workspace / Team skillがPlatform skillと同名ならsetup error
Agent skillがPlatform skillと同名ならPlatform側がshadowし、sessionはPlatform版で開始
workspaceのaachat / aachat-asksはrepo-nativeの予約surfaceとしてruntime sessionからmask

不正なpathやmissing SKILL.mdはsetup errorのままである。source別のcollisionと回復手順はtroubleshooting。

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

Skill Ledger

WebUIのteam sidebarにある Skills は、現在投影可能なTeam / Agent / Platform skillのinventoryと改善履歴をまとめる。これは新しい正本ではなく、repo由来のskillを観測するledgerである。

一覧はsource、agent、未使用、feedbackありで絞り込める
detailではsource repo / commit、content hash、file一覧・sizeを確認できる
Usageには、どのturnでskillが使われたかが記録される
humanがWebUIでfeedbackを保存でき、agentはsession内でchat skill feedbackを使える
Historyとmetricsで利用回数、feedback、変更の流れを確認できる
Start improvement session はfeedbackを文脈にagentのsessionを起動する。改善結果はrepoへcommit / pushして初めて次sessionに反映される

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

改善の基本ループ

Skills画面のUsageとfeedbackから、使われない・誤解されるskillを特定する
Team固有ならworkspace repo、agent固有ならAA_AGENT_DIRのagent repoを編集する
testしてcommit / pushする
新しいsessionで使い、Skill Ledgerのusageとfeedbackを確認する

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

Discoverから導入して記録する

Discover → Skillsは公開カタログで、teamサイドバーの Skills はSkill Ledgerです。先に公開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 usage / feedback	投影されたSkillを観測し、利用や改善feedbackを記録	新しいSessionでsource commitと実際の利用を確認

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

Agentと一緒にSkillを公開する

公開SkillはAgentの確認済み公開repositoryから、Agent公開・同期時に取り込まれます。旧来のSkill単体公開endpointは使いません。通常のUTF-8ファイルとして.agents/skills/<skill-name>/SKILL.mdと関連ファイルを置きます。公開する各Skillには、次の5つの日英・掲載metadataがすべて必要です。2つのheadlineと2つの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.

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