> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ironclaw.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Skills
> Prompt extensions that activate based on context
Skills are markdown files that contain domain-specific instructions. When a skill activates, its markdown body is injected into the LLM context — giving the agent specialized knowledge and behavior without retraining.
IronClaw can search and install skills from the ClawHub registry, a community-driven repository of pre-built skills covering various domains and use cases.
***
## What Skills Do
A skill is a self-contained expertise module. It defines:
* **When to activate** — patterns, keywords, and regex that match incoming messages
* **What to inject** — a markdown body with instructions, examples, and domain knowledge
* **What tools to require** — binaries, environment variables, and configuration needed
* **How much context to use** — a token budget cap per activation
Skills are evaluated on every turn. The agent selects the most relevant skills that fit within the prompt budget and injects them before the LLM reasons about the request.
***
## Activation Pipeline
Skills pass through four stages before injection:
Check that all prerequisites are met: required binaries exist on `PATH`, required environment variables are set, required configuration is present. Skills that fail gating are skipped entirely — they never score or consume budget.
Each gated skill is scored against the current message using a deterministic algorithm: keyword matches, tag overlaps, and regex pattern matches. Higher scores indicate stronger relevance.
Scoring is fully deterministic — no LLM involved. A skill must declare its activation criteria in the frontmatter so the scorer knows what to match.
A skill without an `activation` block scores zero on every message and is never injected.
```yaml theme={null}
---
name: my-skill
version: 0.1.0
description: Short description shown in skill list
activation:
keywords:
- deploy
- rollback
patterns:
- "deploy to.*production"
- "rollback.*release"
tags:
- devops
exclude_keywords:
- dry-run
max_context_tokens: 2000
---
```
| Field | Purpose |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `keywords` | Word or phrase matches. Exact word match scores higher than substring. |
| `patterns` | Regex patterns. Each match adds significant weight — use for intent-specific phrases. |
| `tags` | Short labels for broad domain matching (e.g. `blockchain`, `cli`). |
| `exclude_keywords` | Veto list — if any appear in the message, the skill scores zero regardless of other matches. |
| `max_context_tokens` | Token budget this skill may consume per turn. Omitting it leaves the skill with a 2000-token budget, effectively excluding it. |
If a skill appears in `ironclaw skills list` but the agent doesn't use it, the most common cause is a missing or empty `activation` block.
Skills are sorted by score descending. Starting from the highest-scoring skill, each is selected until the `SKILLS_MAX_TOKENS` budget is exhausted. Lower-scoring skills that don't fit are dropped for this turn.
Trust-based tool ceiling is applied. Installed skills (from ClawHub) lose access to dangerous tools regardless of what the skill requests. Trusted skills retain full tool access. See Trust Levels below.
***
## Trust Levels
| Trust Level | Source | Tool Access |
| ------------- | ----------------------------------------------------------- | ------------------------------------------------------- |
| **Trusted** | User-placed in `~/.ironclaw/skills/` or workspace `skills/` | All tools available to the agent |
| **Installed** | Downloaded from ClawHub registry via `skill_install` | Read-only tools only — no shell, no file write, no HTTP |
Never place a skill file in the trusted directories unless you have reviewed its contents. A skill in `~/.ironclaw/skills/` has the same tool access as you do.
***
## Skill Directories
IronClaw discovers skills from three locations, checked in order:
| Directory | Trust | Description |
| ------------------------------- | --------- | ----------------------------------------------------------- |
| `~/.ironclaw/skills/` | Trusted | User's global skills, available in all sessions |
| `/skills/` | Trusted | Per-workspace skills, activated in that workspace's context |
| `~/.ironclaw/installed_skills/` | Installed | Registry-installed skills from ClawHub |
Skills in trusted directories are loaded as-is. Skills in `installed_skills/` have their tool access capped by the attenuation layer regardless of what they declare.
Each skill lives in its own subdirectory named after the skill:
```
~/.ironclaw/skills/
└── my-skill/
└── SKILL.md
```
To verify that a skill was picked up correctly:
```bash theme={null}
ironclaw skills list
```
A correctly installed skill appears with its name, version, and trust level. If a skill is missing from the list, check the directory structure and SKILL.md validity.
***
## Auto-Discovery
When `SKILLS_AUTO_DISCOVER=true` (the default), IronClaw scans all skill directories at startup and indexes all valid SKILL.md files. New skills added while the agent is running are picked up on the next restart.
```bash theme={null}
# Enable auto-discovery (default: true)
SKILLS_AUTO_DISCOVER=true
# Max tokens injected per turn across all active skills
SKILLS_MAX_TOKENS=4000
```