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.
---
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
---
FieldPurpose
keywordsWord or phrase matches. Exact word match scores higher than substring.
patternsRegex patterns. Each match adds significant weight — use for intent-specific phrases.
tagsShort labels for broad domain matching (e.g. blockchain, cli).
exclude_keywordsVeto list — if any appear in the message, the skill scores zero regardless of other matches.
max_context_tokensToken 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.
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

Trust LevelSourceTool Access
TrustedUser-placed in ~/.ironclaw/skills/ or workspace skills/All tools available to the agent
InstalledDownloaded from ClawHub registry via skill_installRead-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:
DirectoryTrustDescription
~/.ironclaw/skills/TrustedUser’s global skills, available in all sessions
<workspace>/skills/TrustedPer-workspace skills, activated in that workspace’s context
~/.ironclaw/installed_skills/InstalledRegistry-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: 
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. 
# Enable auto-discovery (default: true)
SKILLS_AUTO_DISCOVER=true

# Max tokens injected per turn across all active skills
SKILLS_MAX_TOKENS=4000