Skill

Where Skills live

Skills can live in a project directory or in the user directory. The scope is different:

Here, ~ means the current operating system user's home directory. Common paths:

For example, a project release workflow can live at:

.axiomate/skills/release-check/SKILL.md

When Axiomate starts in that workspace, the Skill is available as /release-check.

For the same Skill to work across projects, put it in the user directory:

~/.axiomate/skills/release-check/SKILL.md

Common directory structure

A Skill does not have to be only one SKILL.md file. More advanced Skills often keep scripts, templates, or examples next to the main Skill file. This is a project-directory example:

<project-root>/
└── .axiomate/
    └── skills/
        └── release-check/
            ├── SKILL.md
            ├── scripts/
            │   ├── collect-status.js
            │   └── verify-release.sh
            ├── templates/
            │   └── release-summary.md
            └── examples/
                └── good-report.md

For a personal Skill in the user directory, the structure is the same, but the root becomes ~/.axiomate/skills/.

Axiomate only requires the entry file to be named SKILL.md. Other files are not run automatically, but the Skill body can instruct AI to read them or run scripts from scripts/.

What a Skill is

A Skill is a reusable task instruction. It stores a repeatable workflow in SKILL.md so it can be invoked as a slash command, and so AI can use it when the situation matches.

Good Skill candidates include release flows, code review steps, fixed report formats, project validation checklists, deployment checks, or repeated team-specific instructions.

Inside SKILL.md, use ${AXIOMATE_SKILL_DIR} to refer to the current Skill directory. Example:

Run `${AXIOMATE_SKILL_DIR}/scripts/verify-release.sh` and summarize the result.

This keeps script references pointed at files inside the Skill even if the Skill directory is moved.

How to write a Skill

A minimal Skill looks like this:

---
description: Run the project release checks.
---

# Release check

Run the release verification steps for this project.

1. Check the current git status.
2. Run lint and build.
3. Summarize whether the release is ready.

The directory name becomes the command name. If the file is saved at .axiomate/skills/release-check/SKILL.md, the command is:

/release-check

frontmatter is the configuration block at the very top of SKILL.md, wrapped by ---. It is not the instruction body that AI follows directly. Axiomate reads it as metadata to understand the Skill description, arguments, permissions, and execution mode.

Example:

---
description: Run the project release checks.
allowed-tools:
  - Bash(pnpm:*)
argument-hint: "<release-version>"
---

# Release check

The instruction body starts here.

Common frontmatter fields:

How to use Skills

List Skills provided by the project, user directory, plugins, or MCP:

/skills

Some bundled Skills can be invoked directly, such as /skillify below, and may not appear in this list.

Run a Skill directly:

/release-check

Run a Skill with arguments:

/fix-issue 123

If a Skill defines arguments, Axiomate substitutes those values into $name references in the body. Example:

---
description: Fix a tracked issue.
argument-hint: "<issue-id>"
arguments:
  - issue_id
---

Fix issue `$issue_id`. Read the issue context, implement the fix, run validation, and summarize the result.

Invoke it with:

/fix-issue 123

Skills are not only manual commands. Unless disable-model-invocation: true is set, AI can also invoke a Skill when it appears relevant. Clear description and when_to_use fields make the Skill easier to use correctly.

How to generate a Skill

After completing a repeatable workflow, use the bundled skillify Skill:

/skillify

Or include a short description:

/skillify save this release-check process as a reusable Skill

skillify reviews the current session and asks follow-up questions about the name, when to use it, steps, and save location. After confirmation, it writes a SKILL.md file.

After generation, run the Skill with /<skill-name> or edit SKILL.md directly to refine it.