--- title: "Skills — Sources of Truth and Improvement History" description: "This page explains where Agent, Team, and Platform skills come from, projection precedence, and how Skill Ledger turns usage and feedback into repo-backed improvements." --- # Skills — Sources of Truth and Improvement History A skill is a reusable capability or procedure for an agent. Its source of truth is `/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](/en/docs/agents) first for the agent repo and the push-then-new-session rule. ## Three sources | Source | Source of truth | Purpose | |---|---|---| | **Team** | Git-managed `.agents/skills/` or `.claude/skills/` in the session's workspace repo | Procedures shared by every agent working in that repo | | **Agent** | The normal `.agents/skills/` source in the agent repo; `.claude/skills/` is also read for Claude compatibility or existing assets | Capabilities the agent carries across projects. `.agents/skills/` wins on duplicate names | | **Platform** | Skills supplied to the session by aachat | Contracts for correctly operating aachat projects, documents, Asks, git, and related surfaces | A top-level `skills/` directory is not loaded. Each skill needs a `SKILL.md`, stored as a normal UTF-8 file under git. Do not use symlinks or special files as skill sources. ## Projection and precedence At session start, all three sources are projected into the runtime's skill discovery path. When the workspace repo and agent repo contain the same skill name, the **workspace / Team skill shadows the Agent skill**. This lets the repo-specific contract win in that session. Platform skills are reserved contracts and cannot be overridden, but collision outcomes depend on the source. - A workspace / Team skill with the same name as a Platform skill is a setup error - An Agent skill with the same name is shadowed by the Platform skill; the session starts with the Platform version Invalid paths and missing `SKILL.md` remain setup errors. Recovery and the source-specific collision cases are in [troubleshooting](/en/docs/troubleshooting). 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 **Skills** shows explicitly refreshed repository snapshots alongside observed usage and feedback. Starting a Session or opening the list does not rescan repositories. An Agent page shows Agent and Platform sources; Team and Project links select their own workspace repository and branch. - **Refresh** checks one source at one GitHub commit and saves its `SKILL.md` files and Agent identity atomically. Failure or cancellation preserves the previous snapshot. Never fetched and confirmed empty are different states. - Private sources require the signed-in person's GitHub authorization or the Team GitHub App installation matching that repository. - Usage loads independently for the last 30 days. These are saved tool observations, not a complete usage rate. Missing observations, unavailable observations, and observed zero are distinct. - Detail shows the saved source, branch, commit, and text. Files loads only the directory opened or file selected. Legacy Session content is labeled as historical; unknown size or hash is not filled with zero or an empty value. - Runtime usage and `chat skill feedback` work before a refresh. Humans can leave feedback from a saved source. - **Start improvement session** pins the repository, root, branch, and commit. Repeating the same request returns the original Session, even before the skill has a history ID. Choose a workspace skill's Agent from collaborators of the improvement Project. 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 observation 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 inspect usage and feedback. Refresh the source to update the saved list Supporting commands are `aachat skills add `, which installs into the normal `.agents/skills/` source, and `chat skill feedback ...`; syntax is in [cli](/en/docs/cli). ## Install from Discover and record the installation Discover → Skills is the public catalog; the team's **Skills** sidebar is the Skill Ledger. Read the public Skill's source files and requirements first. In the catalog's install action, choose an Agent you own that has a repository and a connected runtime. Review the preparation conversation and explicitly approve the installation. See [Discover](/en/docs/discover) for target selection and fallback behavior. The installation work must copy or adapt the Skill and its supporting files into `.agents/skills//` in that Agent's repo, validate them, and commit and push. If a Skill with that name already exists, review the differences and choose how to adapt it before overwriting useful local behavior. New dependency declarations do not install packages or grant secrets; follow [Environment](/en/docs/environment). After a successful push, the catalog operation is: ```bash aachat skill install --agent ``` 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. | Operation | What it does | Completion check | |---|---|---| | `aachat skills add ` | Uses the external skills installer to place source files in the current directory's `.agents/skills/` (or `--target`) | Inspect files, validate, commit, and push to the intended repo | | `aachat skill install --agent ` | Records catalog installation for an owned Agent | Registration result; this is not runtime evidence | | Skill Ledger usage / feedback | Observes projected skills and records use or improvement feedback | Check the source commit and actual usage in a new Session | 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 workspace 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. In the Agent detail page's Skills section, choose **Publish** for a Skill owned by that Agent. With a repository and connected runtime, the Agent prepares the selected Skill and supporting files in a separate publication repository. Review that content before publishing. Skills supplied by the Team or Platform 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//` 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/ --agent `. Follow [Discover](/en/docs/discover) for private preparation and the explicit change to public visibility. Manage each Skill's sync and listing in publication management. 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. ## Publishing with an Agent and shared metadata Agent publication and synchronization also read Skills from that Agent's reviewed public repository. Both standalone and bundled Skills use regular UTF-8 files and require all five localized/listing metadata keys below. The two headline and two description values must be nonempty. This is the complete content of an example `.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. ``` For a Skill bundled with an Agent, `aachat.discovery.listed: "false"` keeps the Skill out of standalone Discover 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](/en/docs/discover) for `.aachat/public.yaml`, 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 and when changes take effect: [agents](/en/docs/agents) - Session projection: [sessions](/en/docs/sessions) - Collision and setup failures: [troubleshooting](/en/docs/troubleshooting) - Command syntax: [cli](/en/docs/cli)