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

Skill ID Generation

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

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

# 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