Skills

Agent Skills standard support - on-demand capability packages with workflows and documentation

Pi can create skills for you. Just ask it to build one for your use case.

Skills are self-contained capability packages that the agent loads on-demand. A skill provides specialized workflows, setup instructions, helper scripts, and reference documentation for specific tasks.

Pi implements the Agent Skills standard, warning about violations but remaining lenient.

How Skills Work

1. Discovery

   At startup, Pi scans skill locations and extracts names and descriptions

2. System Prompt

   Available skills are included in the system prompt in XML format per the specification

3. On-Demand Loading

   When a task matches, the agent uses read to load the full SKILL.md

   (Models don’t always do this automatically - use prompting or /skill:name to force it)

4. Execution

   The agent follows the instructions, using relative paths to reference scripts and assets

This is progressive disclosure: only descriptions are always in context, full instructions load on-demand.

Skill Locations

Skills can instruct the model to perform any action and may include executable code. Review skill content before use.

Pi loads skills from:

Global:

• ~/.pi/agent/skills/
• ~/.agents/skills/

Project:

• .pi/skills/
• .agents/skills/ in cwd and ancestor directories (up to git repo root)

Packages:

• skills/ directories in pi packages
• pi.skills entries in package.json

Settings:

• skills array with files or directories

CLI:

• --skill <path> (repeatable, additive even with --no-skills)

Discovery Rules

• Direct .md files in the skills directory root
• Recursive SKILL.md files under subdirectories

Disable discovery with --no-skills (explicit --skill paths still load).

Using Skills from Other Harnesses

To use skills from Claude Code or OpenAI Codex, add their directories:

{
  "skills": [
    "~/.claude/skills",
    "~/.codex/skills"
  ]
}

For project-level Claude Code skills:

{
  "skills": ["../.claude/skills"]
}

Skill Commands

Skills register as /skill:name commands:

/skill:brave-search           # Load and execute the skill
/skill:pdf-tools extract      # Load skill with arguments

Arguments after the command are appended to the skill content as User: <args>.

Toggle skill commands:

Interactive

Use /settings to toggle skill commands

settings.json

{
  "enableSkillCommands": true
}

Skill Structure

A skill is a directory with a SKILL.md file. Everything else is freeform.

my-skill/
├── SKILL.md              # Required: frontmatter + instructions
├── scripts/              # Helper scripts
│   └── process.sh
├── references/           # Detailed docs loaded on-demand
│   └── api-reference.md
└── assets/
    └── template.json

SKILL.md Format

---
name: my-skill
description: What this skill does and when to use it. Be specific.
---

# My Skill

## Setup

Run once before first use:
\`\`\`bash
cd /path/to/skill && npm install
\`\`\`

## Usage

\`\`\`bash
./scripts/process.sh <input>
\`\`\`

Use relative paths from the skill directory:

See [the reference guide](references/REFERENCE.md) for details.

Frontmatter

Per the Agent Skills specification:

name · string · required

Max 64 chars. Lowercase a-z, 0-9, hyphens. Must match parent directory.

Valid: pdf-processing, data-analysis, code-review

Invalid: PDF-Processing, -pdf, pdf--processing

description · string · required

Max 1024 chars. What the skill does and when to use it.

Be specific - this determines when the agent loads the skill.

license · string

License name or reference to bundled file

compatibility · string

Max 500 chars. Environment requirements

metadata · object

Arbitrary key-value mapping

allowed-tools · string

Space-delimited list of pre-approved tools (experimental)

disable-model-invocation · boolean

When true, skill is hidden from system prompt. Users must use /skill:name

Name Rules

• 1-64 characters
• Lowercase letters, numbers, hyphens only
• No leading/trailing hyphens
• No consecutive hyphens
• Must match parent directory name

Description Best Practices

The description determines when the agent loads the skill. Be specific.

Good

---
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents.
---

---
description: Helps with PDFs.
---

Validation

Pi validates skills against the Agent Skills standard. Most issues produce warnings but still load the skill:

• Name doesn’t match parent directory
• Name exceeds 64 characters or contains invalid characters
• Name starts/ends with hyphen or has consecutive hyphens
• Description exceeds 1024 characters

Unknown frontmatter fields are ignored.

Exception: Skills with missing description are not loaded.

Name collisions (same name from different locations) warn and keep the first skill found.

Example Skill

Complete example: brave-search/

brave-search/
├── SKILL.md
├── search.js
└── content.js

SKILL.md:

---
name: brave-search
description: Web search and content extraction via Brave Search API. Use for searching documentation, facts, or any web content.
---

# Brave Search

## Setup

\`\`\`bash
cd /path/to/brave-search && npm install
\`\`\`

## Search

\`\`\`bash
./search.js "query"              # Basic search
./search.js "query" --content    # Include page content
\`\`\`

## Extract Page Content

\`\`\`bash
./content.js https://example.com
\`\`\`

The agent can now:

1. Read the skill when needed
2. Run setup if required
3. Execute searches using the documented commands
4. Reference the scripts with relative paths

Skill Repositories

Public skill repositories:

Anthropic Skills

Document processing (docx, pdf, pptx, xlsx), web development

Pi Skills

Web search, browser automation, Google APIs, transcription

Installing Skills

Via Packages

Install skill packages via npm or git:

pi install npm:pi-skills
pi install git:github.com/badlogic/pi-skills

See Pi Packages for details.

Manual

Clone or copy skills to a skills directory:

git clone https://github.com/badlogic/pi-skills ~/.pi/agent/skills/pi-skills

Via Settings

Point to external skill directories:

{
  "skills": [
    "~/shared-skills",
    "../team-skills"
  ]
}

Creating Skills

1. Create Directory

   mkdir -p ~/.pi/agent/skills/my-skill
   cd ~/.pi/agent/skills/my-skill
   
2. Write SKILL.md

   ---
   name: my-skill
   description: Your skill description
   ---
   
   # My Skill
   
   Instructions here...
   
3. Add Scripts

   mkdir scripts
   echo '#!/bin/bash\necho "Hello"' > scripts/hello.sh
   chmod +x scripts/hello.sh
   
4. Test

   pi
   /skill:my-skill
   

Best Practices

Write clear descriptions

The description is the most important part. It tells the agent when to use the skill.

Include:

• What the skill does
• When to use it
• What problems it solves

Avoid:

• Vague descriptions
• Generic terms
• Missing use cases

Document setup clearly

If the skill requires setup (npm install, API keys, etc.), document it clearly in a Setup section.

The agent should be able to:

• Detect if setup is needed
• Run setup commands
• Verify setup succeeded

Use relative paths

Always use paths relative to the skill directory:

./scripts/process.sh
[Reference](references/api.md)

This ensures the skill works regardless of where it’s installed.

Include examples

Show concrete examples of how to use the skill:

## Example

Search for Node.js documentation:
\`\`\`bash
./search.js "node.js async/await"
\`\`\`

Provide reference docs

For complex skills, include detailed reference documentation that the agent can load on-demand:

my-skill/
├── SKILL.md          # Quick start
└── references/
    ├── API.md        # Detailed API docs
    └── EXAMPLES.md   # More examples

Sharing Skills

Package skills for others to use:

1. Create package.json

   {
     "name": "my-skills",
     "keywords": ["pi-package", "agent-skills"],
     "pi": {
       "skills": ["./skills"]
     }
   }
   
2. Publish

   npm publish
   

   Or push to GitHub for git-based installation.

3. Users Install

   pi install npm:my-skills
   

See Pi Packages for full packaging details.

Next Steps

Extensions

Build TypeScript extensions for more complex integrations

Pi Packages

Package and share skills via npm or git