Working with Autohand
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
# In Autohand REPL
/skillsUse a Skill
/skills use changelog-generatorCreate a new Skill
/skills newAuto-generate project Skills
autohand --auto-skillSkill 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/:
mkdir -p ~/.autohand/skills/my-skill-nameProject Skills
Project Skills are shared with your team. Store them in .autohand/skills/ within your project:
mkdir -p .autohand/skills/my-skill-nameProject 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:
---
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.
autohand --auto-skillHow it works
- Project Analysis - Scans for package.json, requirements.txt, Cargo.toml, go.mod
- Detection - Identifies languages, frameworks, and patterns
- Platform Awareness - Detects OS (macOS/Linux/Windows) for appropriate commands
- LLM Generation - Creates 3 tailored skills with examples and tool permissions
- 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
$ 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 activateAvailable 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:
# 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 customers2. 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 headers4. Minimal tool permissions
Specify only the tools your skill needs:
allowed-tools: git_log git_diff_range read_file write_fileExample Skills
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
```
## 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 pointsTypeScript refactoring guide
---
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 unchangedSlash 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.
# 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?
# View frontmatter
cat .autohand/skills/my-skill/SKILL.md | head -n 15Check: Is the Skill in the correct location?
# Personal Skills
ls ~/.autohand/skills/*/SKILL.md
# Project Skills
ls .autohand/skills/*/SKILL.mdSkill has errors
Check: Do scripts have execute permissions?
chmod +x .autohand/skills/my-skill/scripts/*.pyCheck: Are file paths correct? Use forward slashes (Unix style) in all paths.
Sharing Skills with your team
Step 1: Add Skill to your project
mkdir -p .autohand/skills/team-skill
# Create SKILL.mdStep 2: Commit to git
git add .autohand/skills/
git commit -m "Add team Skill for PDF processing"
git pushStep 3: Team members get Skills automatically
git pull
autohand # Skills are now available