> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Skill Authoring (@skill)

> The agent writes and evolves its own skills from what it learns — create, update, view, usage analytics and shareable packs.

The **`@skill`** tool lets the agent **grow its own capabilities**: when it learns a reusable procedure, a project convention or a workflow you repeat, it writes a skill that **auto-activates on its triggers** in this and every future session. It's hermes-agent's living skill layer, native to ChatCLI's skill format.

<Info>
  **`@memory` vs `@skill`**: `@memory` stores **facts** ("the user prefers tabs"); `@skill` stores a **reusable procedure/knowledge with triggers** ("how to deploy this project"). Short fact → memory; "how to do X" → skill. And to author skills **from documentation**, attach the corpus as a [knowledge base](/context/knowledge-base): the agent researches with `@knowledge` and writes the skill with `@skill`.
</Info>

***

## Subcommands

```text theme={"system"}
<tool_call name="@skill" args='{"cmd":"create","args":{
  "name":"deploy-acme-api",
  "description":"How to deploy the Acme API. Use when asked to deploy Acme.",
  "triggers":["deploy acme","ship the api"],
  "content":"# Deploy\n1. make test\n2. git tag vX.Y.Z\n...",
  "allowed_tools":["@coder","Bash"]
}}' />
```

| Subcommand | Purpose |
| - | - |
| `create {name, description, content, triggers?, allowed_tools?}` | create a new skill |
| `update {name, ...}` | evolve an existing skill (no duplicates) |
| `list` | list saved skills |
| `show {name}` | print a skill's content |
| `remove {name}` | delete a skill |
| `stats` | **usage analytics** (which skills earn their keep) |
| `export {names?, out}` | bundle skills into a shareable JSON pack |
| `import {path}` | install skills from a pack |

`name` is a validated kebab-case slug (no path traversal). `create` won't clobber; `update` requires the skill to exist.

***

## Evolution loop

```text theme={"system"}
agent learns → @skill create/update → writes ~/.chatcli/skills/<name>/SKILL.md
                                        │
                                        ▼
            loader discovers next turn → auto-activates on triggers
```

The bundled **`skill-authoring`** skill guides the agent on *when* and *how* to author (capture a repeated workflow, good descriptions/triggers, evolve instead of duplicate).

**Generalization.** A run is about an entity — one team, one service, one repository — and a skill learned from it must be about the competence. The self-evolve prompt asks for `team-match-info`, not `flamengo-match-info`, with the entity as an input in the body and generic words in the triggers. And before a new skill is written, its keywords (name, description, triggers) are compared with every installed skill's; a candidate that shares at least half of its keywords with an existing skill (three words or more) is folded into that skill as an evolution instead of authored beside it. The notice says so: `folded into an existing skill: corinthians-match-info → team-match-info`.

***

## Self-evolution

Skills used to appear only when the model remembered to call `@skill` — so you had to *ask*. Now they author and evolve themselves, **riding the same memory-extraction pass** (no extra LLM call): each turn the prompt carries only a compact skill index card; when the pass detects a new reusable procedure it **authors** the skill, and when an insight improves an existing one it **reuses that exact name** and pulls only that skill's body on demand for an **additive merge** (preserving what already works).

Safety and reversibility:

* Every engine write is tracked by a content-hash manifest (like the built-in seed).
* A skill **you** authored by hand (or edited) is **backed up once** before the first modification — `@skill restore <name>` undoes it and restores your original.
* A backup failure downgrades to a suggestion; it never overwrites without a safety net.

Controlled by `CHATCLI_SELFEVOLVE_MODE`:

| Value | Behavior |
| - | - |
| `auto` (default) | Detects and authors/evolves skills automatically (edit-safe, reversible). |
| `suggest` | Detects and **suggests** in one line; never writes to disk. |
| `off` | Disables detection (memory keeps learning normally). |

Observability under **`/config selfevolve`** (mode + how many skills the engine authored vs. the total); per-skill activation analytics in `@skill stats`.

***

## Usage analytics

`@skill stats` shows the activation ranking (most used first, with `last used`) and flags authored skills that **never activated** — candidates to evolve or remove. Data lives in `~/.chatcli/skill-usage.json`, written asynchronously by the manager on each activation (`FindAutoActivatedSkills`), never slowing a turn.

***

## Shareable packs

```text theme={"system"}
@skill export {names:["deploy-acme-api"], out:"team-pack.json"}   # bundle
@skill import {path:"team-pack.json"}                              # install
```

The pack is a JSON carrying each raw `SKILL.md` (lossless round-trip). On import, existing skills are **skipped** unless `overwrite:true`. Useful for moving skills across machines and teams.

***

## Safety

* Slug-validated name → no writes outside the skills directory.
* Never store secrets/tokens in a skill (that's an environment/credential concern).
* [Builtin skills](/tools/builtin-skills) seeding **never** clobbers agent-authored skills.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.