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版で開始

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

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

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

Skill Ledger

WebUI の Skills は、明示的に確認した repository の保存一覧と、Session で観測した利用・feedback の履歴を表示します。Session の開始や一覧の表示では repository を再走査しません。Agent の一覧は Agent と Platform、Team の一覧は Team の設定を使います。Project から開いた workspace 一覧には、その Project の repository と branch が適用されます。

Refresh は source ごとに GitHub の一つの commit を確認し、SKILL.md と Agent identity をまとめて保存します。失敗・取消時は前の保存結果が残ります。未取得と確認済みの空一覧は別の状態です。
private repository の確認には本人の GitHub 認可、または対象 repository と一致する Team の GitHub App 接続を使います。
利用は独立した直近30日の集計です。保存できた tool の観測回数であり、未使用の断定や全体の利用率ではありません。未取得、観測欠損、観測済み0件を区別します。
detail には source、branch、commit と保存した本文を表示します。Files は開いた directory と選んだ本文だけを取得します。旧 Session の本文は履歴資料として区別し、未知の size や hash を0や空値で補いません。
refresh 前でも runtime の usage と chat skill feedback を保存できます。human は保存一覧から feedback を残せます。
Start improvement session は対象の repository・root・branch・commit を固定して Session を開始します。同じ対象の再送は同じ Session に戻ります。skill にまだ履歴 ID がなくても開始できます。workspace skill の対象 Agent は改善先 Project の協力者から選びます。

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

改善の基本ループ

Skills画面の観測範囲とfeedbackを読み、手順を見直す候補を選ぶ
Team固有ならworkspace repo、agent固有ならAA_AGENT_DIRのagent repoを編集する
testしてcommit / pushする
新しいSessionで使い、usageとfeedbackを確認する。画面の保存一覧を更新する場合はsourceをRefreshする

補助コマンドは通常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を隠す場合があります。

Skillを単体で公開する

AgentをDiscoverへ公開せず、所有するSkillだけを公開できます。元AgentのGitHub repositoryはprivateのままで構いません。Agent詳細のSkills欄で、そのAgentが所有するSkillの Publish を選びます。repositoryと接続済みruntimeがあるAgentで、対象Skillと必要ファイルだけを別の公開用repositoryへ準備し、公開内容を確認してから公開します。TeamやPlatformから提供された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ごとに同期・掲載停止できます。元Agentの掲載停止や公開先変更では、単体公開したSkillは削除されません。同期は公開repositoryの変更をカタログへ反映する操作であり、導入済みAgentへ更新を配布する操作ではありません。

Agentと一緒に公開する場合と共通metadata

Agentの公開・同期時には、その公開repositoryに含まれるSkillも取り込まれます。Skill単体公開でもAgent同梱でも、通常のUTF-8ファイルを使い、次の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.

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

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