AI agent skills

Agent skills are Markdown instructions that explain how to use a package or perform a task. LPM CLI manages package guidance and standalone skills through lpm skills.

Two systems, one command

Both systems can coexist. Their ownership records separate installed guidance, authored package files, and standalone content. Neither system has dedicated lpm.json configuration. A task can run a skill command, as shown in the command reference.

Quickstart

# Install a direct dependency and its approved package guidance
lpm install @lpm.dev/owner.package

# Preview a standalone skill for Codex
lpm skills add ./team-skills --skill release-notes --agent codex --project --dry-run

# Install the reviewed selection without prompts
lpm skills add ./team-skills --skill release-notes --agent codex --project --yes

# Inspect both kinds
lpm skills list
lpm skills dashboard

Project skill commands act on the nearest directory with a package.json, as lpm install does, and print the directory they chose when it is not the current one. .lpm/ holds the installed content and stays out of Git. See Files LPM CLI creates for what to commit. Package guidance stays in .lpm/skills/<owner.package>/ without editor configuration changes. Tell your agent where to read it:

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

Use guidance from an LPM.dev package

An online lpm install fetches approved skills for direct LPM.dev Registry dependencies, including aliases. It requests the selected package version, not a separate latest release.

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

The ownership manifest records the package version and file digests. LPM CLI uses it to detect local changes before replacement or removal. Do not edit the manifest.

Automatic reconciliation

Online project installations reconcile the owned directory with the selected release's approved skill set. An upgrade can add, replace, or remove guidance files. Installations keep a package's directory when the package stops being a dependency. lpm uninstall of the final direct dependency or alias removes its intact owned directory. Offline installations do not fetch skills. Global package installations disable automatic skill installation.

Packages delivered by lpm add are recorded in lpm-sources.json. An online installation restores their skills at the recorded version, unless the package is also a direct dependency.

Skills never fail an installation. If a release's skills are under review, failed or rejected review, cannot be fetched, have an unsafe name, or would replace locally edited files, the installation warns and keeps the existing set. JSON installation output lists these messages in warnings.

# Disable automatic fetching persistently
lpm config lpm-skills --set false

# Override the preference for one installation
lpm install --skills
lpm install --no-skills

The preference order is the invocation's --skills or --no-skills, then auto-install-lpm-skills, then the legacy noSkills fallback. The default is enabled. The same invocation flags apply to lpm add and lpm ci. See lpm config for the stored preference.

Disabling automatic fetching preserves existing guidance. After an upgrade with --no-skills, the next enabled online installation replaces stale guidance with the selected version's set. This also applies when package files are already up to date.

Several direct aliases can select different versions of one package. Their shared guidance directory uses the highest selected version, with the same selection on subsequent installations.

Explicit retrieval

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

The optional version must be exact. Without it, the Registry selects the latest accessible release independently of installed dependencies. Explicit retrieval works even if automatic fetching is disabled. A later enabled installation restores guidance for its selected dependency version.

Anonymous users can read approved guidance for Free packages. Private guidance requires publisher access. If the release's skills are pending or processing review, failed or rejected review, or flagged without an approved skill, retrieval fails, names that review state, and preserves the existing set. A partially flagged review can supply its approved subset. An approved empty set removes older, intact guidance files.

Safe package cleanup

lpm skills clean --dry-run
lpm skills clean --yes

Cleanup removes only package sets whose files and digests match a valid ownership manifest. It preserves direct publisher files, edited or untracked content, invalid manifests, symlinks, standalone skills, and agent targets. Interactive cleanup defaults to No. Scripts require --yes. An enabled online installation restores removed package guidance.

If local changes or an invalid manifest prevent replacement or removal, back up the affected directory. Move that directory out of .lpm/skills/, then retry the command. Dependency installation and source-package addition report a warning and preserve the directory. lpm skills add, lpm uninstall, and lpm remove report an error.

Publish guidance with an LPM.dev package

Place authored Markdown files directly in lpm-skills/ at the package root and commit them:

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

Markdown in a subdirectory, such as lpm-skills/guides/usage.md, and symlinks are rejected. Each file has YAML frontmatter and 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 and initialize it once. Reuse that instance for related requests. Handle documented errors at the application boundary. When the application stops, close the client.

The authored version field is separate from the package version recorded in the installed ownership manifest. A later package release can carry unchanged guidance with its original authored version.

lpm skills validate
lpm publish --check
lpm publish

Validation checks the package-skill contract and security rules. LPM.dev Registry checks uploaded skills with the same validator. Markdown files left directly in .lpm/skills/ by earlier releases fail validation with a message to move them.

lpm publish ships the validated files at lpm-skills/ in the tarball for every target, whatever package.json > files lists. It does not edit files. Other files in lpm-skills/ are not published. Tarballs never contain .lpm/, so installed dependency skill sets never ship. The final artifact receives the same secret scan as other published content, including for other registries.

Manage standalone skills

Standalone sources accept local directories, local SKILL.md files, GitHub shorthand, and HTTPS repository, tree, or SKILL.md blob URLs.

lpm skills add owner/repository --list
lpm skills add ./team-skills/release-notes/SKILL.md --list
lpm skills add https://github.com/owner/repository/tree/main/skills --list

lpm skills add owner/repository \
  --skill release-notes \
  --agent codex --agent claude-code \
  --project --yes

Discovery searches standard skill layouts. --full-depth includes other locations. --skill '*' selects all discovered skills. Repeated --skill and --agent flags select several names or targets.

Interactive addition asks for source, skill selection, scope, agent targets, security review, and confirmation. For scripts, provide those choices and --yes after reviewing --dry-run. Global --json disables prompts. lpm skills install is a compatibility alias for add.

Storage and targets

Project content lives under .lpm/managed-skills/. Its ownership record is lpm-agent-skills.json at the project root, which you commit. Global content and its skills.lock.json record live under ${LPM_HOME:-~/.lpm}/managed-skills/. A project record that an earlier release kept in .lpm/managed-skills/skills.lock.json is read and replaced on the next write.

On a fresh checkout, an online lpm install restores the recorded project skills and their enabled agent targets. GitHub sources are fetched at the recorded commit. Local sources are used only while their content matches the recorded digest. Anything that cannot be restored becomes an installation warning. If a source no longer has the recorded revision, run lpm skills update to take its current content.

Global targets honor CODEX_HOME, GROK_HOME, XDG_CONFIG_HOME, and PI_CODING_AGENT_DIR for the corresponding agents. Project links are relative and remain usable when the project moves. Where Git checks out a committed link as a plain file, as on Windows with core.symlinks off, lpm skills doctor reports the target as a link placeholder once the skill's content is in .lpm/ (in a fresh clone, before any install, it reports that content as canonical missing), and the next online lpm install restores the content and replaces the placeholder with the link. --copy creates copies. Windows can fall back to copies if symlink creation is unavailable. Agent-specific frontmatter can restrict compatible targets.

Source and security boundary

GitHub sources require HTTPS. LPM CLI resolves a branch, tag, or commit ref to a commit before each download. GH_TOKEN takes precedence over GITHUB_TOKEN. The credential goes only to the GitHub API, not the archive host.

Remote limits include a 20 MiB download, 64 MiB expanded content, 500 archive entries, and bounded paths with 12 directory levels. Traversal paths are rejected. A URL subpath limits which skill trees discovery examines. Within discovered skill trees, links, special entries, and regular files larger than 1 MiB are rejected. Unrelated archive entries outside those trees do not automatically invalidate a source. All discovered skill trees receive these checks before --skill selection.

Local sources exclude .git and reject symlinks, special files, or oversized regular files throughout the selected source root. Local limits also include 500 files, 64 MiB total content, and 12 directory levels. A local source can't hold what adding it writes, so the project root or a directory containing .lpm/, lpm-agent-skills.json, or a selected agent target is rejected. Keep skills in a directory of their own, such as ./skills.

LPM CLI scans skill content for prompt injection, secret access, exfiltration, downloaded shell execution, and destructive filesystem instructions.

Updates and review

lpm skills update release-notes --dry-run
lpm skills update release-notes --yes
lpm skills disable release-notes --agent cursor --yes
lpm skills enable release-notes --agent cursor --yes

An update reads the original source again. Branches and movable tags can resolve to a newer commit. Local sources reflect current files. Each downloaded revision is pinned for that installation. A later update can advance it.

The dry run shows a bounded diff and identifies new findings by rule, severity, file, and line. Binary auxiliary files remain intact and appear by SHA-256 digest in the diff. LPM CLI checks target compatibility before replacement or re-enabling.

Unified inventory and lifecycle

lpm skills list
lpm skills view owner.package/usage
lpm skills view release-notes
lpm skills doctor
lpm skills dashboard
lpm skills prune --dry-run

Inventory uses package, managed, and external ownership kinds. External skills exist in agent directories but have no LPM CLI ownership record.

Package view reports the package, skill name, and file size. Its text output also shows the path. Managed view reports source, stored context estimate, current security findings, and target status. It does not check the canonical content against a stored digest.

doctor checks canonical-directory existence, target ownership and status, disabled targets, and broken external links. It does not check canonical content digests. prune --dry-run previews stale targets and records before cleanup.

The local dashboard combines project and global discovery. Its source and needs attention filters narrow the inventory. Selecting a skill shows raw Markdown, a rendered body, a bounded file tree, and metadata. External aliases to one canonical directory appear as one item with several agent targets. Broken aliases remain visible.

Dashboard mutations apply only to managed standalone skills. Package and external skills are inspection-only. Agent labels show configured targets, not observed use. Context estimates do not measure session or billing usage.

Global --json emits one structured result, including successful zero-count operations. A successful empty result does not imply that files changed.

See also

• lpm skills — full syntax, flags, and command examples
• lpm install — automatic package guidance and invocation overrides
• lpm publish — publish authored package skills
• lpm config — automatic skill preference
• MCP servers — tools available to an agent