Skills — Sources of Truth and Improvement History

A skill is a reusable capability or procedure for an agent. Its source of truth is <skill-name>/SKILL.md in a Git repository. This page is canonical for where skills live, which same-named skill is used, and how observed usage becomes an improvement. Read agents first for the agent repo and the push-then-new-Session rule.

Four sources

Each skill needs a SKILL.md, stored as a normal UTF-8 file under git. A skill containing symlinks or special files cannot be projected. A top-level skills/ directory in the agent repo is not loaded (the host log shows a warning; move it to .agents/skills/).

Projection and precedence

At Session start, skills from each source are projected into the skill directory of the Session's Runtime: .claude/skills/ for Claude and .agents/skills/ for Codex.

Team skills in the workspace repo are projected even when they sit in the other Runtime's directory. For example, a Claude Session also gets the workspace repo's .agents/skills/* in .claude/skills/. Only git-tracked real directories with a regular-file SKILL.md are projected. If both directories in the workspace repo have the same skill name, the Runtime's own directory wins, and files tracked by the repo are never overwritten.

When names collide, the result is:

An agent skill directory without SKILL.md is also a setup error. Recovery and source-specific collision cases are in troubleshooting. Agent and Plugin skills that use a retired platform skill name (such as aachat-session or aachat-ask) are not projected.

The aachat skill that aachat init writes into a repo is not a Platform name, so it projects like any other workspace skill. Its own SKILL.md says it is not for use inside a Session.

Because the repo is canonical, commit and push a skill change, then start a new Session. There is no hot reload into a running Session.

Skill Ledger

Skill Ledger shows repository versions checked when you open the list separately from observed usage and feedback. In the WebUI, see it on an Agent profile's Skills tab (agents) and on the Team-wide Skills screen (/t/<team>/skills). The Team sidebar has no link to the Skills screen; open the URL or use the back link from a Skill detail. Opening the list automatically checks connected repositories; a Session or manual refresh is not required.

• On the Team-wide Skills screen, choose the source with Team / Agent / Platform at the top. For Agent, pick the Agent in the filter. When Skills is opened from a Project, that Project's repository and branch are used
• On an Agent’s Skills tab, search names and descriptions and select Agent レポジトリ / Team レポジトリ. Unchecking both shows no results. aaChat standard Skills are excluded from this list and its counts. Returning from a detail preserves these filters
• The first visit waits for the repository check. On a return visit, a cached list may appear with Checking for updates…. The Agent default branch or selected workspace branch is checked, and skills and identity.md use the same commit. Confirmed empty, connection required, and failed checks are distinct states
• A temporary failure offers Retry and may show the last saved version from the same connection. A disconnected or revoked connection hides the old content
• Connect repository authorizes a stored GitHub App connection. Only the Agent owner can connect an Agent repository; only Team owners/admins can connect a workspace repository, including a Project override. Ordinary viewers use that connection without their own OAuth step. Configure GitHub App opens installation settings if needed
• Usage covers the last 30 days and counts saved tool observations. It is not proof of non-use or a complete usage rate. Not fetched, missing observations, and observed zero are distinct. Agent rows show 「集計期間　過去30日」 and counts such as 「12 回利用」. On the Team-wide screen, filter with 「期間内の利用記録なし」 (no usage in the period) and 「フィードバックあり」 (has feedback)
• Detail has 内容 (content), フィードバック (feedback), and 変更履歴 (changes) tabs. The source is checked before directly linked detail is read. Text and additional files use the selected version; if it changes, reopen the skill from the list. Expand 取得バージョン below the text for source, branch, and commit. Legacy Session content is labeled as historical
• When the text's repository and commit are known, relative links open the referenced file at that commit in a new GitHub tab. The file list switches content within the current view. Reading on GitHub requires access to that repository
• Feedback shows actor type and text; changes show date, content hashes, and commit. The API returns the latest 100 events, so older records may be outside this range
• Runtime usage and chat skill feedback are saved even before the snapshot is refreshed

The Agent Skills tab checks the Agent repository and the current Team repository by default. When opened from a Project, it checks that Project’s selected workspace repository instead. Team skill candidates that are symlinks are skipped; real directories from both skill roots remain visible. This is a repository list, not a list of skills injected into a particular Session. Agent repository read permission is separate from the connection used to run the agent. Until its owner grants that permission, available Team skills still appear.

Feedback and improvement Sessions

A Skill detail lets you save feedback (what happened, file or step, suggestion). An agent inside a Session records it with chat skill feedback <skill-name> "<text>". When several skills share the name, use the selector the error shows.

Read older saved feedback in the detail view’s Feedback tab with Load more. Within their own Session, agents can use chat skill feedback-list <skill-id> --team <slug>, follow next_page, and open source sessions with detail_read. Each read uses that Session’s current project access and accepted sources.

For skills other than Platform skills, you can start an improvement Session from the detail.

1. Open フィードバックを書く and enter what happened. フィードバックを保存 saves feedback by default
2. Select 保存したフィードバックで改善を依頼する, choose a Project and Agent, and press 保存して改善Sessionを開始. If saving succeeds but starting fails, 改善Sessionの開始を再試行 retries only the start
3. The improvement Session starts pinned to the repository, root, branch, and commit. Repeating the same request returns the same Session

A skill without a confirmed version (commit) cannot start one; open its Skills list and resolve any connection or acquisition error first.

Platform skills are read-only. Send improvement feedback to aachat instead of editing them in the project or agent repo.

Basic improvement loop

1. Read the Skill Ledger usage coverage and feedback to select a skill to improve
2. Edit the workspace repo for a Team-specific skill, or the agent repo at AA_AGENT_DIR for an Agent-specific skill
3. Test, commit, and push
4. Use it in a new Session and check usage and feedback. Reopen the Agent profile's Skills tab to check the repository version

To have an agent propose new Skills from its recent work, use Improve agent on the Agent profile (agents).

Supporting commands are aachat skills add <skill-name>, which installs into .agents/skills/, and chat skill feedback <skill-name> ...; syntax is in cli.

Install from Discover and record the installation

Discover's Skills is the public catalog and is separate from Skill Ledger. Read the public Skill's source files and requirements first. On the Skill detail, choose Add to my agent and pick an Agent you own that has a repository and a connected runtime. Review the preparation conversation and explicitly approve the installation. See Discover for target selection and fallback behavior.

The installation work copies or adapts the Skill and its supporting files into .agents/skills/<skill-name>/ in that Agent's repo, validates them, and commits and pushes. If a Skill with that name already exists, review the differences and choose how to adapt it before overwriting useful local behavior. Dependency declarations do not install packages or grant secrets; follow Environment.

After a successful push, the catalog operation is:

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

Use the actual catalog UUID and your target Agent name from the installation flow. This records an installation receipt. It does not download files, push commits, restart a Session, or verify usage. Repeating the registration for the same Agent reports that it is already recorded. Only the target Agent's owner can register it.

If registration fails after the file push, repair authentication, ownership, or the catalog ID and retry only registration. If the receipt exists but the Skill is absent in a Session, check the pushed commit, new-Session timing, and source precedence. A Team skill can shadow the installed Agent skill.

Publish a Skill on its own

You can publish a Skill without publishing its Agent in Discover. The original Agent's GitHub repository can stay private. Expand スキルの取得元 on the Agent profile's Skills tab and choose Publish for a Skill owned by that Agent, or choose Publish something new in Discover's Publication management and select Skill as the type. An Agent with a repository and a connected runtime prepares only the selected Skill and supporting files in a separate publication repository. Review that content before publishing. Skills supplied by a Team, Platform, or Plugin do not have this publication action.

A standalone Skill does not need an Agent publication profile or .aachat/public.yaml. Put SKILL.md and supporting files in .agents/skills/<skill-name>/ in the publication repository, with aachat.discovery.listed set to "true" in the metadata below. The CLI command in that prepared repository is aachat skill publish .agents/skills/<skill-name> --agent <agent-name>. Follow Discover for private preparation and the explicit change to public visibility.

Open a Skill from publication management to read its contents and supporting files, sync it, or stop its listing. Unlisted Skills remain in the list; view their contents on GitHub. Stopping the source Agent's listing or changing its publication repository does not remove standalone Skills. Sync reads public repository changes into the catalog; it does not distribute updates to Agents that installed the Skill.

Publication metadata and Skills bundled with an Agent

What a Skill's publication metadata must contain depends on what you publish.

This is the complete content of an example .agents/skills/source-review/SKILL.md:

---
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.

For a Skill bundled with an Agent, only a Skill with aachat.discovery.listed set to "true" gets a standalone Discover listing. "false" or no value keeps it out of standalone listing, but its files are still public with the Agent repository. A standalone Skill publication requires "true". The flag is a catalog choice, not an access control. The localized metadata describes the Skill in Discover; it does not translate its instructions automatically.

Review the repository's license, private content, and all supporting files before the human owner publishes it. Follow Discover for the public profile, explicit public visibility, sync, and stopping the Agent/Skill listing. Catalog lineage records a source relationship; it does not automatically install upstream updates into existing Agents.

Related pages

• Agent repo, when changes take effect, and Improve agent: agents
• Session projection: sessions
• Collision and setup failures: troubleshooting
• Command syntax: cli
• Public catalog, Plugins, and publication: Discover