Agent Skills

Package-published Agent Skills are versioned Markdown guidance shipped with an @lpm.dev/* package. They help an AI coding agent use that package's public API, conventions, and migration paths correctly.

This page covers skills bundled with a Registry package as flat .lpm/skills/*.md files. Standalone SKILL.md directories from GitHub or a local source are a separate LPM CLI workflow. See the LPM CLI skills documentation for both systems.

How package skills work

1. The publisher writes direct Markdown files under .lpm/skills/.
2. The LPM CLI validates them before upload.
3. The LPM.dev Registry validates and stores them with the package version.
4. Public package skills become consumer-available only after the package review and skill review complete.
5. The LPM CLI can materialize the approved set into a consuming project.

Installed package guidance remains under .lpm/skills/<owner.package>/. The LPM CLI does not turn it into a standalone skill or link it into Codex, Claude Code, Cursor, or another agent directory. Point your agent at the package directory when you want it to use that guidance.

Authoring format

Each skill is a direct .md file:

.lpm/
└── skills/
    ├── usage.md
    └── migration.md

Nested publisher paths such as .lpm/skills/guides/usage.md are invalid.

Each file requires YAML frontmatter followed by a Markdown body:

---
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 whenever you change an existing integration.

Field	Required	Rules
name	Yes	Lowercase letters, numbers, and hyphens; no leading or trailing hyphen
description	Yes	10–500 characters
version	No	Package version for which the guidance was authored
globs	No	Array of file patterns where the guidance is relevant

The optional version belongs to the skill. It is preserved even when a later package release carries unchanged guidance.

Limits

Rule	Limit
Skills in one package version	10
Size of one skill file	15 KB
Total skill size in one package version	100 KB
Markdown body	At least 100 characters
Stored skill content across one author or organization	10 MB

Skill names must also be unique within the package version.

Validate and publish

Run the publisher validation before publishing:

lpm skills validate
lpm publish

Validation checks the file layout, frontmatter, sizes, duplicate names, and deterministic security patterns. High-risk download-and-execute instructions, secret access or exfiltration, prompt injection, and destructive filesystem operations can reject publication.

If package.json > files would exclude the skills directory, lpm publish adds .lpm/skills to that array before packing and tells you that it changed package.json.

Review and availability

For a private package, structurally valid skills are available to the personal owner or organization without AI processing.

For Pool and Marketplace packages:

1. The package version must first pass mandatory publication review.
2. Its skills then enter a dedicated security review.
3. Skills remain unavailable to consumers while review is pending.
4. Only approved skills are returned to consumers.

A flagged skill is withheld. A finding that indicates package-level malicious intent can also escalate the package version for further review.

If a new version carries the same semantic skill content as the previous version, the publish response warns the author to review the guidance for accuracy. The warning does not block publication.

Install package guidance

Installing a direct @lpm.dev/* dependency reconciles its approved skills by default:

lpm install @lpm.dev/acme.ui-kit

The installed set is written to:

.lpm/skills/acme.ui-kit/

Automatic reconciliation applies to direct LPM.dev Registry dependencies. It runs when the package is installed, upgraded, or removed.

Fetch or preview one package's guidance explicitly:

lpm skills add @lpm.dev/acme.ui-kit --dry-run
lpm skills add @lpm.dev/acme.ui-kit --yes

lpm skills install remains a compatibility alias for lpm skills add.

Configure automatic installation

Package skill installation is enabled by default. Change the persistent preference or override it for one command:

lpm config lpm-skills --set false
lpm install @lpm.dev/acme.ui-kit --no-skills
lpm install @lpm.dev/acme.ui-kit --skills

The setting affects future reconciliation. It does not delete skill files already present in the project and does not disable an explicit lpm skills add.

Clean installed package skills

Preview cleanup before applying it:

lpm skills clean --dry-run
lpm skills clean

Cleanup removes only package directories whose files still match a valid LPM CLI ownership manifest. It preserves publisher-authored files, modified or untracked content, invalid manifests, symlinks, standalone managed skills, and agent links.

Run lpm install again to restore package guidance that was removed.

Quality score

Package-published skills contribute up to 10 points to the quality score: 7 points for at least one skill and 3 additional points for three or more skills. Public consumer availability remains subject to the separate skill security review.