Skills

A skill is a structured bundle — a SKILL.md plus any supporting files — that teaches an agent a specialized domain: your API conventions, a testing playbook, a code-review checklist. Unlike rules, a skill's knowledge loads only when it's relevant, so it doesn't crowd the agent's context on every turn.

Anatomy of a skill

~/.agents/skills/
  api-conventions/
    SKILL.md          # what it is + when to use it (frontmatter + body)
    rules/            # optional rules that apply only when the skill is invoked
    reference.md      # optional supporting files the skill can pull in

The SKILL.md frontmatter carries a name and a description — the description is how the agent decides the skill is relevant to the task at hand.

Rules vs. commands vs. skills

• Rules — always in context. Short, universal standards.
• Commands — a single action you invoke by name (/commit).
• Skills — a body of domain knowledge (and optional rules) that activates when the task calls for it.

Manage skills

agents skills list                       # installed skills + sync status
agents skills add gh:you/skills --agents claude,codex
agents skills add                        # pick from ~/.agents/skills/ interactively
agents skills view api-conventions       # metadata: name, description, rules count

Find more with agents search and install from GitHub with agents install gh:owner/repo.

Related

• Plugins — bundle skills, hooks, and permissions into one distributable package.
• MCP — give a skill live tools (databases, APIs) to work with.
• Config layers — how skills merge across project, user, and system.