Skills System

Skills are markdown files that inject instructions into agent system prompts. Drop one into ~/.huginn/skills/ and every agent follows it — globally or per project.

Skill format

A skill is a single SKILL.md file with YAML frontmatter and a markdown body:

---
name: nil-guard
description: "Always guard pointers before use"
author: your-handle
---

Before dereferencing any pointer, always add a nil check and return a
descriptive error.

## Rules
- Never dereference without a nil check
- Return errors.New("nil <name>") on nil input

Frontmatter fields:

Body structure:

• Everything before ## Rules → injected into the system prompt
• Everything after ## Rules → injected as a rules block
• Both are wrapped in <skill> tags when loaded

Skill locations

Project-local skills take precedence over global skills with the same name.

CLI commands

huginn skill list                        # list all installed skills
huginn skill create                      # generate a SKILL.md template
huginn skill search "term"               # search the registry
huginn skill info <name>                 # show skill details
huginn skill install <name>              # install from registry
huginn skill install github:user/repo    # install directly from GitHub
huginn skill install ./path/SKILL.md     # install from local file
huginn skill enable <name>
huginn skill disable <name>
huginn skill uninstall <name>
huginn skill update                      # update all registry skills
huginn skill update <name>               # update one skill
huginn skill validate ./SKILL.md         # validate format before installing

Installing from the registry

huginn skill search
huginn skill install nil-guard

The registry index is cached at ~/.huginn/cache/skills-index.json and refreshed every 24 hours.

Installing from GitHub

Any public GitHub repo with a SKILL.md at the root can be installed directly:

huginn skill install github:your-org/your-skill-repo

Per-agent skills

By default, all installed skills load for all agents. To restrict a skill to specific agents, set the skills field in ~/.huginn/agents/<name>.json:

{
  "skills": ["nil-guard", "go-style"]
}

An absent skills field means the agent gets all enabled skills.

Auto-discovered project rules

These files are automatically injected as workspace context (distinct from the skills system). Loaded in this priority order:

1. .huginn/rules.md — Huginn-specific project rules
2. CLAUDE.md — Claude Code rules
3. .claude/CLAUDE.md — Alternate Claude Code location
4. .cursor/rules — Cursor rules
5. .cursorrules — Cursor rules (legacy)
6. .github/copilot-instructions.md — GitHub Copilot instructions

Publishing to the registry

1. Create a public GitHub repo with SKILL.md at the root
2. Validate: huginn skill validate ./SKILL.md
3. Open a PR to scrypster/huginn-skills-index adding your entry to index.json