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)
`allowedPaths`	`string[]`	Additional directories accessible beyond project root. Supports `~` for home directory.
`timeout`	`number`	Command timeout in milliseconds (default: 120000)

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. Use skills: trusted for sandboxed or yolo-style agents. It keeps auto skill loading, but treats loaded skills as trusted to use the tools already configured on the agent. It does not enable new tools or new bash commands.

skills: trusted

Define a skill explicitly when it is core to the agent. Explicit skills are preloaded before the task starts, so the agent does not need to infer the trigger from the user instruction:

skills: [linkedin]

skills:
  linkedin:
    allow: [agent-browser]

allow entries are user-authored command-family grants. AgentUse does not infer or validate command needs from skill text. For example, allow: [agent-browser] grants the agent-browser * command family. Use allow: ["*"] only for trusted skills that may use all tools already configured for the agent. 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.

​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

​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

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