Agent Skills System

Agent Skills are modular instruction packages that extend Autohand's AI agent with specialized workflows and domain expertise. Skills provide context-aware guidance, tool permissions, and structured approaches for common development tasks.

Overview
Quick Start
Skill Discovery
SKILL.md Format
Auto-Skill Generation
Available Tools
Creating World-Class Skills
Examples
Best Practices

Overview

Skills work like on-demand AGENTS.md files that can be activated for specific tasks. Each skill contains:

Purpose statement - What the skill does
Usage examples - Concrete prompts showing how to use it
Workflow steps - Actionable procedures for the agent
Tool permissions - Which tools the skill can use

When activated, skills inject their instructions into the agent's context, providing specialized guidance for the task at hand.

Quick Start

List Available Skills

# In Autohand REPL
/skills

Use a Skill

/skills use changelog-generator

An exact $skill-name mention activates the installed skill and injects its instructions into the same turn:

$extension-builder adapt this Pi package into an Autohand extension and install it for this project

extension-builder ships with Autohand. The curated copy can also be installed through Autohand's community installer or the open skills ecosystem:

autohand --skill-install extension-builder --yes
npx skills add https://github.com/autohandai/community-skills --skill extension-builder -a autohand-code -y

Create a New Skill

/skills new

Auto-Install Recommended Project Skills

autohand --auto-skill

Built-In Deep Research

/deep-research Hermes self evolving and DSPy

/deep-research <topic> activates the bundled deep-research skill, uses Autohand's web search, fetch, task, and file tools, and saves a cited markdown report under <project>/.autohand/research/topic-<slug>.md. /deep-search is an alias. Saved reports are surfaced in later prompts so the next turn can reuse the research context.

While research is running, /deep-research status (or /deep-search status) shows the persisted run state, task progress, current tool, evidence and failure counts, report target, tokens, and remaining context. A run is only marked completed after all recorded research tasks finish, the cited report passes its required-section/source audit, the final response confirms the exact saved path, and any project quality checks pass. Otherwise the run remains incomplete with explicit blockers in its status.

Skill Discovery

Account skills from Console

All plans can add skills from Skilled, create or import their own SKILL.md instructions, edit them, enable or disable them, and remove them in Console under Configure > Skills. Account-managed instructions synchronize automatically at startup and during the normal background sync interval (5 minutes by default), when Code is signed in and sync is enabled. Use the same api.accountId as Console when working with a team account.

The account copy lives in a separate .account-skills/ cache. A running registry rechecks that snapshot when listing or activating skills, so disabled or removed account skills are no longer available after sync without restarting Code. Independently installed and project skills are preserved. An account skill with the same name takes precedence while it is present in the account library, including when disabled. Logout or switching the configured account hides the previous account cache. Offline use keeps the last successfully synced snapshot until connectivity returns.

Console's Skills Usage page shows reported CLI skill events. Telemetry is optional and is not required for managing or synchronizing skills. Console only marks a revision applied after the CLI has persisted it and acknowledged it. The API skill-library migration and a CLI version containing account-skill sync must be released before this works in production.

Skills are discovered from multiple locations, with later sources taking precedence:

Location	Source ID	Description
Packaged `dist/skills/builtin/**/SKILL.md`	`builtin`	Skills shipped with Autohand
`~/.codex/skills/**/SKILL.md`	`codex-user`	User-level Codex skills (recursive)
`~/.claude/skills/*/SKILL.md`	`claude-user`	User-level Claude skills (one level)
`~/.agent/skills/**/SKILL.md`	`agent-user`	User-level shared agent skills (recursive)
`~/.agents/skills/**/SKILL.md`	`agent-user`	User-level `npx skills` shared skills (recursive)
`~/.autohand/skills/**/SKILL.md`	`autohand-user`	User-level Autohand skills (recursive)
`<project>/.claude/skills/*/SKILL.md`	`claude-project`	Project-level Claude skills (one level)
`<project>/skills/**/SKILL.md`	`agent-project`	Project-level shared skills (recursive)
`<project>/.agent/skills/**/SKILL.md`	`agent-project`	Project-level shared agent skills (recursive)
`<project>/.agents/skills/**/SKILL.md`	`agent-project`	Project-level shared agent skills (recursive)
`<project>/<agent-dir>/skills/**/SKILL.md`	`agent-project`	Third-party agent project skills (recursive)
`<project>/.autohand/skills/**/SKILL.md`	`autohand-project`	Project-level Autohand skills (recursive)
Enabled extension `contributes.skills` entries	`extension`	Skills owned by installed Autohand extensions

Supported third-party project skill directories include .aider-desk/skills, .augment/skills, .bob/skills, .codeartsdoer/skills, .codebuddy/skills, .codemaker/skills, .codestudio/skills, .commandcode/skills, .continue/skills, .cortex/skills, .crush/skills, .devin/skills, .factory/skills, .forge/skills, .goose/skills, .hermes/skills, .junie/skills, .iflow/skills, .kilocode/skills, .kiro/skills, .kode/skills, .mcpjam/skills, .vibe/skills, .mux/skills, .openhands/skills, .pi/skills, .qoder/skills, .qwen/skills, .rovodev/skills, .roo/skills, .tabnine/agent/skills, .trae/skills, .windsurf/skills, .zencoder/skills, .neovate/skills, .pochi/skills, and .adal/skills.

Auto-Copy Behavior

Skills discovered from Codex or Claude locations are automatically copied to the corresponding Autohand location:

~/.codex/skills/ and ~/.claude/skills/ → ~/.autohand/skills/
<project>/.claude/skills/ → <project>/.autohand/skills/

Existing skills in Autohand locations are never overwritten. Shared agent and third-party project skill directories are loaded in place; they are not automatically copied.

Codex Skill Compatibility

Autohand can activate skills discovered from ~/.codex/skills/. When those skills include Codex-specific installer instructions, Autohand treats user-skill installs as Autohand installs by default:

child shell commands launched by Autohand map CODEX_HOME to AUTOHAND_HOME unless the command explicitly overrides CODEX_HOME
skill installs should target $AUTOHAND_HOME/skills (default ~/.autohand/skills), not ~/.codex/skills
"Restart Codex" follow-up text in imported installer skills means restart Autohand

SKILL.md Format

Skills use YAML frontmatter followed by markdown content:

---
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 (e.g., 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 Bootstrap

The --auto-skill flag analyzes your project, finds high-confidence community skills that fit the codebase, installs them into <project>/.autohand/skills/, and activates them for the session before the agent starts.

Usage

autohand --auto-skill

How It Works

Project Analysis - Scans for package.json, requirements.txt, Cargo.toml, go.mod
Recommendation - Uses the skills advisor to rank community skills for the project
Install - Automatically installs the strongest matches at project scope
Activation - Activates the installed skills so their instructions are available immediately
Fallback - If nothing scores highly enough, Autohand continues normally without installing 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

$ autohand --auto-skill
Scanning for community skills that fit this project...
Project: Ink TypeScript CLI with strong testing needs.
  ✓ clean-coder-skill (92%) — Improves implementation discipline for CLI refactors.
  Installed clean-coder-skill

Auto-activated skills: clean-coder-skill

For manual discovery inside a session, use /skills install, /learn, find_agent_skills, and install_agent_skill.

Available Tools

Skills can specify which tools they need via the allowed-tools field. Available tools by category:

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
`find`	Canonical code discovery tool for exact, contextual, and semantic search
`search`	Legacy alias for `find` exact search
`search_replace`	Search and replace in files
`search_with_context`	Legacy alias for `find` with surrounding context
`semantic_search`	Legacy alias for `find` semantic mode
`list_tree`	List directory structure
`file_stats`	Get file metadata
`create_directory`	Create directories
`delete_path`	Delete files/directories
`rename_path`	Rename/move files
`copy_path`	Copy files/directories

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_stash_list`	List stashes
`git_stash_pop`	Apply stashed changes
`git_merge`	Merge branches
`git_rebase`	Rebase branches
`git_cherry_pick`	Cherry-pick commits
`git_fetch`	Fetch from remote
`git_pull`	Pull changes
`git_push`	Push changes
`auto_commit`	Auto-generate commit message and commit (auto-approves in yes/non-interactive mode)

Commands

Tool	Description
`run_command`	Execute shell commands
`custom_command`	Run user-defined commands

Dependencies

Tool	Description
`add_dependency`	Add project dependency
`remove_dependency`	Remove dependency

Memory

Tool	Description
`save_memory`	Persist information
`recall_memory`	Retrieve information ranked by content, tags, and recency
`inspect_memory`	Outline or zoom memory, invalidate derived summaries, or rebuild projections
`delete_memory`	Delete an obsolete memory while retaining its canonical deletion event

Delegated and teammate workers read up to five recent project lessons from the selected workspace's .autohand/memory/, with each lesson truncated to 1,000 characters. They treat saved lessons as reference data, not new instructions or permission to expand a task. Bare mode disables this automatic context.

Workers with save_memory available can save an explicitly authorized, evidence-backed lesson with level="project". They must not save secrets, raw logs, or speculative explanations. Read-only workers and workers without the memory tool report lesson candidates to the lead; their tool access is never expanded to persist memory. Worker output is not automatically stored, and agent.autoMemory: false keeps automatic lesson saving disabled.

Skill activations are learned as project capability usage in the canonical memory event log. The derived project ranking distinguishes user and agent use, so frequently successful skills can inform later sessions without copying skill bodies into memory. Slash-command usage follows the same privacy-safe model, but commands are only suggested and never automatically executed.

Planning

Tool	Description
`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.

# Changelog Generator

Transforms git commits into polished, user-friendly changelogs for releases.

## 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:

## 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:

## 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. Platform Awareness

Specify platform-specific commands when relevant:

## Platform Commands

**macOS/Linux:**
```bash
npm run build && npm test

Windows (PowerShell):

npm run build; npm test


### 5. Tool Permissions

Specify only the tools your skill needs:

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

Examples

Example 1: Changelog Generator

---
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

What changed between v1.0.0 and v2.0.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
   - **Docs** (`docs:`): Documentation updates
   - **Refactor** (`refactor:`): Code improvements
4. Transform technical commits into user-friendly language
5. Format as clean markdown with headers and bullet points
6. Highlight breaking changes prominently

## Output Format

```markdown
# Changelog

## [2.5.0] - 2024-12-23

### New Features
- Added dark mode support for all themes
- Users can now export data in CSV format

### Bug Fixes
- Fixed login timeout on slow connections
- Resolved issue with file uploads over 10MB

### Breaking Changes
- Removed deprecated `oldApi()` method - use `newApi()` instead

Tips

Run from repository root for accurate git access
Use date ranges for focused changelogs
Review output before publishing
Consider your audience (developers vs end-users)


### Example 2: TypeScript Refactoring Guide

```markdown
---
name: typescript-refactoring
description: Guides TypeScript refactoring with type-safe patterns and best practices.
allowed-tools: read_file write_file find 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
- Modernizing legacy patterns

## How to Use

Refactor this function to use generics

Extract the user validation logic into a separate module

Convert this file to strict TypeScript


## 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
   - Consider backward compatibility

3. **Make Changes**
   - Apply changes incrementally
   - Run type checker after each change
   - Update imports in dependent files

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

## Common Patterns

### Extract Function
```typescript
// Before
const result = items.filter(x => x.active).map(x => x.name);

// After
function getActiveNames<T extends { active: boolean; name: string }>(items: T[]): string[] {
  return items.filter(x => x.active).map(x => x.name);
}

Add Type Guards

function isUser(value: unknown): value is User {
  return typeof value === 'object' && value !== null && 'id' in value;
}

Tips

Enable strict mode in tsconfig for best type safety
Use unknown instead of any when type is truly unknown
Prefer interfaces for object shapes, types for unions
Add JSDoc comments for complex types


### Example 3: Skill Creator

```markdown
---
name: skill-creator
description: Helps create new Autohand skills with proper structure and best practices.
allowed-tools: read_file write_file create_directory find
---

# Skill Creator

Guides you through creating effective, well-structured Autohand skills.

## When to Use This Skill

- Creating a new project-specific skill
- Converting workflow knowledge into reusable skills
- Sharing expertise with your team

## How to Use

Create a skill for generating API documentation

Help me make a skill for our deployment process


## Workflow

1. **Define Purpose**
   - What problem does this skill solve?
   - When should someone use it?

2. **Identify Tools**
   - Which tools does the workflow need?
   - Start minimal, add tools as needed

3. **Write Examples**
   - Create 2-3 concrete usage examples
   - Use real scenarios from your workflow

4. **Document Workflow**
   - Break down into numbered steps
   - Include decision points
   - Note platform differences if relevant

5. **Save Skill**
   - Save to `.autohand/skills/<name>/SKILL.md`
   - Test with `/skills use <name>`

## Skill Template

```markdown
---
name: your-skill-name
description: Brief description of when to use this skill
allowed-tools: read_file write_file run_command
---

# Your Skill Name

One paragraph explaining what this skill does.

## When to Use This Skill

- Scenario 1
- Scenario 2
- Scenario 3

## How to Use

\```
Example prompt 1
\```

\```
Example prompt 2
\```

## Workflow

1. First step
2. Second step
3. Third step

## Tips

- Helpful tip 1
- Helpful tip 2

Tips

Keep skills focused on one workflow
Include real examples from your project
Update skills as your workflow evolves
Share skills via version control


---

## 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

### Don't

- Don't create vague, generic skills
- Don't request all tools "just in case"
- Don't assume specific file paths exist
- Don't skip the workflow section
- Don't forget to test your skill

---

## 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 |

---

## Related Documentation

- [Configuration Reference](./config-reference.md) - Full configuration options
- [CLI Usage](./cli-usage.md) - Command-line interface guide

Navigation Menu

Uh oh!

Agent Skills System

Table of Contents

Overview

Quick Start

List Available Skills

Use a Skill

Create a New Skill

Auto-Install Recommended Project Skills

Built-In Deep Research

Skill Discovery

Account skills from Console

Auto-Copy Behavior

Codex Skill Compatibility

SKILL.md Format

Frontmatter Fields

Auto-Skill Bootstrap

Usage

How It Works

Detected Patterns

Example Output

Available Tools

File Operations

Git Operations

Commands

Dependencies

Memory

Planning

Creating World-Class Skills

1. Clear Purpose

2. Concrete Examples

3. Actionable Workflows

4. Platform Awareness

Examples

Example 1: Changelog Generator

Tips

Add Type Guards

Tips

Tips

Uh oh!

FilesExpand file tree

agent-skills.md

Latest commit

History

agent-skills.md

File metadata and controls

Agent Skills System

Table of Contents

Overview

Quick Start

List Available Skills

Use a Skill

Create a New Skill

Auto-Install Recommended Project Skills

Built-In Deep Research

Skill Discovery

Account skills from Console

Auto-Copy Behavior

Codex Skill Compatibility

SKILL.md Format

Frontmatter Fields

Auto-Skill Bootstrap

Usage

How It Works

Detected Patterns

Example Output

Available Tools

File Operations

Git Operations

Commands

Dependencies

Memory

Planning

Creating World-Class Skills

1. Clear Purpose

2. Concrete Examples

3. Actionable Workflows

4. Platform Awareness

Examples

Example 1: Changelog Generator

Tips

Add Type Guards

Tips

Tips