# <Skill />

Stage and register one complete local Agent Skills package for a single Agent session.
Canonical: https://agent-markup-language.com/docs/reference/primitives/skill/
Documentation index: https://agent-markup-language.com/docs/
Complete documentation: https://agent-markup-language.com/docs/llms.txt

`<Skill />` declares a real local [Agent Skills](https://agentskills.io/specification) package. AML validates and copies the complete package into an invocation-private Agent-visible staging root, then lets the provider expose it through native discovery or metadata-only fallback.

```text
skills/
└── evidence-review/
    ├── SKILL.md
    ├── references/
    │   └── checklist.md
    └── scripts/
        └── inspect.sh
```

```md title="skills/evidence-review/SKILL.md"
---
name: evidence-review
description: Review code changes using concrete implementation evidence.
---

# Evidence review

Read `references/checklist.md` when performing a code review.
```

```tsx
import { Agent, Skill } from "@aml-jsx/sdk"

;<Agent provider={reviewer}>
  <Skill src="./skills/evidence-review" />
  Review the current change.
</Agent>
```

## Props

| Prop  | Type     | Required | Meaning                                                                             |
| ----- | -------- | -------- | ----------------------------------------------------------------------------------- |
| `src` | `string` | yes      | Local package directory resolved from [`AmlRuntime.cwd`](https://agent-markup-language.com/docs/reference/runtime/). |

`<Skill />` accepts no children, inline instruction text, remote URL, registry reference, or install command. Use [`<Include />`](https://agent-markup-language.com/docs/reference/primitives/include/) for an application prompt file.

## Package contract

- The directory must contain a root `SKILL.md`; its frontmatter must provide `name` and `description`.
- `name` is a lowercase hyphenated segment of at most 64 characters and must match the source directory name.
- `description` is normalized activation guidance of at most 1,024 characters.
- AML copies regular files recursively, including binary resources, and rejects symbolic links or special filesystem entries.
- AML reads and validates the package live for every evaluation. It never fetches remote content or executes package scripts while staging.

## Discovery and lifecycle

The staged package always ends in `.agents/skills/<name>/SKILL.md`. Providers receive the concrete `.agents` home, package directory, and `SKILL.md` path. Codex and OpenCode use native discovery mapping; providers that do not declare native discovery receive a short session-wide system fragment containing only the Skill name, description, and `SKILL.md` path. AML never inserts the Skill body into the prompt automatically.

`<Skill />` is valid only in the containing Agent plan and remains available for its initial turn and every [`<FollowUp />`](https://agent-markup-language.com/docs/reference/primitives/follow-up/). It is invalid as a standalone value or inside a System or FollowUp block. Duplicate Skill names in one Agent reject.

One Agent owns one writable staging root shared by its Skills and oversized local Includes. AML removes that root after the provider session, before writable Sandbox reconciliation. Skill staging does not silently become durable Workspace state.

This primitive is separate from the installable [AML coding-agent skill](https://agent-markup-language.com/docs/agent-skill/): that package teaches an external coding agent how to author AML, while runtime `<Skill />` registers an application-selected package for one AML Agent session.