---
title: Skills Manager
description: SKILL.md metadata, per-session activation, and context injection.
---

import LinkToSource from '@/components/LinkToSource.astro';
import { Aside, LinkCard, FileTree } from '@astrojs/starlight/components';

Header: <LinkToSource relativePath="components/claw_modules/claw_skill/include/claw_skill.h" />

`claw_skill` manages user-visible **Skills** in the model context:

- On disk: a set of `skills/<skill_id>/SKILL.md` files whose JSON frontmatter describes the Skill id, summary, manage mode, and capability groups.
- Per session: a set of “currently activated” Skill ids persisted under the session state directory.
- After activation, the model sees fuller Skill docs and can use `cap_skill` tools to activate/deactivate Skills.

<LinkCard title="How Skills work" href="@lang/reference-project/skills" description="Skill mechanics and manual or Agent-driven edits to Skills" />

## Init configuration

Main fields of `claw_skill_config_t`:

- `skills_root_dir`: root for the Skills tree (demo: `/fatfs/skills`).
- `session_state_root_dir`: where per-session activation state files live (demo shares the same root as session history).
- `max_file_bytes`: maximum bytes read from a single Skill document file (guards against huge files filling the context).

## Wiring into claw_core

`claw_skill` plugs into `claw_core` as two **context providers**:

1. **`claw_skill_skills_list_provider`**: each request renders `name` and `description` from every `SKILL.md` frontmatter into the system prompt so the model knows what Skills exist.
2. **`claw_skill_active_skill_docs_provider`**: concatenates `SKILL.md` bodies for Skills activated in the current session.

Activating a Skill therefore adds its `SKILL.md` body to the next request; tool descriptions and behavioral contracts come from that document.

## Activation state

Activation is **isolated per session**:

- Session A activating `weather` does not affect session B.
- State is persisted as files under `session_state_root_dir` and survives reboot.
- The model can toggle via `cap_skill`’s `activate_skill` / `deactivate_skill`, or you can use the Console `skill` commands.

<Aside type="caution">
  Console `--session` must match the id from the current `session` command, otherwise it looks like “activated but not in context”.
</Aside>

## Where runtime Skills come from

The `/fatfs/skills` tree read at runtime is assembled in the build staging image under `build/fatfs_image/skills`:

1. **`application/edge_agent/fatfs_image/skills/`**: app-bundled factory Skills laid out as `skills/<skill_id>/SKILL.md`, copied into the build staging image.
2. **Component Skills**: each `cap_*` / `lua_module_*` / `lua_driver_*` component may ship `skills/<skill_id>/SKILL.md`; `components/common/skill_builder` syncs them into `build/fatfs_image/skills/` before packaging.

Note: `application/edge_agent/fatfs_image/` is source input. `application/edge_agent/build/fatfs_image/` is generated staging output and is recreated during the build.

## User-facing interaction

<LinkCard title="Console usage" href="@lang/reference-project/console-usage" description="Using the skill command in the Console" />
<LinkCard title="cap_skill" href="@lang/reference-cap/cap-skill" description="activate_skill / deactivate_skill vs model-visible Skills" />
