Create a custom skill

A custom skill is a named SKILL.md procedure that you can invoke with a slash command. Put one under ~/.afk/skills/ for every project, or under <cwd>/.afk/skills/ for one project. It is discovered when a session starts.

Create oneCopy Anchor Link

---
name: review-note
description: Review a note and suggest a concise revision.
when-to-use: When a user asks for editorial review of a note.
argument-hint: "<file> [style]"
context: load
---

Read `${1}`. Revise it in the style `${2}` if supplied.
The complete caller input is `$ARGUMENTS`.

The when-to-use hint helps the model route to the skill and appears in the REPL's selected skill hint. The description remains the short listing label. argument-hint explains expected input; it is not a parser. Name and directory must match the skill-name rules: 1 to 64 lowercase letters, digits, or single internal hyphens. A skill needs a nonempty body and a description no longer than 1,024 characters.

Arguments and executionCopy Anchor Link

$ARGUMENTS and $ARGUMENT insert the entire raw argument string. ${1}, ${2}, and so on insert one-indexed, shell-style positional tokens: quoted words stay together. Braces are required; bare $1 is left alone so shell examples and currency are not rewritten. A missing positional remains literal, which makes a mistaken invocation visible. Placeholders are expanded for both load and fork skill paths. These substitutions form model instructions, not shell escaping; validate input before using it in commands.

context: load (the default) returns instructions to the current agent with its existing context. context: fork gives a child session its own context window and passes arguments to it. ${SKILL_ROOT} resolves to the skill directory when you need bundled files. Plugin skills can be packaged in an installed plugin's skills/<name>/SKILL.md directory. Name collisions with other origins get a namespaced fallback such as user:review-note.

Keep a skill manual-onlyCopy Anchor Link

Add disable-model-invocation: true to its SKILL.md frontmatter to omit it from the model-facing skill manifest while retaining direct slash invocation. To hide existing skill names without editing their files, set the human-only skills.hidden array in afk.config.json:

{
  "skills": {
    "hidden": ["review-note", "example-plugin:publish"]
  }
}

Bare names also match plugin-qualified names with that suffix. The agent's config_set cannot change skills.hidden. Hiding is a routing control, not a security boundary: it does not remove an explicitly invoked skill or revoke its tools. See Configuration keys.

RelatedCopy Anchor Link