Skip to main content
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:
1

Gate

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.
2

Score

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.
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.
3

Budget

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.
4

Attenuate

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

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: 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:
To verify that a skill was picked up correctly:
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.