Skills and instructions
Give agents durable project instructions (AGENTS.md) and reusable skills
(SKILL.md) that can be invoked as slash commands or mentioned inline in chat.
On this page: Instruction files, Where skills are discovered, Write a skill, and Activate and reload skills.
Both skills and instructions are enabled by default.
Instruction files
Albedo loads project-level and global instruction files into the agent's context:
- Project instructions come from
AGENTS.mdandCLAUDE.mdat the session workspace root, and Markdown files directly inside its.agentsand.albedodirectories. Discovery does not recursively scan nested project directories. A nested directory supplies its own root instructions when it becomes the session workspace. - Global instructions come from Markdown files directly inside
~/.agentsand~/.albedo. - Albedo adds its shipped instructions after project and global instructions.
The agent directories exclude system.md and append_system.md from this list.
See instruction loading for the host owner.
Open /instructions in the terminal or web client to inspect which instruction
files are active and toggle per-session defaults.
Where skills are discovered
Albedo scans immediate child directories under these five roots in precedence order:
<workspace>/.albedo/skills<workspace>/.agents/skills$HOME/.albedo/skills$HOME/.agents/skills- Built-in skills shipped with Albedo
If two directories define the same skill name, the earlier root in that order
wins. For declarative Nix setups, programs.albedo.skills in
home-manager links skills into
~/.albedo/skills.
Write a skill
Each skill lives in its own directory containing a SKILL.md file with YAML
frontmatter:
---
name: release-notes
description: Summarize merged changes since the last tag.
---
Inspect commits since the latest tag and group user-visible changes by area.
name: 1โ64 lowercase ASCII letters, digits, and single separating hyphens, matching the directory name (or omitted to inherit the directory name).description: 1โ1,024 characters shown in the skill list and command menu.
Scripts, templates, and reference files placed beside SKILL.md belong to the
skill. Mention them in SKILL.md, and the agent reads them when they need them.
Activate and reload skills
A skill is used in three ways:
- Slash command: run
/skill-name(with optional arguments) in the composer. - Inline mention: mention
$skill-namein a message to activate that skill for the turn. - By itself: every agent sees each skill's name and description, and reads a skill when its description matches the task. A precise description is what makes that work.
Activating a skill loads its instructions. It does not run bundled scripts or grant new tools by itself.
Use /skills to enable or disable individual skills for a session. After adding
or editing skill files on disk, run /reload session in an existing session (no
daemon restart is needed).
Previous webhooks Next mcp servers