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 command family.

Two systems, one command

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

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

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

Each file contains YAML frontmatter followed by Markdown guidance:

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

# 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

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

lpm install @lpm.dev/owner.package

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

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:

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

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.

lpm config lpm-skills --set false

Use --no-skills with lpm install, lpm 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:

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

Safe package cleanup

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

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

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

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

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

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:

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

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:

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

• lpm skills — command examples and flags for every workflow
• lpm install --no-skills — opt out of package skill extraction
• lpm add --no-skills — same for dependency installation
• lpm config lpm-skills — persist automatic package skill installation
• MCP servers — tools and agent skills are separate integrations