# AI agent skills (/docs/reference/ai-agent-skills)



Agent skills are Markdown instructions that help an AI agent use a package, workflow, or project correctly. The LPM CLI supports two distinct systems under the [`lpm skills`](/docs/packages/skills) command family.

## Two systems, one command [#two-systems-one-command]

|                 | LPM.dev package skills                                  | Standalone skills                                             |
| --------------- | ------------------------------------------------------- | ------------------------------------------------------------- |
| Purpose         | Versioned guidance shipped with an `@lpm.dev/*` package | Reusable agent capability independent of a package install    |
| Source          | Publisher-authored `.lpm/skills/*.md` files             | Standard `SKILL.md` directories from GitHub or a local source |
| Delivery        | Validated and stored by the LPM.dev Registry            | Resolved and security-scanned by the LPM CLI                  |
| Project storage | `.lpm/skills/<owner.package>/`                          | `.lpm/managed-skills/` plus selected agent targets            |
| Lifecycle       | Reconciled with the package version                     | Added, updated, enabled, disabled, or removed explicitly      |
| Agent links     | None                                                    | Linked by default, or copied with `--copy`                    |

The two systems can coexist in one project. Their paths and ownership records keep publisher source, installed package guidance, and standalone managed content separate.

## Publish guidance with an LPM.dev package [#publish-guidance-with-an-lpmdev-package]

Publishers place each skill directly under `.lpm/skills/`:

```text
package-repository/
├── package.json
└── .lpm/
    └── skills/
        ├── usage.md
        └── migration.md
```

Each file contains YAML frontmatter followed by Markdown guidance:

```md
---
name: package-usage
description: Use the package through its supported public API.
version: "1.4.0"
globs:
  - "src/**/*.ts"
---

# Package usage

Import the public client, initialize it once, and reuse that instance. Follow the package's documented error handling and configuration conventions when changing an existing integration.
```

Nested publisher paths are not supported. `.lpm/skills/guides/usage.md` is rejected by both the LPM CLI preflight and the LPM.dev Registry instead of being silently ignored.

The publisher workflow is:

```bash
# Optional: install the standalone authoring guide
lpm skills add lpm-dev/lpm-guide

# Validate direct .lpm/skills/*.md files
lpm skills validate

# Publish the package and its skills
lpm publish
```

`validate` enforces the registry contract: required `name` and `description`, valid lowercase names, descriptions from 10 to 500 characters, at least 100 Markdown body characters, at most 15 KB per file, at most 10 skills and 100 KB total, unique names, and the package-skill security rules.

Optional `version` identifies the package release the guidance was authored for. It is stored per skill rather than inferred from the package release that carries the file, so older guidance remains identifiable after a later package publish. The LPM CLI preserves the field in installed package-skill frontmatter.

If `package.json > files` would exclude `.lpm/skills`, `lpm publish` adds the directory before creating the current tarball. Projects may also contain installed package skill directories; valid manifest-owned consumer directories are ignored during publisher validation and excluded from the tarball.

## Use guidance from an LPM.dev package [#use-guidance-from-an-lpmdev-package]

Installing a direct `@lpm.dev/*` dependency fetches its published guidance by default:

```bash
lpm install @lpm.dev/owner.package
```

The LPM CLI materializes an exact, package-owned set:

```text
my-project/
└── .lpm/
    └── skills/
        └── owner.package/
            ├── .lpm-package-skills.json
            ├── usage.md
            └── gotchas.md
```

`.lpm-package-skills.json` records ownership and content digests. It lets the LPM CLI reconcile upgrades, verify integrity, and distinguish installed consumer content from publisher-authored files. Do not edit it.

Package skills remain in `.lpm/skills/<owner.package>/`. The LPM CLI does not create agent links or modify editor configuration for them. Point your agent at the relevant directory when you want it to use the package author's guidance:

```text
Read .lpm/skills/owner.package/ before changing code that uses @lpm.dev/owner.package.
```

### Automatic reconciliation [#automatic-reconciliation]

Package skill installation is enabled by default. Installing or upgrading a direct package reconciles its directory to the exact published set; removing the package removes its owned directory.

```bash
lpm config lpm-skills --set false
```

Use `--no-skills` with [`lpm install`](/docs/packages/install), [`lpm add`](/docs/packages/add), or `lpm ci` to opt out once. Use `--skills` to override a disabled preference once. Precedence is `--skills` / `--no-skills`, then `auto-install-lpm-skills`, then the legacy `noSkills` fallback, then the enabled default.

The preference controls future automatic fetching and reconciliation only. It does not delete existing content or disable explicit retrieval:

```bash
lpm skills add @lpm.dev/owner.package --dry-run
lpm skills add @lpm.dev/owner.package --yes
```

### Safe package cleanup [#safe-package-cleanup]

```bash
lpm skills clean --dry-run
lpm skills clean
```

`clean` previews the exact installed package sets, file count, and size. In a terminal it asks for confirmation with **No** selected by default; scripts must pass `--yes`.

Only package directories whose files and digests exactly match a valid LPM CLI ownership manifest are removed. Direct publisher files, untracked or modified content, invalid manifests, symlinks, standalone managed skills, and agent links are preserved. Re-run `lpm install` to restore removed package guidance.

## Manage standalone skills [#manage-standalone-skills]

Standalone skills come from a GitHub repository or tree URL, GitHub `owner/repository` shorthand, or a local directory:

```bash
lpm skills add vercel-labs/skills --skill find-skills
lpm skills add https://github.com/vercel-labs/agent-skills --skill web-design-guidelines
lpm skills add ./team-skills --skill release-notes --agent codex --project
```

Remote standalone inputs currently resolve through GitHub. A discovery catalog can point you to a skill, but the LPM CLI input is its underlying GitHub source. Local inputs are read directly from the selected directory.

In a terminal, `add` opens a wizard for source, skills, project or global scope, compatible agent targets, security review, and confirmation. Scripts provide those choices explicitly and pass `--yes` after reviewing `--dry-run`.

`lpm skills install` is a compatibility alias for `lpm skills add`; use `add` in new scripts.

### Storage and targets [#storage-and-targets]

Standalone content is stored once in an LPM-managed canonical location, then linked by default or copied with `--copy` to selected targets:

| Target      | Project path              |
| ----------- | ------------------------- |
| Codex       | `.agents/skills/<skill>/` |
| Claude Code | `.claude/skills/<skill>/` |
| Cursor      | `.cursor/skills/<skill>/` |

Project canonical content lives in `.lpm/managed-skills/`. Global canonical content lives under the LPM home directory. Project links are relative, so moving the project directory keeps healthy links intact.

### Source and security boundary [#source-and-security-boundary]

GitHub sources must use HTTPS. Branches, tags, and commit refs are resolved to an immutable commit before download. `GH_TOKEN` or `GITHUB_TOKEN` is used only for authenticated GitHub API requests and is not forwarded to the archive host.

The remote boundary limits downloads to 20 MB, expanded content to 64 MB, regular files to 1 MB, 500 archive entries, and 12 directory levels. Traversal, symlinks, hard links, special entries, and oversized selected files are rejected.

Before installation, the LPM CLI scans selected skills for prompt injection, secret access or exfiltration, shell-download execution, and destructive filesystem instructions:

| Severity  | Effect                                                                       |
| --------- | ---------------------------------------------------------------------------- |
| `warning` | Included in the plan; installation can continue after explicit confirmation. |
| `block`   | Stops installation before managed storage or agent targets are written.      |

`lpm skills update --dry-run` shows a bounded content diff and identifies new findings by rule, severity, file, and line. Binary auxiliary files are preserved and represented by SHA-256 digest rather than interpreted as text.

## Unified inventory and lifecycle [#unified-inventory-and-lifecycle]

```bash
lpm skills list
lpm skills view owner.package/usage
lpm skills view release-notes
lpm skills dashboard
```

Inventory uses three ownership categories:

* `package`: LPM.dev package guidance in `.lpm/skills/<owner.package>/`.
* `managed`: standalone content explicitly added through `lpm skills add`.
* `external`: agent-directory skills discovered but not managed by the LPM CLI.

The command boundary follows that ownership:

| Operation                               | Publisher files     | Installed package sets                 | Standalone managed skills           |
| --------------------------------------- | ------------------- | -------------------------------------- | ----------------------------------- |
| `validate`                              | Validates           | Ignores valid owned sets               | No effect                           |
| `clean`                                 | Preserves           | Removes after preview and confirmation | No effect                           |
| `update`, `enable`, `disable`, `remove` | No effect           | No effect                              | Manages selected skills and targets |
| `list`, `view`, `dashboard`             | Not inventory items | Inspects                               | Inspects and manages                |

`view` reports source, estimated context size, security findings, integrity, and target health. `doctor` diagnoses canonical content, targets, ownership, disabled targets, and broken external links. `prune --dry-run` previews exact stale target and state paths before cleanup.

The authenticated local dashboard always combines project and global discovery; its source tabs filter that inventory in the browser. Selecting a skill loads its exact raw Markdown, rendered body, bounded file tree, and metadata by stable inventory ID. Preview-and-apply actions are available only for managed standalone skills. Package and external skills are inspection-only. Agent labels mean configured targets, not observed use by a running agent; context numbers are estimates, not session or billing usage.

Global `--json` emits one structured result for every command, including no-op operations. Unified inventory includes total and per-category counts. Validation, cleanup, and prune can therefore report successful zero-count results without implying a mutation.

## See also [#see-also]

* [`lpm skills`](/docs/packages/skills) — command examples and flags for every workflow
* [`lpm install --no-skills`](/docs/packages/install) — opt out of package skill extraction
* [`lpm add --no-skills`](/docs/packages/add) — same for dependency installation
* [`lpm config lpm-skills`](/docs/infra/config#setup-wizards) — persist automatic package skill installation
* [MCP servers](/docs/reference/mcp-servers) — tools and agent skills are separate integrations