Skills

Skills are Markdown files with YAML frontmatter that provide custom instructions to the agent. They extend the agent's capabilities without modifying source code.

Overview

A skill is a Markdown document that gets included in the agent's system prompt. Skills can define specialized behaviors, coding conventions, review checklists, or any other instructions.

Skill Format

---
name: code-review
description: Performs thorough code reviews with security focus
---

# Code Review Skill

When reviewing code, follow these steps:

1. Check for security vulnerabilities (injection, XSS, CSRF)
2. Verify error handling and edge cases
3. Assess code readability and naming conventions
4. Look for performance issues
5. Check test coverage

Always provide specific line references and suggested fixes.

Frontmatter Fields

Name Validation

• Lowercase letters, numbers, and hyphens only
• Maximum 64 characters
• No consecutive hyphens
• If the skill is in a subdirectory, the name must match the directory name

Skill Discovery

The CLI automatically discovers skills from two locations:

Directory Structure

~/.pi/agent/skills/
├── code-review/
│   └── SKILL.md        # Skill in a subdirectory
├── security-audit/
│   └── SKILL.md
└── quick-fix.md        # Skill as a root-level file

Skills can be either:

• Root-level .md files — Any .md file in the skills directory
• Subdirectory SKILL.md files — A SKILL.md inside a named subdirectory

Loading Skills

Automatic discovery

Skills are loaded automatically from the default locations unless disabled:

# Skills are auto-discovered
epi

# Disable automatic discovery
epi --no-skills

Explicit loading

Load specific skill files or directories:

# Load a single skill file
epi --skill ./my-skills/review.md

# Load a skill directory
epi --skill ./my-skills/

# Load multiple skills
epi --skill ./skills/review.md --skill ./skills/deploy.md

Using Skills

Automatic invocation

By default, skills are visible to the model and it can choose to follow them based on the conversation context.

Manual invocation

In interactive mode, invoke a skill directly:

/skill:code-review

Listing skills

/skills

Skill Integration

Skills that are visible to the model are formatted as XML and appended to the system prompt:

<skills>
  <skill name="code-review">
    <description>Performs thorough code reviews with security focus</description>
    <content>
      # Code Review Skill
      When reviewing code, follow these steps:
      ...
    </content>
  </skill>
</skills>

Skills with disable-model-invocation: true are only available via explicit /skill:name invocation.

Name Collisions

If multiple skills share the same name (e.g., a user skill and a project skill), the CLI reports a diagnostic warning. The first-discovered skill takes priority.

Examples

Convention enforcement

---
name: project-conventions
description: Enforces project coding conventions
---

# Project Conventions

- Use TypeScript strict mode
- All functions must have JSDoc comments
- Use `camelCase` for variables and functions
- Use `PascalCase` for types and interfaces
- Maximum line length: 100 characters
- Use `const` by default, `let` only when reassignment is needed

Deployment checklist

---
name: deploy
description: Pre-deployment checklist and procedures
disable-model-invocation: true
---

# Deployment Checklist

Before deploying, verify:

1. All tests pass: `npm test`
2. Build succeeds: `npm run build`
3. No TypeScript errors: `npx tsc --noEmit`
4. Lint passes: `npm run lint`
5. Environment variables are set
6. Database migrations are ready