Skills

Skills are instruction snippets injected into the agent's conversation at invocation time. They let you encode domain expertise, project conventions, or task-specific playbooks that the model activates when needed — without bloating the base system prompt.

How skills work

The system prompt contains only the skill's name and description for discovery. The full skill body is never baked into the system prompt. Instead, it is injected into the conversation at invocation time via one of two paths:

• User explicit invocation — when you send /skill-name in the chat, the body is injected immediately before your message in the same turn.
• Model proactive invocation — the model has a skill tool. When a task matches an available skill, it calls skill({skill: "name"}) and the body is injected as a text block in the tool-result user message.

After any compaction (auto, manual, or compact tool), the bodies of all active skills are re-injected so the model retains their instructions across context resets.

Dynamic context injection

Before a skill body is injected, AFK renders supported placeholders so the model receives current context rather than an instruction to fetch it. Use $ARGUMENTS for the full text after the skill name, or$0, $1, and $ARGUMENTS[N] for individual arguments. AFK also supports ${CLAUDE_SKILL_DIR}and ${CLAUDE_SESSION_ID} in skill bodies.

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above and flag risks.

Lines such as !`command` and fenced ```!command blocks are executed as preprocessing in the agent's current project directory. Their output replaces the placeholder before the rendered skill body is sent to the model. To disable skill shell preprocessing, set disableSkillShellExecution or disable_skill_shell_execution in AFK settings.

Skill file format

---
name: my-skill
description: What this skill does and when to use it. Be specific — the model reads this.
license: MIT               # optional
compatibility: Requires bash
metadata:
  author: your-org
  version: "1.0"
allowed-tools: Read Bash(git:*)   # optional tool restrictions
---

Skill instructions go here. Written in plain Markdown.

The model receives this full body when the skill is invoked. Include:
- Specific guidelines for this domain
- Patterns to follow
- Anti-patterns to avoid
- Example commands or code snippets

Frontmatter fields

Skill locations

AFK scans these directories (highest to lowest priority):

1. <projectDir>/.afk/skills/ — project-level AFK skills
2. <projectDir>/.agents/skills/ — project-level AgentSkills standard path
3. ~/.afk/skills/ — user-level AFK skills
4. ~/.agents/skills/ — user-level AgentSkills standard path
5. Plugin skills (namespaced as pluginName:skillName)
6. Built-in skills bundled with AFK

Project-level overrides user-level on name collision.

Creating a skill

Each skill lives in its own directory with a SKILL.md file:

mkdir -p ~/.afk/skills/migration-guide
cat > ~/.afk/skills/migration-guide/SKILL.md << 'EOF'
---
name: migration-guide
description: Use when writing or reviewing database migrations. Enforces safe migration patterns.
---

When writing database migrations:

1. **Never combine schema changes with data migrations** in the same migration file.
2. **Always write rollback migrations** — every UP must have a corresponding DOWN.
3. **Add indexes explicitly** — never rely on ORM defaults. Include CONCURRENTLY for large tables.
4. **Test with EXPLAIN ANALYZE** before finalizing any query that touches tables > 10k rows.
5. **Check FK indexes** — every foreign key column must have an explicit index.

## Naming convention
`V<major>.<minor>.<patch>__<description>.sql`
EOF

Creating a skill from the UI

In the browser UI, type /edit_skills or press Ctrl+E in the skill picker. Click New skill, fill in the name, description, body, and scope (user vs. project), then save. The skill is written to disk and reloaded immediately.

Invoking skills

Explicit invocation

/migration-guide write a migration to add a soft-delete column to users

Proactive invocation

When the model identifies that a task matches a skill's description, it calls the skill tool automatically. The skill body is injected and the model proceeds with the enriched instructions — no user action needed.

Built-in skills

AFK ships with these built-in skills:

Skill scripts and assets

A skill directory can include scripts/, references/, and assets/ subdirectories. The base directory path is included in the injected body so skill scripts can use $SKILL_ROOT to locate their resources.

~/.afk/skills/deploy-helper/
  SKILL.md
  scripts/
    pre-deploy-check.sh
    rollback.sh
  references/
    deployment-checklist.md

Plugin skills

Plugins can contribute skills by placing a SKILL.md file inside a skills/<name>/ subdirectory. Plugin skills are namespaced as pluginName:skillName and can be invoked as /pluginName:skillName. See Plugin System.