---
title: Skill Creation
url: https://arcana.otnelhq.com/docs/skill-creation
---

# Skill Creation



Skills are the primary way to extend Arcana's capabilities. A skill is a folder containing a `SKILL.md` file with instructions the agent loads on demand. This guide covers everything you need to create, test, and share custom skills.




## Anatomy of a Skill



```
skills/
  my-skill/
    SKILL.md           # Required — skill definition
    references/        # Optional — additional docs loaded by the agent
      guide.md
      examples.md
    scripts/           # Optional — helper scripts
      setup.sh
```




## SKILL.md Format



Every skill requires a `SKILL.md` file with YAML frontmatter:



```
---
name: My Custom Skill
description: Does something specific for my project
---

# My Custom Skill

## Purpose

This skill helps with [specific task].

## Instructions

1. Step one
2. Step two
3. Step three

## Rules

- Always do X before Y
- Never do Z

## Examples

### Example 1: Basic usage
Show a concrete example of the skill in action.

### Example 2: Advanced usage
Show a more complex example.
```




## Frontmatter Fields



| Field | Required | Description |
| --- | --- | --- |
| `name` | Yes | Human-readable skill name (generates the skill ID) |
| `description` | No | Brief description shown in skill lists |
| `triggers` | No | Keywords that auto-activate this skill |
| `category` | No | Override the auto-detected category |




## Skill ID Generation



The skill ID is derived from the folder name: lowercase, special characters replaced with hyphens.



| Folder Name | Skill ID |
| --- | --- |
| `python-testing` | `python-testing` |
| `Code Review` | `code-review` |
| `React+TypeScript` | `react-typescript` |




## Reference Files



The `references/` directory contains additional documents the agent can read when the skill is active:



```
skills/
  my-skill/
    SKILL.md
    references/
      api-guide.md      # Agent reads this when needed
      examples.md       # Concrete usage examples
      troubleshooting.md # Common issues and fixes
```



The agent automatically discovers and loads reference files. Keep them focused and well-organized.




## Helper Scripts



The `scripts/` directory contains executable scripts the agent can run:



```
skills/
  my-skill/
    SKILL.md
    scripts/
      setup.sh          # Environment setup
      validate.sh       # Validation checks
      test.sh           # Run tests
```



Scripts must be executable (`chmod +x`). The agent can invoke them via the shell tool.




## Writing Effective Skills



- **Be specific** — skills work best when they solve one problem well
- **Include examples** — concrete examples help the agent understand your intent
- **Set rules** — explicit constraints prevent unwanted behavior
- **Use step-by-step instructions** — numbered lists are clearer than prose
- **Reference files** — put detailed docs in `references/` to keep SKILL.md focused




## Testing Your Skill



```bash
# 1. Place your skill in the skills directory
cp -r my-skill/ ~/.arcana/skills/

# 2. List available skills
arcana skills list

# 3. Get info on your skill
arcana skills info --skill my-skill

# 4. Test in a session
arcana
> /skill my-skill
> [test your skill's behavior]
```




## How Skills Are Loaded



Arcana discovers skills from three locations (in priority order):



1. **User-local:** `~/.arcana/skills/`
2. **In-repo:** `skills/` in the project root
3. **Environment override:** `ARCANA_SKILLS_DIRS` (separated by `;`)




## Sharing Skills



Skills are just folders with markdown files. Share them by:



- **Git** — commit the skill folder to your repo
- **Copy** — share the folder directly
- **Package** — publish as an npm package with the skill in the package




## Complete Example



```
---
name: API Review
description: Review REST API endpoints for consistency and best practices
triggers:
  - api review
  - endpoint review
  - rest api
---

# API Review Skill

## Purpose
Review REST API endpoints for consistency, naming conventions, error handling, and documentation.

## Instructions

1. List all API route files in the project
2. For each endpoint, check:
   - HTTP method matches the action (GET for reads, POST for creates, etc.)
   - URL follows RESTful naming conventions
   - Request/response schemas are documented
   - Error responses include proper status codes
   - Authentication is applied where needed
3. Generate a report with findings and suggestions
4. If issues are found, suggest specific fixes

## Rules
- Never modify files without explicit approval
- Focus on consistency and best practices
- Consider security implications of each endpoint

## Output Format
Present findings as a structured report with:
- Summary of endpoints reviewed
- Issues found (grouped by severity)
- Recommendations for each issue
```