lpm skills

lpm skills manages guidance from LPM.dev Registry packages and standalone skills from GitHub or local files.

lpm skills [OPTIONS] <COMMAND>
lpm skills add [OPTIONS] [SOURCE]
lpm skills list [OPTIONS]
lpm skills view [OPTIONS] <SELECTOR>
lpm skills dashboard [OPTIONS]
lpm skills validate
lpm skills clean [OPTIONS]
lpm skills doctor [OPTIONS]
lpm skills update [OPTIONS] [SKILL]...
lpm skills remove [OPTIONS] [SKILL]...
lpm skills enable [OPTIONS] [SKILL]...
lpm skills disable [OPTIONS] [SKILL]...
lpm skills prune [OPTIONS]

Quickstart

# Preview and install a package's published guidance
lpm skills add @lpm.dev/owner.package --dry-run
lpm skills add @lpm.dev/owner.package --yes

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

# Inspect the result
lpm skills list
lpm skills dashboard

Commands and ownership

Project commands act on the nearest directory with a package.json, as lpm install does. From a subdirectory, the command prints the directory it chose. Without a package.json above it, the command uses the current directory. A local source path that you pass to lpm skills add is relative to the current directory.

Package skills do not create agent links or change editor configuration. Standalone mutations do not change package skill sets or external skills. See AI agent skills for the ownership model.

Examples

lpm skills add @lpm.dev/owner.package@1.0.0 --list
lpm skills add owner/repository --skill release-notes --agent codex --global --yes
lpm skills list --kind managed --agent codex --global
lpm skills view owner.package/usage
lpm skills update release-notes --dry-run
lpm skills update release-notes --yes
lpm skills disable release-notes --agent cursor --yes
lpm skills clean --dry-run

A task in lpm.json

Neither lpm.json nor package.json > lpm has dedicated skill configuration. An uncached task can check authored package skills:

{
  "tasks": {
    "skills-check": {
      "command": "lpm skills validate",
      "cache": false
    }
  }
}

lpm run skills-check
lpm run skills-check -- --json

Extra arguments apply to that run. See lpm run. Automatic package skill installation uses a separate global preference, described below.

Package skills

Only @lpm.dev/owner.package inputs select package mode. An optional version must be exact. Tags and ranges are rejected. Without a version, the Registry selects the latest accessible release.

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

--list and --dry-run read the Registry without installing files. Package mode rejects --skill, --agent, --project, --global, --copy, and --full-depth. The package's approved skills form one installed set.

Private guidance requires publisher access. Stored sessions can recover from expired credentials, including concealed access denials. Public reads do not require a session refresh.

If the release's skills are not available, lpm skills add fails, names the review state, and keeps the installed set:

A flagged review with approved skills supplies its approved subset. A published empty set can remove an older, intact set.

If a set contains edited files, untracked files, symlinks, or an invalid ownership manifest, replacement stops. Back up and move the affected .lpm/skills/<owner.package>/ directory, then retry.

Automatic installation and overrides

lpm install installs skills for direct @lpm.dev/* dependencies by default, including aliases. It requests the exact resolved package version. Offline installation does not fetch skills. It also restores the skills of packages that lpm add delivered, at the version recorded in lpm-sources.json. A package that is also a direct dependency uses the dependency's version.

Package skills never fail an installation. A fetch error, an unavailable review state from the table above, an unsafe skill name, or locally edited skill files produce a warning, and the skills already in .lpm/skills/ stay. JSON output lists these messages in warnings. After a --no-skills upgrade, an enabled online installation refreshes stale guidance even if package files are current. If direct aliases select several versions of one package, the shared guidance directory uses the highest selected version.

lpm config lpm-skills --set false
lpm install --skills
lpm install --no-skills

The global key is auto-install-lpm-skills in ${LPM_HOME:-~/.lpm}/config.toml. Its default is true. The legacy noSkills preference applies only if the current key is absent.

--skills and --no-skills override the preference for one installation. They also apply to lpm add and lpm ci. The preference does not remove existing files or affect explicit skill commands. See lpm config.

An installation does not remove a package's skill directory when the package stops being a dependency. lpm uninstall removes an intact set after the last direct dependency or alias on the package goes. lpm remove removes the skills of a package that lpm add delivered, unless the package is still a dependency.

Clean package skill sets

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

clean removes only sets whose files and digests match their ownership manifest. It preserves Markdown files directly under .lpm/skills/, modified or untracked content, invalid manifests, symlinks, managed standalone content, and agent targets. A dry run does not create a lock file or project directories.

Interactive cleanup defaults to No. Unattended cleanup requires --yes. Run lpm install to restore removed sets.

Standalone sources and agent targets

Standalone sources can be local directories, local SKILL.md files, or GitHub repositories. GitHub accepts owner/repository shorthand and HTTPS repository, tree, or SKILL.md blob URLs.

lpm skills add ./team-skills --list
lpm skills add ./team-skills/release-notes/SKILL.md --agent codex --project --yes
lpm skills add owner/repository --skill release-notes --agent codex --global --yes

For private GitHub sources, GH_TOKEN takes precedence over GITHUB_TOKEN. LPM CLI sends this credential only to the GitHub API, not the archive download host.

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

Interactive add asks for the source, selection, scope, targets, security review, and confirmation. An unattended run needs a source, scope, agents, unambiguous skill selection, and --yes. JSON mode disables prompts.

lpm skills add ./team-skills \
  --skill release-notes \
  --agent codex --agent claude-code \
  --project --yes --json

Storage and compatibility

The project record lists each skill's source, revision, and agent targets with / paths. A local source inside the project is recorded as a ./ path. LPM CLI removes the record when the last project skill goes. A record in .lpm/managed-skills/skills.lock.json from an earlier release is read and replaced on the next write.

An online lpm install restores the project skills that this checkout lacks, with their enabled agent targets. A GitHub source is fetched at its recorded commit. A local source is used only while its content still has the recorded digest. A skill that cannot be restored produces an installation warning. If its source no longer has the recorded revision, run lpm skills update to take the current content. --no-skills skips this restore, as it skips package skills. An unreadable lpm-agent-skills.json also produces a warning rather than an installation failure. See Files LPM CLI creates for what to commit.

Global paths honor CODEX_HOME, GROK_HOME, XDG_CONFIG_HOME, and PI_CODING_AGENT_DIR for the corresponding agents. Links are the default. --copy creates copies, and Windows can fall back to copies if symlink creation is unavailable.

Agent-specific frontmatter restricts compatible targets. Re-adding a skill checks all enabled targets that will receive its new content, including retained targets. Enabling a disabled target checks the current stored content before restoring it.

Warning-level security findings require confirmation. Blocking findings prevent installation and updates. Previews can show blocked candidates without applying them.

Update, disable, enable, and remove

lpm skills update release-notes --dry-run
lpm skills update release-notes --yes
lpm skills disable release-notes --agent codex --yes
lpm skills enable release-notes --agent codex --yes
lpm skills remove release-notes --agent codex --yes
lpm skills prune --dry-run
lpm skills prune --yes

update reads the original local path or resolves the recorded GitHub reference again. It shows a bounded content diff and security changes before it refreshes content and enabled targets. Skills from the same source and reference use one source snapshot per update operation.

disable removes selected targets and retains stored content and records. enable restores recorded targets only. It does not add a new agent selection. remove deletes stored content after the last recorded target is removed.

These commands require skill names or --all. --all takes precedence over names. --global selects only the global store for mutations. update rejects --agent because enabled targets share the updated content.

If an external file replaces a managed target, mutation stops before replacement. Use doctor to inspect its path and ownership before moving files. If managed content is missing, update can restore it from the original source.

Managed view and update previews bound file size, total size, entry count, and directory depth.

Oversized or unsafe stored content returns an error. The dashboard instead marks content as unavailable. list and doctor do not check these content limits. Large diffs can show an excerpt or a size summary.

If altered stored files exceed a limit, back up your changes before removing the managed skill. Then add it again from a trusted source.

Inspect skills and diagnose targets

lpm skills list --global
lpm skills list --kind package
lpm skills list --kind managed --agent codex
lpm skills view release-notes --global
lpm skills view owner.package/usage
lpm skills doctor --global

For list, view, and doctor, --global adds global locations to the project inventory. Project managed names take precedence over matching global names. list --agent filters managed and external entries. Package entries remain unless --kind excludes them.

Managed and external view results include source, security, context, and target details. Package view reports names, paths, and sizes. The dashboard provides full package content and metadata.

doctor can exit successfully while its report contains unhealthy targets. For a CI health gate, inspect the JSON field:

set -o pipefail
lpm skills doctor --global --json | jq -e '.healthy'

Publish package guidance

Author direct Markdown files in lpm-skills/ at the package root, next to package.json, and commit them:

lpm-skills/
├── usage.md
└── migration.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 documented error handling and configuration rules when you change an existing integration.

lpm skills validate --json
lpm publish

Quote numeric-looking names and versions to retain string values. Folded and literal YAML descriptions are supported.

LPM.dev Registry checks uploaded skills with the same validator, so a skill that passes lpm skills validate also passes the upload check. Registry security review happens after upload. Markdown files left directly in .lpm/skills/ by earlier releases fail validation with a message to move them to lpm-skills/. Installed package sets in .lpm/skills/<owner.package>/ are not checked.

lpm publish validates the skills and ships the valid files at lpm-skills/ in the tarball, whatever package.json > files lists. Other files in lpm-skills/ are not published. Publishing does not edit package.json > files. When lpm add copies a package without lpm.config.json, it leaves out lpm-skills/. For @lpm.dev/* packages, lpm add installs the published skills in .lpm/skills/ instead.

The optional skill version describes its guidance independently of the package release that carries it. An older value remains visible after a later package release. See the package-skill authoring guide.

Local dashboard

lpm skills dashboard --read-only
lpm skills dashboard --no-open --port 4401

The dashboard includes project and global skills. It binds only to 127.0.0.1. An explicit port must be between 1 and 65535. Without --port, the command selects a free port.

The dashboard shows content, metadata, files, context estimates, integrity, security findings, and target health. Package and external entries support inspection only. Managed entries support reviewed enable, disable, update, and remove operations. --read-only disables mutations.

Each mutation uses an expiring, single-use plan. The server checks its authentication token, Host, and Origin. The launch URL carries its token in a fragment, which the dashboard removes after startup.

Multiple external links to one directory form one entry with several targets. Broken links remain visible with their paths and missing-target status.

--no-open prints the authenticated URL without opening a browser. JSON mode also suppresses browser opening, emits a startup object, and keeps the server running. Keep the command running while you use the dashboard. Press Ctrl+C to stop it.

Flags

See Global flags for Registry and authentication overrides.

See also

• AI agent skills — ownership, lifecycle, and security.
• lpm install — automatic package skill installation.
• lpm publish — publish package guidance.
• lpm config — automatic installation preferences.
• MCP servers — agent tool integrations.