Agent Skills

Agent Skills are markdown files bundled inside your LPM package that give AI coding assistants context about how to use your library. When a developer installs your package's skills, their AI agent automatically loads the relevant instructions, patterns, and anti-patterns.

Skills live in .lpm/skills/*.md within your package.

How They Work

1. You author .md files in .lpm/skills/ with YAML frontmatter and markdown content
2. lpm publish extracts and validates skills from the tarball
3. After publishing, skills go through a security scan
4. Developers install skills with lpm skills install @lpm.dev/owner.package-name
5. Their AI coding agent picks up the installed skill files and uses them as context

File Format

Each skill file is a markdown file with required YAML frontmatter:

---
name: react-patterns
description: Idiomatic React patterns and hooks usage for this component library
globs:
  - "**/*.tsx"
  - "**/*.jsx"
---

## Component Composition

Always use the `compose` helper when combining multiple primitives:

\`\`\`jsx
import { compose } from "@lpm.dev/acme.ui-kit"

const MyButton = compose(Button, { variant: "primary", size: "md" })
\`\`\`

## Anti-patterns

- Do not wrap components in `React.memo` - the library handles memoization internally
- Never access `\_\_internal` exports - they change between versions without notice

Required Frontmatter

Field	Type	Rules
name	string	Kebab-case, 2-50 characters
description	string	10-200 characters

Optional Frontmatter

Field	Type	Purpose
globs	string[]	File patterns that determine when the skill is relevant (e.g., "**/*.tsx")

Body

The markdown body contains the actual skill content - instructions, patterns, code examples, and anti-patterns. Minimum 50 characters.

Validation Rules

Skills are validated at publish time with the following limits:

Rule	Limit
Skills per package	10
Max size per skill	50KB
Total skills size	500KB
Content minimum	50 characters
Description minimum	10 characters

Blocked Patterns

Skills cannot contain:

• Shell commands - rm -rf, chmod, chown, curl \| sh, wget \| bash
• Environment access - $HOME, $PATH, process.env, os.environ
• Prompt injection - "ignore previous instructions", "disregard safety", "forget your rules"

Any skill containing blocked patterns is rejected during publish validation.

Security Scanning

Skills go through two layers of security review:

1. Static validation at publish time - Checks blocked patterns, size limits, and frontmatter format. Fails the publish immediately if violated.
2. AI-powered security scan after publish - Detects prompt injection, dangerous command sequences, data exfiltration attempts, and obfuscated payloads that static patterns miss.

Skills start in a pending state and become approved after passing the AI security scan. Only approved skills are served to developers.

Quality Score Impact

Skills contribute to your package's quality score under the Package Health category:

Check	Points	Requirement
has-skills	7	At least 1 approved skill
skills-comprehensive	3	3 or more approved skills

Both checks are server-only - they run after publishing, not during lpm publish --check.

Staleness Detection

The server compares skills across versions. If your skills haven't changed between consecutive versions, a staleness warning is shown on the package page. This encourages keeping skill content up to date as your API evolves.

Including Skills in Your Package

1. Create the skills directory

your-package/
├── .lpm/
│   └── skills/
│       ├── getting-started.md
│       ├── react-patterns.md
│       └── migration-guide.md
├── src/
├── package.json
└── README.md

2. Update package.json (if using files field)

If your package.json uses the files field to control what gets published, add .lpm to the array:

{
  "files": ["dist", ".lpm"]
}

If you don't use the files field, .lpm is included by default.

3. Publish

lpm publish

The CLI extracts skills from the tarball, validates them against the rules above, and uploads them. After publishing, skills enter the security scan queue.

CLI Commands

Validate local skills

lpm skills validate

Runs the same checks as lpm publish without publishing. Use this in CI or before committing.

Install skills from a package

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

Downloads approved skills from the registry and places them where your AI coding agent can find them.

Skills are installed by default

lpm install @lpm.dev/acme.ui-kit
lpm install --no-skills @lpm.dev/acme.ui-kit  # Skip skills

When you install a package, skills are automatically fetched for any packages that include them. Use --no-skills to skip.

List available skills

lpm skills list

Shows skills available from your installed packages.

Remove installed skills

lpm skills clean

Removes all locally installed skill files.

Learn More

• AI Skills - LPM's own AI coding agent skill for building packages
• Quality Score - Full breakdown of all quality checks
• AI Metadata - How LPM generates AI-readable package metadata