ARCANA
Back to Blog

Tutorial

Writing Your First Arcana Skill

Aug 10, 2026 Tutorial

A skill in Arcana is a self-contained instruction file that teaches the agent a specific behavior. Unlike system prompts that are always loaded, skills activate on demand, keeping context clean and focused.

The key insight behind skills is that an agent's context window is finite. If you load every possible instruction at the start of a session, you burn through tokens before the conversation even begins. Skills solve this by loading only what is relevant to the current task. Need a code review? Load the code-review skill. Writing documentation? Load the documentation skill. The rest stays dormant until needed.

This is not just an optimization. It is a design philosophy. A focused agent that loads 200 tokens of relevant instructions outperforms a bloated agent that loads 5,000 tokens of irrelevant ones. Skills make this possible without requiring the user to think about token budgets.

Anatomy of a Skill

A skill is a Markdown file with a frontmatter header:

---
name: code-review
description: Review code for bugs, style issues, and security problems
triggers:
  - review this code
  - code review
  - check for bugs
---

# Code Review Skill

When reviewing code, follow this checklist:

1. **Correctness** - Does the code do what it claims?
2. **Security** - Are there injection risks, auth bypasses, or data leaks?
3. **Performance** - Are there obvious O(n^2) loops or unbounded allocations?
4. **Style** - Does it follow the project's conventions?

Output a structured report with severity levels.

Frontmatter Fields

  • name: Unique identifier for the skill
  • description: One-line summary shown in the skill picker
  • triggers: Phrases that auto-activate the skill when detected in conversation

Triggers in Practice

Trigger phrases are matched against the user's most recent message using simple string matching. The match is case-insensitive and checks for substring containment. This means a trigger of "code review" will match "can you do a code review of this file" but also "I reviewed the code review process" which is usually fine because the latter is rare in practice.

Write triggers the way a user would naturally speak. "review this code" works better than "code-review-action" because users do not speak in kebab-case. Think about the actual phrases someone would type when they want this behavior.

Loading a Skill

Skills load in three ways:

  1. Automatic. If the user's message matches a trigger phrase, the skill loads transparently. The agent receives the skill's instructions and follows them without you needing to do anything extra. This is the most common loading path.
  2. Manual. Type /skill code-review to load it explicitly. Use this when you know which skill you want but the trigger might not match your current message. Manual loading also lets you load a skill preemptively before you start a task.
  3. Programmatic. Other skills or plugins can request a skill load via the skill API. This is rare in normal use but useful for building compound behaviors where one skill orchestrates several others.

When a skill loads, the agent's context receives the full Markdown body of the skill file. The frontmatter is stripped. The agent sees only the instructions, which is exactly what it needs.

Where Skills Live

By default, Arcana looks for skills in a skills/ directory inside your Arcana home folder. The location depends on your operating system:

  • Linux: ~/.arcana/skills/
  • macOS: ~/.arcana/skills/
  • Windows: %USERPROFILE%\.arcana\skills\

You can add additional directories with the ARCANA_SKILLS_DIRS environment variable. Use colons as separators on Linux/macOS, semicolons on Windows.

Linux / macOS:

export ARCANA_SKILLS_DIRS="$HOME/.arcana/skills:$HOME/my-skills"

Windows (cmd):

set ARCANA_SKILLS_DIRS=%USERPROFILE%\.arcana\skills;%USERPROFILE%\my-skills

Windows (PowerShell):

$env:ARCANA_SKILLS_DIRS="$env:USERPROFILE\.arcana\skills;$env:USERPROFILE\my-skills"

Common Patterns

Here are a few skill patterns that work well in practice:

  • Checklist skills. A numbered list of steps the agent should follow. Simple, reliable, easy to maintain. Good for code reviews, security audits, and quality checks.
  • Template skills. Instructions that shape the agent's output format. "When writing documentation, always include a description, parameters, return value, and example." Good for documentation, reports, and structured responses.
  • Constraint skills. Rules the agent must follow. "Never modify files in the src/legacy/ directory without explicit approval." Good for safety rails and workflow enforcement.
  • Persona skills. Instructions that change how the agent communicates. "Respond in a concise, technical style. Use bullet points. Avoid fluff." Good for adapting the agent to different audiences.

Best Practices

  • Keep skills focused. One skill, one behavior. If a skill does too much, split it into smaller, composable skills.
  • Write clear trigger phrases. They should be natural language that a user would actually say, not technical jargon.
  • Test with /skill preview code-review to see what the agent receives without activating it. This helps you catch formatting issues and ensure the instructions read clearly.
  • Version your skills. The frontmatter supports a version field. Use semantic versioning: bump the minor version when you add behavior, bump the major version when you change the agent's output format.
  • Keep skills under 2,000 tokens. Longer skills consume more context window space. If a skill exceeds this, it is probably doing too much.
  • Use Markdown formatting. Bold for emphasis, code blocks for examples, lists for steps. The agent parses Markdown well and responds to structured input more reliably than walls of plain text.

Distribution

Skills are just Markdown files. This is deliberate. No build step, no compilation, no packaging. You share a skill by sharing the file.

The most common distribution patterns:

  • Git repository. A shared skills directory in your team's repo. Everyone pulls the same skills. Changes are tracked in version control.
  • Chat paste. Copy the skill file and paste it into a conversation. The agent can save it to your skills directory with a single command.
  • Registry. A central collection of community skills. Browse, install, and contribute. Arcana has no built-in registry yet, but the filesystem layout makes one straightforward to build.

Arcana has no opinion on how you distribute skills beyond the filesystem layout. The simplicity is the point.

Related Reading