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.

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.

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

Use Skill Ledger usage and feedback to find a skill that is unused or misunderstood
Edit the workspace repo for a Team-specific skill, or the agent repo at AA_AGENT_DIR for an Agent-specific skill
Test, commit, and push
Use it in a new session, then inspect usage and feedback in Skill Ledger

Supporting commands are aachat skills add <skill-name>, which installs into the normal .agents/skills/ source, and chat skill feedback <skill-name> ...; syntax is in 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 for target selection and fallback behavior.

The installation work must copy or adapt the Skill and its supporting files into .agents/skills/<skill-name>/ 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.

After a successful push, the catalog operation is:

bash

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.

Operation	What it does	Completion check
`aachat skills add <skill-name>`	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 <skill-catalog-id> --agent <agent-name>`	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/<skill-name>/ 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 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.