Skills

UGENT has full compatibility with Claude Code skill files (.claude/skills/ convention). Skills are Markdown files with YAML frontmatter that define reusable agent behaviors.

Enabling Skills

[skills]
enabled = true
root_dir = "~/.ugent/skills"
max_body_bytes = 40000
max_listed = 200

Skill File Format

Each skill is a Markdown file with frontmatter:

---
name: deep-research
description: Conducts comprehensive web research with multiple search rounds
argument-hint: "[topic]"
allowed-tools: web_search, web_fetch, delegate_task
agent: researcher
model: opus
effort: high
---

# Deep Research Skill

When invoked, conduct a multi-round research workflow:

1. Search for the topic using multiple search engines
2. Read and summarize the top results
3. Cross-reference claims across sources
4. Produce a well-cited report

Supported Frontmatter Fields

All 19 Agent Skills standard fields are supported:

Field	Description
name	Skill name (lowercase, hyphens, max 64 chars)
description	When to use this skill
arguments	Expected arguments
argument-hint	Usage hint shown to the model
allowed-tools	Tools the skill may use (space-separated or array)
disallowed-tools	Tools the skill must not use
agent	Preferred agent role
model	Preferred model name
effort	Effort level: low, medium, high, max
context	fork signals delegation to a sub-agent
shell	Shell execution settings
hooks	Lifecycle event hooks
paths	Glob patterns for context-sensitive activation
disable-model-invocation	Hide from agent listing
user-invocable	Show in user menu
general-purpose	General purpose flag
license	License info
compatibility	Compatibility notes
metadata	Custom metadata

Skill Body Processing

When a skill is loaded, the body passes through a 3-phase pipeline:

1. Variable Substitution

Replaces variables in the skill body:

• ${UGENT_SKILL_DIR} — path to the skill's directory
• ${UGENT_SESSION_ID} — current session ID
• $ARGUMENTS — all arguments passed to the skill
• $1, $2 — positional arguments
• $named_arg — named arguments

2. Shell Command Injection

Inline shell commands within skill bodies:

Current git branch: !`git branch --show-current`

System info:
```!
uname -a
rustc --version

Controlled by `shell_execution_enabled` in skills settings. Commands run in the skill directory with configurable timeout and output cap. Single-pass: output is never re-scanned.

### 3. Skills Firewall

Scans skill bodies for authority-grab attempts and injection patterns. When `block_malicious_skills` is enabled in `firewall.toml`, skills with Critical findings are refused at load time. Otherwise, suspicious content is wrapped in untrusted-boundary markers.

## Loading Skills

Skills are loaded via `load_skill()` or the `/skill` command:

/skill deep-research

Or from the agent's system prompt — the agent can invoke skills autonomously when the description matches the user's request.

## Visibility Control

```yaml
disable-model-invocation: true   # Hide from agent's skill listing
user-invocable false             # Hide from user menu

Tool Name Mapping

Claude Code tool names are automatically mapped to UGENT equivalents:

Claude Code	UGENT
Bash	bash
Read	read_file
Write	write_file
Glob	find_files
Grep	search_files

Model names (sonnet, opus, haiku) are mapped to configured provider targets. Effort strings (low through max) are mapped directly.

Paths Activation

paths:
  - "src/**/*.rs"
  - "Cargo.toml"

When set, the skill is only active when the workspace matches the glob patterns. Useful for project-specific skills.

Context Fork

context: fork

Signals that the skill should execute in a delegated sub-agent context via delegate_task rather than direct injection into the current conversation.

Disable Flag

Skip loading all skills for a session:

ugent --disable-skills

No skill index prompt is injected into the system prompt.

Skill Overrides

Per-skill enable/disable without removing files:

[skills.skill_overrides]
"deep-research" = { enabled = true, force_body = false }
"deprecated-skill" = { enabled = false }