> ## 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](/features/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).

***

## 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](/features/builtin-skills) seeding **never** clobbers agent-authored skills.