Skills

Skills are based on the Agent Skills open standard, originally developed by Anthropic. AgentUse implements this standard to enable portable, reusable instruction modules across different AI agent platforms.

What Are Skills?

Skills are reusable instruction modules that agents can load on-demand. Think of them as specialized knowledge packages - each skill contains detailed guidance for a specific type of task. Unlike sub-agents that execute independently, skills provide instructions that the agent follows directly. This makes skills ideal for:

Specialized workflows: Code review checklists, deployment procedures, data analysis patterns
Domain expertise: Writing guidelines, compliance requirements, best practices
Reusable templates: Project scaffolding, documentation formats, testing strategies
Cross-agent knowledge: Share instructions across multiple agents without duplication

Quick Start

Create a skill directory:

mkdir -p .agentuse/skills/code-review

Add a SKILL.md file with YAML frontmatter and markdown content:

---
name: code-review
description: Review code for quality, security, and maintainability.
allowed-tools: Read Bash(git:*)
---

Then add your skill instructions in markdown below the frontmatter.

The skill is automatically available to your agents!

Skill Locations

Skills are discovered from these directories (in priority order):

Location	Scope	Purpose
`.agentuse/skills/`	Project	Project-specific skills
`~/.agentuse/skills/`	User	Personal skills across projects
`.claude/skills/`	Project	Claude ecosystem compatibility
`~/.claude/skills/`	User	Claude ecosystem compatibility

If duplicate skill names exist, the first discovered skill takes precedence.

For AI Coding Assistants

Install the assistant-facing AgentUse skill so Claude Code, Codex, Cursor, and other assistants can drive AgentUse workflows:

npx skills add agentuse/agentuse

The stub redirects to agentuse skills get core, keeping instructions aligned with the installed CLI version.

Skill Structure

Each skill lives in its own directory with a SKILL.md file:

.agentuse/skills/
└── my-skill/           # Directory name must match skill name
    └── SKILL.md        # Skill definition file

SKILL.md Format

Skills use markdown with YAML frontmatter:

---
name: my-skill
description: What this skill does
allowed-tools: Read Write
license: MIT
compatibility: ">=0.3.0"
metadata:
  author: your-name
  version: "1.0.0"
---

Below the frontmatter, add your skill instructions in markdown.

Frontmatter Fields

Field	Required	Description
`name`	Yes	Skill identifier (1-64 chars, lowercase, hyphens allowed)
`description`	Yes	What the skill does and when to use it (max 1024 chars)
`allowed-tools`	No	Space-delimited list of required tools
`license`	No	Skill license (e.g., MIT, Apache-2.0)
`compatibility`	No	Version requirements or environment notes
`metadata`	No	Custom key-value metadata

Name Requirements

Skill names must:

Be 1-64 characters long
Use only lowercase letters, numbers, and hyphens
Not start or end with a hyphen
Not contain consecutive hyphens (--)
Match the parent directory name

Valid names: code-review, seo-analyzer, db-migration Invalid names: Code-Review, my_skill, -invalid, too--many

Allowed Tools

The allowed-tools field documents which tools your skill needs. It’s a space-separated list of tool names for documentation purposes.

allowed-tools: Read Write Bash(git:*) mcp__github

Skills use whatever tools the agent has configured. The allowed-tools field documents dependencies and provides validation warnings for builtin tools.

Validation

Only builtin tools are validated against the agent’s configuration:

Read, Write, Edit - checked against tools.filesystem
Bash, Bash(command:*) - checked against tools.bash.commands

Bash Tool Configuration

Field	Type	Description
`commands`	`string[]`	Allowlist of command patterns (supports `*` wildcard)
`gated`	`string[]`	Command patterns that require an approved per-action lease
`allowedPaths`	`string[]`	Additional directories accessible beyond project root. Supports `~` for home directory.
`timeout`	`string`	Command timeout as a suffixed duration such as `"30s"`, `"2m"`, or `"500ms"`; bare numbers are rejected

Other tool names (like MCP tools) are accepted but not validated - they serve as documentation only. If validation fails:

A warning is logged to the console
The LLM sees a warning message
The skill still loads (graceful degradation)

Agent Tool Configuration

Skills run with the agent’s tools. For a skill to use the tools it documents, the agent must have them configured. Agents use skills: auto by default, even when the field is omitted. This makes installed skills discoverable and lets the model load relevant skills on demand. By default a skill is discovered but granted nothing: to run a command a skill documents, it must be in tools.bash.commands, or you must trust the skill. Trusting a skill grants it the bash commands it declares in its SKILL.md allowed-tools, so you do not have to re-list them. Trust per skill:

skills:
  linkedin: trusted

or trust every discovered skill (the blunt shortcut, use deliberately):

skills: trusted

Trusting a skill is a real trust decision, the same class as installing an editor extension: you are granting a skill you may not have written the commands it asks for. Trust only grants (adds the commands so they can run); it never invents gates. Gating stays your explicit call:

To require approval for a subset of what a skill grants, list that pattern in tools.bash.gated. For example, a skill declares Bash(birdc:*), so trusting it grants birdc *. If you want birdc reply * behind approval, add it to tools.bash.gated. Gated-wins precedence gates birdc reply while birdc read still auto-runs.

skills:
  x-personal: trusted        # grants birdc *
tools:
  bash:
    gated:
      - "birdc reply *"       # ...but reply needs your approval

agentuse doctor flags granted commands that look irreversible, so you know what to consider gating.

Preloading skills

List a skill to preload it: its instructions are injected before the task starts, so the agent does not have to infer the trigger from the user instruction. Use this when a skill is core to the agent’s job.

skills: [linkedin, x-personal]

Listing a skill preloads it; it never hides the others. Discovery stays on, so every unlisted skill is still loadable on demand. Listing is “these are the skills I use,” not “forbid all others.”

This reverses pre-0.16.0 behavior, where skills: [x] was an allowlist that silently hid every other skill. Restricting is now an explicit, deliberate act (see below).

To pin the agent to a closed set (only the listed skills are visible, everything else is hidden), opt in explicitly with auto: false:

skills:
  linkedin:         # bare = include, no special grant
  auto: false       # ...and hide every other discovered skill

Because hiding skills is the rarer, higher-consequence choice, it is loud (auto: false) rather than a silent side effect of listing. Per-skill map values may be empty or trusted (including the object form { trusted: true }). The pre-0.16 allow key has been removed. Grant individual commands through tools.bash.commands instead.

Skill config forms

Config	Discovery	Preloaded	Trusted
omitted / `skills: auto`	all	none	none
`skills: [linkedin]`	all	linkedin	none
`skills: { linkedin: trusted }`	all	linkedin	linkedin
`skills: { linkedin:, auto: false }`	only linkedin	linkedin	none
`skills: trusted`	all	none	all

To inspect a skill’s grants:

agentuse doctor path/to/agent.agentuse
agentuse doctor path/to/agent.agentuse --last-run

Doctor also shows command-looking snippets mentioned by the skill. This is advisory: it extracts command names from shell code blocks, inline command snippets, allowed-tools, pipes, and command substitutions. AgentUse does not treat the output as a permission manifest. Add --last-run when the agent has already failed or behaved unexpectedly. Doctor will inspect the latest recorded session for that agent and report actual blocked bash commands from runtime, which is more accurate than static skill-doc extraction.

Example

Skill (code-review/SKILL.md):

---
name: code-review
description: Review code for quality and security.
allowed-tools: Read Bash(git:*) mcp__github
---

Agent (reviewer.agentuse):

---
model: anthropic:claude-sonnet-5
tools:
  filesystem:
    - path: ${root}             # Grants access to all files under project root
      permissions: [read]
  bash:
    commands:
      - "git *"
    allowedPaths:               # Optional: directories beyond projectRoot
      - ~/workspace/other-repo
      - /tmp
mcpServers:
  github:
    command: npx
    args: ["-y", "@anthropic/mcp-server-github"]
    env:
      GITHUB_TOKEN: ${env:GITHUB_TOKEN}
---

You are a code reviewer. Use the code-review skill to analyze changes.

The skill documents needing Read, Bash(git:*), and mcp__github. The agent provides all three through its tools and mcpServers configuration.

If a skill’s instructions reference tools that the agent hasn’t configured, those operations will fail at runtime.

How Agents Use Skills

Skills are exposed to agents via a special skill tool. The agent sees available skills listed in XML format and can load them on demand. When the agent loads a skill, it receives:

The skill name and base directory
Any tool warnings (if required tools are missing)
The full markdown content with instructions

Skill File Reader

After loading a skill, agents can read additional files from the skill directory using the skill_read tool. This is useful for accessing:

Helper scripts bundled with the skill
Data files or templates
Configuration examples

skill_read(skill: "code-review", path: "templates/pr-template.md")

The skill must be loaded first before reading files from its directory.

Skill Directory Variables

When a skill is loaded, AgentUse substitutes these placeholders in the skill’s content with the skill’s absolute directory path. Use them so bundled scripts and assets resolve regardless of where the skill is installed:

Placeholder	Purpose
`${skillDir}`	Legacy AgentUse placeholder
`${SKILL_DIR}`	Cross-agent convention
`${CLAUDE_SKILL_DIR}`	Claude ecosystem compatibility

Run `bash ${SKILL_DIR}/scripts/setup.sh` before generating output.

Only the curly-brace form is replaced. Literal $SKILL_DIR (no braces) is left untouched so runtime shell expansion still works inside scripts.

Example Skills

Git Commit Guidelines

Frontmatter:

---
name: commit-guidelines
description: Create well-structured git commits following conventional commit format.
allowed-tools: Bash(git:*)
---

Content: Include guidance on conventional commit format, commit types (feat, fix, docs, refactor, test, chore), and best practices like keeping subject lines under 72 characters.

API Documentation Writer

Frontmatter:

---
name: api-docs
description: Generate comprehensive API documentation from code.
allowed-tools: Read
---

Content: Include templates for endpoint documentation (HTTP method, path, parameters, response format, error codes) and function documentation (purpose, parameters, return values, examples).

Database Migration Checker

Frontmatter:

---
name: migration-check
description: Validate database migrations for safety before production.
allowed-tools: Read Bash(psql:*)
---

Content: Include checklists for backwards compatibility, data safety, performance considerations, and rollback planning.

Skills vs Sub-agents

Aspect	Skills	Sub-agents
Execution	Instructions followed by parent agent	Runs as separate agent
Context	Shared with parent agent	Isolated context
Tools	Uses parent agent’s tools (no own config)	Has own tool configuration
Tool declaration	`allowed-tools` for documentation/validation	Full `tools` config in agent file
Output	Integrated into parent’s response	Returns result to parent
Use case	Guidelines, procedures, knowledge	Independent tasks

Use skills for knowledge and procedures. Use sub-agents for independent task execution.

Getting Started

Building

Running

Reference

Skills

Skills

What Are Skills?

Quick Start

Skill Locations

For AI Coding Assistants

Skill Structure

SKILL.md Format

Frontmatter Fields

Name Requirements

Allowed Tools

Validation

Bash Tool Configuration

Agent Tool Configuration

Preloading skills

Skill config forms

Example

How Agents Use Skills

Skill File Reader

Skill Directory Variables

Example Skills

Git Commit Guidelines

API Documentation Writer

Database Migration Checker

Skills vs Sub-agents

​Skills

​What Are Skills?

​Quick Start

​Skill Locations

​For AI Coding Assistants

​Skill Structure

​SKILL.md Format

​Frontmatter Fields

​Name Requirements

​Allowed Tools

​Validation

​Bash Tool Configuration

​Agent Tool Configuration

​Preloading skills

​Skill config forms

​Example

​How Agents Use Skills

​Skill File Reader

​Skill Directory Variables

​Example Skills

​Git Commit Guidelines

​API Documentation Writer

​Database Migration Checker

​Skills vs Sub-agents

Skills

What Are Skills?

Quick Start

Skill Locations

For AI Coding Assistants

Skill Structure

SKILL.md Format

Frontmatter Fields

Name Requirements

Allowed Tools

Validation

Bash Tool Configuration

Agent Tool Configuration

Preloading skills

Skill config forms

Example

How Agents Use Skills

Skill File Reader

Skill Directory Variables

Example Skills

Git Commit Guidelines

API Documentation Writer

Database Migration Checker

Skills vs Sub-agents