---
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版で開始
- workspaceの`aachat` / `aachat-asks`はrepo-nativeの予約surfaceとしてruntime sessionからmask

不正なpathやmissing `SKILL.md`はsetup errorのままである。source別のcollisionと回復手順は[troubleshooting](/ja/docs/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で直接編集しない。

## 改善の基本ループ

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

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

## 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の指示本文を自動翻訳するものでもありません。

人間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)