Skip to main content

Create a skill

Scaffold a skill, write its instructions, use it locally, and publish it — end to end.

A skill packages specialized knowledge an agent loads on demand — how to review a diff, scaffold a component, or follow a release checklist. This how-to walks the full loop: scaffold, edit, use, publish.

Scaffold the skill

Section titled Scaffold the skill

Create a new skill with axm skills new, which generates the folder, SKILL.md, and skill.json manifest for you:

axm skills new code-review

Names are lowercase, hyphenated, up to 64 characters. The command writes the authored package under the project skills/ root:

your-project/
└── skills/
    └── code-review/    # canonical package you author
        ├── skill.json  # manifest (owner, version, …)
        └── src/
            └── SKILL.md

Edit the generated SKILL.md

Section titled Edit the generated SKILL.md

Open the generated SKILL.md and write your instructions. A skill is YAML frontmatter (name and description) plus the Markdown the agent follows:

---
name: code-review
description:
  Review a diff against our TypeScript and Effect conventions. Use before
  opening a pull request.
---

# Code review

Read the changed files, then check for...

The description helps supporting hosts discover the skill. Say plainly what it does and when to use it. Selection depends on the host and model; packaging and a valid description do not guarantee activation.

A skill can also bundle scripts, references, and templates alongside SKILL.md — add them under the skill's src/ and reference them from the instructions. For every manifest and frontmatter field, run axm help skill-schema or see the skill schema.

Use it locally

Section titled Use it locally

Materialize the skill into your configured coding agents with axm sync:

axm sync

This writes the skill into the universal .agents/skills/code-review location plus each configured agent's native directory (.claude/skills/code-review for Claude Code, and so on). Now make a small code change and ask your agent to use the skill:

Review my changes before I open a pull request.

Observe whether your agent selects the skill and follows it. Also try a paraphrase and an adjacent task that should not select it. Iterate on the instructions, run axm sync again, and re-test against the intended behavior.

Publish it

Section titled Publish it

When the skill is ready to share, bump its version and publish it to the AgentXM.ai registry:

axm version @you/skills/code-review minor
axm skills publish code-review

AXM validates the manifest and SKILL.md. Existing versions are skipped without overwriting them; an unpublished lower version requires explicit backfill. See Publish a skill for the end-to-end publishing flow, including the account, handle, and visibility concerns that live on agentxm.ai.

Optional engineering guidance

Section titled Optional engineering guidance

The steps above support basic authoring on their own. For deeper design, review, and evaluation guidance, the encouraged @agentxm/packs/agent-extension-engineering collection contains one routing skill and a knowledge bundle. When you want that additional guidance, install the pack:

axm install @agentxm/packs/agent-extension-engineering

Its recommendations complement AXM's package contracts. The AXM skill and CLI remain usable without the pack.

Operational sources: axm help skills, axm help authoring, and axm help publish for your installed CLI. This walkthrough was reconciled with AXM 0.51.0.

See also

Section titled See also