--- 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 - Workspace skills named `aachat` or `aachat-asks` are reserved repo-native surfaces and are masked from the runtime session Invalid paths and missing `SKILL.md` remain setup errors. Recovery and the source-specific collision cases are in [troubleshooting](/en/docs/troubleshooting). 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** in the WebUI team sidebar is an inventory and improvement history for currently projectable Team, Agent, and Platform skills. It observes repo-backed skills; it is not a second source of truth. - Filter the list by source, agent, unused skills, or skills with feedback - A detail view shows source repo / commit, content hash, files, and size - Usage records the turns in which the skill was used - Humans can save feedback in the WebUI; agents can use `chat skill feedback` inside a session - History and metrics show usage, feedback, and change over time - **Start improvement session** starts an agent session with the feedback as context. The result affects future sessions only after it is committed and pushed to the source repo Platform skills are read-only. Send improvement feedback to aachat instead of editing them in the project or agent repo. ## Basic improvement loop 1. Use Skill Ledger usage and feedback to find a skill that is unused or misunderstood 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, then inspect usage and feedback in Skill Ledger 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 Skills with an Agent Public Skills are derived from the Agent's reviewed public repository during Agent publication and synchronization. Do not use a standalone legacy Skill publication endpoint. Place regular UTF-8 `SKILL.md` files in `.agents/skills//` and include supporting files. Each publication Skill needs 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. ``` `aachat.discovery.listed: "false"` keeps the Skill out of standalone Discover listing, but its files are still public with the Agent repository. 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)