> ## Documentation Index > Fetch the complete documentation index at: https://docs.agentuse.io/llms.txt > Use this file to discover all available pages before exploring further. # Skills # Skills Skills are based on the [Agent Skills](https://agentskills.io) 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 1. Create a skill directory: ```bash theme={"system"} mkdir -p .agentuse/skills/code-review ``` 2. Add a `SKILL.md` file with YAML frontmatter and markdown content: ```yaml theme={"system"} --- 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. 3. 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: ```bash theme={"system"} 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: ```yaml theme={"system"} --- 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**. ```yaml theme={"system"} 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. ```yaml theme={"system"} 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: ```yaml theme={"system"} skills: [linkedin] ``` ```yaml theme={"system"} 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: ```bash theme={"system"} 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`): ```yaml theme={"system"} --- name: code-review description: Review code for quality and security. allowed-tools: Read Bash(git:*) mcp__github --- ``` **Agent** (`reviewer.agentuse`): ```yaml theme={"system"} --- 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 | ```markdown theme={"system"} 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:** ```yaml theme={"system"} --- 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:** ```yaml theme={"system"} --- 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:** ```yaml theme={"system"} --- 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.