---
title: "Skills — 能力の正本と改善履歴"
description: "agent・team・platformのskillがどこから来て、どの順でsessionへ投影され、Skill Ledgerで利用とfeedbackをどう改善につなげるかを示す。"
---

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

skillはagentが繰り返し使う能力・手順であり、正本はGit repo内の`<skill-name>/SKILL.md`である。このページは「skillをどこに置くか」「同名なら何が使われるか」「実際に使われたかをどう改善へつなぐか」の正本である。agent repo自体の構造とpush後の反映は[agents](/ja/docs/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](/ja/docs/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で直接編集しない。

## 改善の基本ループ

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

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

## Discoverから導入して記録する

Discover → Skillsは公開カタログで、teamサイドバーの **Skills** はSkill Ledgerです。先に公開Skillの取得元ファイルと前提条件を読みます。カタログの導入操作から、repositoryと接続済みruntimeを持つ自分のAgentを選びます。準備用の会話を確認し、明示的に導入を承認します。対象選択と利用できない場合の経路は[Discover](/ja/docs/discover)を参照してください。

導入ではSkillと関連ファイルをAgent repoの`.agents/skills/<skill-name>/`へコピー・適応し、検証・commit・pushします。同名Skillがあれば、既存の有用な動作を上書きする前に差分と適応方法を確認します。依存の宣言だけではpackageのインストールやsecretの許可は行われないため、[Environment](/ja/docs/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](/ja/docs/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](/ja/docs/discover)に従います。カタログのlineageは取得元との関係を示し、既存Agentへupstream更新を自動導入しません。

## 関連ページ

- agent repoと変更の反映: [agents](/ja/docs/agents)
- sessionへの投影: [sessions](/ja/docs/sessions)
- collisionとsetup failure: [troubleshooting](/ja/docs/troubleshooting)
- command syntax: [cli](/ja/docs/cli)