Skills

Skills are modular capabilities that extend Claude's functionality with domain-specific expertise.

Learn More

Skills are based on Claude's Agent Skills system. See the official Claude Skills documentation for comprehensive details.

What are Skills?

Skills are filesystem-based resources that provide Claude with:

• Domain-specific expertise and workflows
• Project-specific context and best practices
• Reusable capabilities across conversations

Unlike one-off prompts, Skills load on-demand and eliminate the need to repeatedly provide the same guidance.

How Skills Work

Skills use progressive disclosure - loading content in stages as needed:

Level	When Loaded	Content
Metadata	Always (at startup)	name and description from YAML frontmatter
Instructions	When Skill is triggered	SKILL.md body with guidance
Resources	As needed	Additional files, scripts, references

This ensures only relevant content occupies the context window at any time.

Skill Structure

Every Skill is a directory containing a SKILL.md file with YAML frontmatter:

my-skill/
├── SKILL.md          # Main instructions (required)
├── REFERENCE.md      # Additional guidance (optional)
└── scripts/          # Utility scripts (optional)
    └── helper.py

SKILL.md Format

---
name: code-reviewer
description: Expert code review assistant. Use when reviewing code, checking for bugs, or assessing code quality.
---

# Code Review Skill

## Instructions

When reviewing code:
1. Check for bugs and errors
2. Assess performance implications
3. Suggest improvements
4. Follow language-specific best practices

## Response Format

- Start with a summary
- List issues by severity
- Provide specific suggestions

Required Fields

• name: Unique identifier (lowercase letters, numbers, hyphens only, max 64 chars)
• description: What the Skill does and when to use it (max 1024 chars)

WARNING

The description is critical - Claude uses it to determine when to activate the Skill. Include both what it does AND when to use it.

Skill Locations

Alma loads Skills from multiple locations with the following priority (higher priority overrides lower):

Personal Skills

~/.config/alma/skills/

Your personal Skills, available in all conversations. These have the highest priority.

Claude Code Skills

~/.claude/skills/

Skills from Claude Code, shared between Alma and Claude Code CLI.

Marketplace Skills

Skills installed from Claude's plugin marketplace.

Project Skills

<workspace>/.alma/skills/

Project-specific Skills, automatically loaded when a workspace is active. Perfect for:

• Team-shared coding standards and conventions
• Project-specific workflows and scripts
• Repository-specific documentation helpers

Project Skills Auto-Loading

When you open a chat with a workspace, Alma automatically detects and loads Skills from that workspace's .alma/skills/ directory. The Skills appear in the skill selector and can be used immediately.

Priority Order

When Skills have the same name, the following priority determines which one is used:

1. Personal (highest) - ~/.config/alma/skills/
2. Claude Code - ~/.claude/skills/
3. Marketplace - Installed plugins
4. Project (lowest) - <workspace>/.alma/skills/

Using Skills

Automatic Activation

Claude automatically uses Skills when your request matches a Skill's description. You don't need to explicitly invoke them.

Explicit Reference

You can also mention a Skill by name in your message to ensure it's used.

Skill Content Types

Skills can contain three types of content:

Instructions (Markdown)

Workflows, best practices, and guidance in markdown files.

Code (Scripts)

Executable scripts that Claude can run. The script code doesn't enter the context window - only the output does.

Resources

Reference materials like documentation, schemas, templates, or examples.

Skill Management

Viewing Skills

1. Go to Settings → Skills
2. Browse available Skills
3. Filter by location

Enabling/Disabling

Toggle Skills on or off without deleting them.

Refreshing

Click Refresh to reload Skills from disk after making changes.

Examples

Writing Assistant

writing-assistant/
└── SKILL.md

---
name: writing-assistant
description: Professional writing assistant. Use when drafting documents, editing text, or improving writing quality.
---

# Writing Assistant

Help with:
- Blog posts and articles
- Technical documentation
- Marketing copy
- Email drafts

Follow these principles:
- Clear and concise
- Active voice
- Appropriate tone
- Proper grammar

Project Context

project-context/
├── SKILL.md
└── ARCHITECTURE.md

---
name: project-context
description: Project-specific knowledge for MyApp. Use when working on this codebase.
---

# Project: MyApp

## Quick Reference
- React frontend with TypeScript
- Node.js backend
- PostgreSQL database

For detailed architecture, see [ARCHITECTURE.md](ARCHITECTURE.md).

## Common Tasks
- Start dev: `npm run dev`
- Test: `npm test`
- Build: `npm run build`

Best Practices

Write Clear Descriptions

The description determines when Claude uses your Skill. Include:

• What the Skill does
• When it should be used
• Key trigger phrases

Keep Skills Focused

Each Skill should have a clear, single purpose.

Use Progressive Disclosure

Put essential info in SKILL.md, detailed references in separate files.

Version Control

Store Skills in git for versioning and sharing.

Troubleshooting

"Skill Not Loading"

• Check that SKILL.md exists in the Skill directory
• Verify YAML frontmatter syntax (must have name and description)
• Click Refresh to reload

"Skill Not Activating"

• Check if the description matches your request context
• Make sure the Skill is enabled
• Try mentioning the Skill name explicitly