# Create a skill

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

A [skill](/docs/skills) 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

Create a new skill with [`axm skills new`](/docs/cli-reference/skills/new),
which generates the folder, `SKILL.md`, and `skill.json` manifest for you:

```bash
axm skills new code-review
```

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

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

## 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:

```markdown
---
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](https://axm.sh/schemas/skill.schema.json).

## Use it locally

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

```bash
axm sync
```

This writes the skill into the universal `.agents/skills/code-review` location
plus each [configured agent's](/docs/managing-coding-agents) 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:

```text
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

When the skill is ready to share, bump its version and publish it to the
[AgentXM.ai registry](https://agentxm.ai):

```bash
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](/docs/publishing) for the end-to-end publishing flow,
including the account, handle, and visibility concerns that live on agentxm.ai.

## 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:

```bash
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

- [Skills](/docs/skills) — what a skill is and how AXM manages it
- [Publish a skill](/docs/publishing) — version and share your skill
- [Find and install skills](/docs/find-and-install-skills) — install skills
  others have published
- [Managing coding agents](/docs/managing-coding-agents) — control which agents
  `axm sync` writes into
- [`axm skills new`](/docs/cli-reference/skills/new) — full CLI reference