Creating Skills

Skills are markdown files with YAML frontmatter that provide reusable instructions for the AI. This guide covers how to create custom skills for LLPM.

Skill Structure

Each skill is a markdown file named SKILL.md inside a directory named after the skill:

~/.llpm/skills/
  my-skill/
    SKILL.md

The SKILL.md file has two parts:

YAML Frontmatter - Metadata about the skill
Markdown Body - Instructions for the AI

Frontmatter Fields

Field	Required	Description
`name`	Yes	Unique identifier for the skill (kebab-case)
`description`	Yes	Brief summary of what the skill does
`license`	No	License identifier for the skill
`compatibility`	No	Environment requirements (products, packages, network access)
`metadata`	No	Arbitrary string-to-string mapping for additional properties
`allowed-tools`	No	Space-delimited list of pre-approved tools (experimental)

Example Frontmatter

---
name: code-review
description: "Review code changes for quality, security, and best practices"
license: "Apache-2.0"
compatibility: "Requires network access"
metadata:
  category: "review"
allowed-tools: "Read"
---

Markdown Body

The body contains instructions the AI follows when the skill is active. Structure your instructions clearly:

# Skill Name

Brief description of what this skill does.

## When to Use

List the triggers or situations when this skill should activate:
- "Review this PR"
- "Check this code for issues"
- When analyzing code changes

## Available Tools

| Tool | Purpose |
|------|---------|
| `tool_name` | What it does |

## Workflow

Step-by-step instructions for the AI:

### Step 1: Gather Context
...

### Step 2: Analyze
...

### Step 3: Report
...

## Output Format

[Template or example of expected output]

## Best Practices

- Guideline 1
- Guideline 2

Skill Locations

LLPM discovers skills from three locations (in priority order):

Location	Purpose	Example
`~/.llpm/skills/`	User-installed skills shared across projects	Global utilities
`.skills/`	Project-specific skills	Project conventions
Built-in	Default LLPM skills	Core functionality

When skills have the same name, higher-priority locations win.

Complete Example

Here is a complete skill for generating release notes:

---
name: release-notes
description: "Generate release notes from merged PRs and closed issues"
allowed-tools: "Read"
---

# Release Notes Skill

Generate release notes by analyzing merged PRs and closed issues since the last release.

## When to Use

Activate when:
- Preparing a new release
- Generating changelog entries
- Summarizing changes between versions

## Available Tools

| Tool | Purpose |
|------|---------|
| `tool_name` | Description of what the tool does |

## Workflow

### Step 1: Identify Scope

Ask the user:
- What is the new version number?
- Since which tag/release should we include changes?

### Step 2: Gather Changes

Search for:
- Merged PRs since last release
- Closed issues with `changelog` label
- Breaking changes labeled `breaking`

### Step 3: Categorize

Group changes into:
- **Features** - New functionality
- **Fixes** - Bug fixes
- **Breaking** - Breaking changes
- **Docs** - Documentation updates
- **Other** - Maintenance, dependencies

### Step 4: Generate Notes

## Output Format

```markdown
# Release [version] - [date]

## Features
- [Feature description] (#PR)

## Fixes
- [Fix description] (#PR)

## Breaking Changes
- [Change description] - Migration: [steps]

## Documentation
- [Doc update] (#PR)

Best Practices

Lead with breaking changes so users see them first
Include PR/issue numbers for traceability
Write user-focused descriptions, not commit messages
Add migration steps for breaking changes


## Best Practices

### Clear Triggers

Be explicit about when the skill should activate:

```markdown
## When to Use

Activate when:
- User says "generate release notes"
- User asks "what changed since [version]"
- Preparing for a release

Focused Scope

Keep skills focused on one task. Instead of one large “project management” skill, create separate skills for:

Issue triage
Sprint planning
Stakeholder updates
Risk detection

Practical Examples

Include example inputs and outputs so the AI understands the expected format:

## Example

**User**: "Generate release notes for v2.0"

**Output**:
# Release 2.0.0 - 2025-01-15

## Features
- Added dark mode support (#142)
- New export to PDF feature (#156)
...

Tool Documentation

If the skill uses tools, document what each tool does and when to use it:

## Available Tools

| Tool | Purpose | When to Use |
|------|---------|-------------|
| `tool_name` | What it does | When it is needed |

Testing Skills

Before deploying a skill, test it:

# Preview skill content
/skills test my-skill

# Enable and try it
/skills enable my-skill

# Ask the AI to use it
"Use the my-skill skill to..."

Verify:

The skill activates on expected triggers
The AI follows the workflow correctly
Output matches the expected format
Tools are used appropriately

Sharing Skills

Skills can be shared by:

Copying the skill directory to another user’s ~/.llpm/skills/
Adding to a project’s .skills/ directory for team sharing
Publishing to a skills repository

Because LLPM uses the Agent Skills standard, skills are compatible with other systems that support this format.

Planning Skills Visualization Skills