Skills & Agents

Skills

A skill is a reusable LLM instruction bundle with metadata. Skills package a prompt template, variable declarations, and tool permissions into a single unit that can be activated on demand.

The SkillsV2Registry (in crates/clawft-core/src/agent/skills_v2.rs, ~1,430 lines) manages the skill lifecycle: YAML frontmatter parsing, three-level discovery, security validation, hot-reload, and auto-generation.

SKILL.md Format

The preferred format is a single SKILL.md file with YAML frontmatter and a markdown body:

---
name: research
description: Deep research on a topic
version: 1.0.0
variables:
  - topic
  - depth
allowed-tools:
  - WebSearch
  - Read
  - Grep
user-invocable: true
argument-hint: Search query or topic
---

You are a research assistant. Given a {{topic}}, perform deep research
at the requested {{depth}} level. Use WebSearch for current information
and Read/Grep for local files.

Frontmatter Fields

Both hyphenated (allowed-tools) and underscored (allowed_tools) field names are accepted.

Comparison with Hermes: Hermes uses a similar skill-as-markdown pattern but lacks hot-reload, auto-generation, and the three-level priority chain. clawft's SKILL.md format is wire-compatible with Hermes skills -- the frontmatter fields map directly.

Legacy Format

The older format uses skill.json + prompt.md:

my-skill/
  skill.json
  prompt.md

When both SKILL.md and skill.json exist, SKILL.md takes precedence.

Discovery Chain

Skills are loaded from three levels (highest priority first):

1. Workspace skills -- .clawft/skills/ in the project root (highest priority)
2. User skills -- ~/.clawft/skills/ in the user's home directory
3. Built-in skills -- compiled into the binary (lowest priority)

When the same skill name appears at multiple levels, the higher-priority source wins. This allows workspace-specific overrides of user or built-in skills without modifying the originals.

CLI Commands

weft skills list                        # list all discovered skills
weft skills show research               # show skill details
weft skills install /path/to/my-skill   # install to ~/.clawft/skills/
weft skills remove my-skill             # remove a user-installed skill

Interactive Slash Commands

In a weft agent session:

/skills              -- list available skills
/use research        -- activate a skill
/use                 -- deactivate the current skill
/status              -- show current agent, model, and active skill

Hot-Reload

The SkillWatcher (~555 lines) monitors skill directories for filesystem changes using platform-native file watchers. Modified skills are atomically swapped so in-flight invocations complete with the old definition while new invocations use the updated version. No restart required.

The watcher covers all three discovery levels and handles:

• New skill files appearing in a watched directory
• Modifications to existing SKILL.md files
• Deletion of skill files (skill is removed from the registry)

Skill Auto-Generation

When skill_autogen.enabled = true, the SkillAutogen module (~638 lines) detects repeated tool call patterns during agent operation. The flow:

1. The module tracks sequences of tool calls across messages.
2. When the same tool-call pattern appears at least threshold times (default: 3), the module generates a skill candidate.
3. The candidate is written to ~/.clawft/skills/ with status: pending in the frontmatter.
4. The user must approve the skill before it becomes active.

Auto-generated skills have minimal permissions by default:

• No shell access
• No network access
• Filesystem limited to the workspace directory

Configuration:

{
  "skills": {
    "auto_create": true,
    "auto_create_threshold": 3
  }
}

MCP Exposure

Skills are automatically exposed as MCP tools via SkillToolProvider. Any MCP client connected to weft mcp-server can invoke skills as tools.

Security Validation

Skills undergo multiple security checks before loading:

• SEC-SKILL-01: YAML nesting depth limited to 10 levels (prevents deeply nested YAML bombs)
• SEC-SKILL-02: Directory names validated against path traversal
• SEC-SKILL-03: When skill and agent both declare allowed_tools, the effective list is their intersection
• SEC-SKILL-05: Workspace skills not loaded by default; pass --trust-project-skills to enable
• SEC-SKILL-06: Prompt injection tokens (<system>, <|im_start|>, <<SYS>>, etc.) are stripped from skill instructions
• SEC-SKILL-07: SKILL.md files limited to 50 KB (MAX_SKILL_MD_SIZE)

Agents

An agent is a predefined persona that bundles a system prompt, model selection, tool constraints, and skill activations into a named definition.

Agent Definition Format

Agents are YAML or JSON files in a named directory:

# ~/.clawft/agents/researcher/agent.yaml
name: researcher
description: Deep research agent with web access
model: anthropic/claude-sonnet-4-20250514
system_prompt: |
  You are a meticulous research assistant. Always cite sources
  and verify claims across multiple references.
skills:
  - research
allowed_tools:
  - WebSearch
  - Read
  - Grep
max_turns: 20
variables:
  output_format: markdown
  citation_style: APA

Agent Fields

Discovery Chain

Same 3-level priority as skills:

1. Workspace -- .clawft/agents/
2. User -- ~/.clawft/agents/
3. Builtin -- compiled into the binary

Template Variables

Agent prompts and skill instructions support substitution:

Missing variables are replaced with an empty string.

CLI Commands

weft agents list                  # list all agents
weft agents show researcher       # show agent details
weft agents use researcher        # select an agent

In interactive mode:

/agent researcher    -- switch to an agent
/agent               -- show the current agent

Security

• Directory names validated against path traversal
• Model strings validated against shell metacharacters
• Agent files limited to 10 KB
• Tool allowlists intersected between agent and skill

Per-Agent Workspaces

Each agent can have an isolated workspace at ~/.clawft/agents/<id>/:

Configuration merges in three levels: global -> agent -> workspace.

Inter-Agent Communication

Agents can exchange messages through the AgentBus:

• InterAgentMessage -- Typed message with from_agent, to_agent, task, and payload
• Per-agent inboxes -- Each agent has a bounded channel for incoming messages
• SwarmCoordinator -- Provides dispatch_subtask (one agent) and broadcast_task (all agents)
• TTL enforcement -- Messages carry time-to-live; expired messages are dropped

Multi-Agent Routing

When multiple agents are defined, inbound messages are dispatched via a routing table with first-match-wins semantics. Routes can match on keywords, channels, or sender patterns. A catch-all route handles unmatched messages.

Autonomous Skill Creation

Agents can detect repeated prompt patterns and auto-generate skills:

1. Pattern repeats beyond threshold (default 3)
2. Agent generates SKILL.md with inferred variables
3. Skill installed in pending state
4. User approval required before activation

Disabled by default:

{
  "skills": {
    "auto_create": true,
    "auto_create_threshold": 3
  }
}