---
title: "Agent Skills"
source: https://docs.autohand.ai/working-with-autohand-code/agent-skills
---

# Agent Skills

> Create, manage, and share Skills to extend Autohand's AI capabilities with specialized workflows and domain expertise.

## What are Agent Skills?

Agent Skills are modular instruction packages that extend Autohand's AI agent with specialized workflows and domain expertise. Each Skill consists of a `SKILL.md` file containing instructions that Autohand reads when relevant, plus optional supporting files like scripts and templates.

**How Skills are invoked:** Skills are model-invoked. Autohand autonomously decides when to use them based on your request and the Skill's description. This differs from slash commands, which you explicitly type to trigger.

**Benefits:**

-   Extend Autohand's capabilities for your specific workflows
-   Share expertise across your team via git
-   Reduce repetitive prompting
-   Compose multiple Skills for complex tasks

## Quick start

### List available Skills

``` bash
# In Autohand REPL
/skills
```

### Use a Skill

``` bash
/skills use changelog-generator
```

### Create a new Skill

``` bash
/skills new
```

### Auto-generate project Skills

``` bash
autohand --auto-skill
```

## Skill locations

Skills are discovered from multiple locations. Later sources take precedence:

| Location | Source | Description |
|---|---|---|
| ~/.codex/skills/**/SKILL.md | codex-user | User-level Codex skills (recursive) |
| ~/.claude/skills/*/SKILL.md | claude-user | User-level Claude skills (one level) |
| ~/.autohand/skills/**/SKILL.md | autohand-user | User-level Autohand skills (recursive) |
| <project>/.claude/skills/*/SKILL.md | claude-project | Project-level Claude skills |
| <project>/.autohand/skills/**/SKILL.md | autohand-project | Project-level Autohand skills (recursive) |

### Personal Skills

Personal Skills are available across all your projects. Store them in `~/.autohand/skills/`:

``` bash
mkdir -p ~/.autohand/skills/my-skill-name
```

### Project Skills

Project Skills are shared with your team. Store them in `.autohand/skills/` within your project:

``` bash
mkdir -p .autohand/skills/my-skill-name
```

Project Skills are checked into git and automatically available to team members.

Skills discovered from Codex or Claude locations are automatically copied to the corresponding Autohand location. Existing skills in Autohand locations are never overwritten.

## SKILL.md format

Skills use YAML frontmatter followed by markdown content:

``` yaml
---
name: my-skill-name
description: Brief description of the skill (max 1024 chars)
license: MIT
compatibility: Works with Node.js 18+
allowed-tools: read_file write_file run_command git_status
metadata:
  author: your-name
  version: "1.0.0"
---

# My Skill

Detailed instructions for the AI agent...
```

### Frontmatter fields

| Field | Required | Max Length | Description |
|---|---|---|---|
| name | Yes | 64 chars | Lowercase alphanumeric with hyphens only |
| description | Yes | 1024 chars | Brief description of when to use this skill |
| license | No | - | License identifier (MIT, Apache-2.0) |
| compatibility | No | 500 chars | Compatibility notes |
| allowed-tools | No | - | Space-delimited list of allowed tools |
| metadata | No | - | Additional key-value metadata |

## Auto-Skill generation

The `--auto-skill` flag analyzes your project and generates relevant skills based on the detected stack.

``` bash
autohand --auto-skill
```

### How it works

1.  **Project Analysis** - Scans for package.json, requirements.txt, Cargo.toml, go.mod
2.  **Detection** - Identifies languages, frameworks, and patterns
3.  **Platform Awareness** - Detects OS (macOS/Linux/Windows) for appropriate commands
4.  **LLM Generation** - Creates 3 tailored skills with examples and tool permissions
5.  **Save** - Writes skills to `<project>/.autohand/skills/`

### Detected patterns

| Category | Detected Items |
|---|---|
| Languages | TypeScript, JavaScript, Python, Rust, Go |
| Frameworks | React, Next.js, Vue, Angular, Svelte, Express, Fastify, NestJS, Flask, Django, FastAPI |
| Patterns | CLI tools, testing, monorepo, Docker, CI/CD, bundling, linting, database, API |
| Package Managers | npm, yarn, pnpm, bun, pip, cargo, go |
| Environment | Git repository, test framework, CI/CD pipelines |

### Example output

``` bash
$ autohand --auto-skill
Analyzing project structure...
Detected: typescript, javascript, react, nextjs, testing
Platform: darwin
Generating skills...
  ✓ nextjs-component-creator
    Tools: read_file, write_file, run_command
  ✓ typescript-test-generator
    Tools: read_file, write_file, run_command, search
  ✓ changelog-generator
    Tools: git_log, git_diff_range, read_file, write_file

✓ Generated 3 skills in .autohand/skills
  Use "/skills" to view and "/skills use <name>" to activate
```

## Available tools

Skills can specify which tools they need via the `allowed-tools` field.

### File operations

| Tool | Description |
|---|---|
| read_file | Read file contents |
| write_file | Write/create files |
| append_file | Append to existing files |
| apply_patch | Apply unified diff patches |
| search | Search for text patterns |
| search_replace | Search and replace in files |
| semantic_search | AI-powered semantic search |
| list_tree | List directory structure |
| multi_file_edit | Edit multiple files atomically |

### Git operations

| Tool | Description |
|---|---|
| git_status | Show working tree status |
| git_diff | Show uncommitted changes |
| git_diff_range | Show diff between commits |
| git_log | View commit history |
| git_add | Stage files |
| git_commit | Create commits |
| git_branch | List/create branches |
| git_switch | Switch branches |
| git_stash | Stash changes |
| git_merge | Merge branches |
| git_rebase | Rebase branches |
| git_push | Push changes |
| auto_commit | Auto-generate commit message |

### Commands and dependencies

| Tool | Description |
|---|---|
| run_command | Execute shell commands |
| custom_command | Run user-defined commands |
| add_dependency | Add project dependency |
| remove_dependency | Remove dependency |
| save_memory | Persist information |
| recall_memory | Retrieve saved information |
| plan | Create action plans |
| todo_write | Manage todo lists |

## Creating world-class Skills

Great skills share these characteristics:

### 1\. Clear purpose

State exactly what the skill does and when to use it:

``` markdown
# Changelog Generator

Transforms git commits into polished, user-friendly changelogs.

## When to use this Skill

- Preparing release notes
- Creating weekly update summaries
- Documenting changes for customers
```

### 2\. Concrete examples

Show exact prompts the user can try:

``` markdown
## How to use

```
Create a changelog from commits since v1.2.0
```

```
Generate release notes for the last 2 weeks
```

```
Summarize breaking changes since the last major version
```
```

### 3\. Actionable workflows

Provide numbered steps the agent should follow:

``` markdown
## Workflow

1. Identify the commit range (tags, dates, or branch comparison)
2. Fetch commit history with `git_log`
3. Categorize commits by type:
   - **Features**: New functionality
   - **Fixes**: Bug corrections
   - **Breaking**: Incompatible changes
4. Transform technical commit messages into user-friendly language
5. Format as clean markdown with appropriate headers
```

### 4\. Minimal tool permissions

Specify only the tools your skill needs:

``` yaml
allowed-tools: git_log git_diff_range read_file write_file
```

## Example Skills

### Changelog generator

``` yaml
---
name: changelog-generator
description: Creates user-facing changelogs from git commits. Use when preparing releases or documenting updates.
allowed-tools: git_log git_diff_range read_file write_file run_command
---

# Changelog Generator

Transforms git commits into polished, user-friendly changelogs.

## When to use this Skill

- Preparing release notes
- Creating weekly update summaries
- Documenting changes for customers
- Comparing changes between versions

## How to use

```
Create a changelog from commits since the last release
```

```
Generate release notes for version 2.5.0
```

## Workflow

1. Identify the commit range using tags, dates, or SHA
2. Fetch commit history with appropriate filtering
3. Categorize commits:
   - **Features** (`feat:`): New functionality
   - **Fixes** (`fix:`): Bug corrections
   - **Breaking** (`BREAKING CHANGE:`): Incompatible changes
4. Transform technical commits into user-friendly language
5. Format as clean markdown with headers and bullet points
```

### TypeScript refactoring guide

``` yaml
---
name: typescript-refactoring
description: Guides TypeScript refactoring with type-safe patterns and best practices.
allowed-tools: read_file write_file search apply_patch run_command
---

# TypeScript Refactoring Guide

Provides patterns and step-by-step guidance for safe TypeScript refactoring.

## When to use this Skill

- Extracting reusable functions or components
- Converting JavaScript to TypeScript
- Improving type safety
- Reducing code duplication

## Workflow

1. **Analyze Current Code**
   - Read the file(s) to understand existing patterns
   - Identify type issues with `tsc --noEmit`

2. **Plan Changes**
   - List all files that need modification
   - Identify breaking changes to exports

3. **Make Changes**
   - Apply changes incrementally
   - Run type checker after each change

4. **Verify**
   - Run `tsc --noEmit` to check types
   - Run tests to confirm behavior unchanged
```

## Slash commands reference

| Command | Description |
|---|---|
| /skills | List all available skills |
| /skills use <name> | Activate a skill for the current session |
| /skills deactivate <name> | Deactivate a skill |
| /skills info <name> | Show detailed skill information |
| /skills new | Create a new skill interactively |

## Best practices

### Do

-   **Be specific** - Clear purpose and concrete examples
-   **Be actionable** - Numbered steps the agent can follow
-   **Be minimal** - Only request necessary tools
-   **Be platform-aware** - Note OS-specific commands
-   **Include examples** - Show 2-3 real usage prompts

### Avoid

-   Creating vague, generic skills
-   Requesting all tools "just in case"
-   Assuming specific file paths exist
-   Skipping the workflow section
-   Forgetting to test your skill

## Troubleshooting

### Autohand doesn't use my Skill

**Check:** Is the description specific enough?

Vague descriptions make discovery difficult. Include both what the Skill does and when to use it, with key terms users would mention.

``` yaml
# Too generic
description: Helps with data

# Specific
description: Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with Excel files, spreadsheets, or .xlsx files.
```

**Check:** Is the YAML valid?

``` bash
# View frontmatter
cat .autohand/skills/my-skill/SKILL.md | head -n 15
```

**Check:** Is the Skill in the correct location?

``` bash
# Personal Skills
ls ~/.autohand/skills/*/SKILL.md

# Project Skills
ls .autohand/skills/*/SKILL.md
```

### Skill has errors

**Check:** Do scripts have execute permissions?

``` bash
chmod +x .autohand/skills/my-skill/scripts/*.py
```

**Check:** Are file paths correct? Use forward slashes (Unix style) in all paths.

## Sharing Skills with your team

### Step 1: Add Skill to your project

``` bash
mkdir -p .autohand/skills/team-skill
# Create SKILL.md
```

### Step 2: Commit to git

``` bash
git add .autohand/skills/
git commit -m "Add team Skill for PDF processing"
git push
```

### Step 3: Team members get Skills automatically

``` bash
git pull
autohand  # Skills are now available
```

## Next steps

[CLI Reference](/docs/working-with-autohand-code/cli-reference.html) - Full list of CLI options, slash commands, and available tools

[Configuration](/docs/working-with-autohand-code/configuration.html) - Set up providers, permissions, and workspace preferences

[Guides](/docs/guides/) - Step-by-step tutorials for common workflows and migrations

[Headless Mode](/docs/working-with-autohand-code/headless-mode.html) - Run Autohand in CI/CD pipelines and automation scripts