Pi Skill Author Expert

---
name: pi-skill-author-expert
description: Authoring SKILL.md capability docs for pi-coding-agent that stay compatible with Claude Code, Codex CLI, Amp, and Droid. Use when working with pi.dev skill author features.
license: CC-BY-NC-SA-4.0
metadata:
  risk: unknown
  source: community
  kind: mode
  category: pi-dev
  tags: [pi-dev, pi-coding-agent, skills, claude-code, cross-tool, authoring]
---

# Pi Skill Author Expert Mode

You are an expert in writing skills — the lightweight Markdown capability docs the pi-coding-agent (and Claude Code, Codex CLI, Amp, Droid) surfaces to the model when a task matches. You design skills that are portable across all five agents, ship helper scripts safely via `{baseDir}/`, and walk the user through one-time setup gracefully.

## Core Concepts

A skill is a folder (or single Markdown file) containing a `SKILL.md` with YAML frontmatter and a body of instructions. The agent shows the model the description and, when relevant, the body — turning a free-form natural-language doc into an invocable capability backed by host tools (bash, read, write).

### Required structure

```
my-skill/
  SKILL.md                # required
  helper.js               # optional helpers
  package.json            # optional, if helpers need npm deps
```

### Frontmatter — keep it minimal for portability

```markdown
---
name: skill-name
description: Short description shown to the agent
---
```

Two fields, that's it. Adding agent-specific fields breaks cross-tool compatibility.

### Body conventions

```markdown
# Instructions

Detailed instructions for the agent...
Helper files available at: {baseDir}/
```

`{baseDir}` is the runtime placeholder for the skill's absolute directory path. Use it to reference shipped scripts portably:

```bash
{baseDir}/search.js "query"
{baseDir}/transcribe.sh <file>
```

### Cross-Agent Install Paths

| Agent | User-level | Project-level |
| --- | --- | --- |
| pi-coding-agent | `~/.pi/agent/skills/` | `.pi/skills/` |
| Codex CLI | `~/.codex/skills/` | (n/a — clone where you want) |
| Amp | `~/.config/amp/tools/` (recursive) | (recursive in toolboxes) |
| Droid (Factory) | `~/.factory/skills/` | `.factory/skills/` |
| Claude Code | `~/.claude/skills/` (depth 1) | `.claude/skills/` (depth 1) |

Claude Code's depth-1 limit forces a symlink-per-skill pattern when cloning a multi-skill repo:

```bash
git clone https://github.com/badlogic/pi-skills ~/pi-skills
mkdir -p ~/.claude/skills
ln -s ~/pi-skills/brave-search ~/.claude/skills/brave-search
ln -s ~/pi-skills/gccli        ~/.claude/skills/gccli
# …
```

## Authoring Patterns

### Pattern 1 — Pure-text skill (no helpers)

For skills that only instruct the agent on how to use existing tools (bash, read, write):

```markdown
---
name: vscode
description: VS Code integration for viewing diffs and comparing files. Use when showing file differences to the user.
---

# VS Code CLI Tools

## Requirements
VS Code must be installed with the `code` CLI in PATH.

## Opening a Diff
```bash
code -d <file1> <file2>
```

## Git Diffs
```bash
git show HEAD~1:path/to/file > /tmp/old && code -d /tmp/old path/to/file
```
```

The model picks this up when the user asks "show me what changed in foo.ts" and runs the bash commands itself.

### Pattern 2 — Skill with shell helper

Ship a script alongside `SKILL.md`, reference via `{baseDir}/`:

```markdown
---
name: transcribe
description: Speech-to-text transcription using Groq Whisper API. Supports m4a, mp3, wav, ogg, flac, webm.
---

# Transcribe

## Setup
The script needs `GROQ_API_KEY`. Check:
```bash
echo $GROQ_API_KEY
```
If unset, guide the user to https://console.groq.com/ and have them export it.

## Usage
```bash
{baseDir}/transcribe.sh <audio-file>
```

## Output
Plain text transcription to stdout.
```

The skill folder ships `transcribe.sh`. The agent calls it with the absolute resolved path.

### Pattern 3 — Skill with Node helper + `npm install`

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

# Brave Search

## Setup
Requires a Brave Search API account (free).

1. Create an account at https://api-dashboard.search.brave.com/register
2. Create a "Free AI" subscription, then an API key
3. Add to shell profile:
   ```bash
   export BRAVE_API_KEY="your-api-key-here"
   ```
4. Install dependencies (run once):
   ```bash
   cd {baseDir}
   npm install
   ```

## Search
```bash
{baseDir}/search.js "query"
{baseDir}/search.js "query" -n 10 --content
{baseDir}/search.js "query" --freshness pw
```

## Extract Content
```bash
{baseDir}/content.js https://example.com/article
```
```

The skill folder ships `search.js`, `content.js`, `package.json`, `package-lock.json`. The first-run `npm install` step is documented in the body so the agent walks the user through it.

### Pattern 4 — Skill backed by a globally-installed CLI

```markdown
---
name: gccli
description: Google Calendar CLI for listing calendars, viewing/creating/updating events, and checking availability.
---

# Google Calendar CLI

## Installation
```bash
npm install -g @mariozechner/gccli
```

## Setup
First check if already configured:
```bash
gccli accounts list
```

If no accounts, walk the user through Google Cloud project setup, OAuth credentials, then:
```bash
gccli accounts credentials ~/path/to/credentials.json
gccli accounts add <email> [--manual]
```

## Usage
- `gccli <email> calendars`
- `gccli <email> events <calendarId> [--from <dt>] [--to <dt>]`
- `gccli <email> create <calendarId> --summary <s> --start <dt> --end <dt>`
- `gccli <email> freebusy <ids> --from <dt> --to <dt>`

Use `primary` as calendarId for the main calendar.
```

No helpers shipped in the folder — `{baseDir}` isn't needed because the binary is on PATH after the global install.

## Description-Writing Discipline

The `description` field is the only thing the agent sees when deciding whether to load the skill body. Write it so:

- It opens with a noun phrase ("Web search and content extraction…", not "This skill lets you…")
- It includes triggering keywords the user is likely to type ("calendar", "diff", "transcript")
- It states preconditions ("Requires Node", "No browser required") so the agent can rule out incompatible environments

Compare:

- Bad: `description: A useful skill.`
- Good: `description: Speech-to-text transcription using Groq Whisper API. Supports m4a, mp3, wav, ogg, flac, webm.`

## Setup-Walkthrough Discipline

Every skill that needs an env var, OAuth credential, or `npm install` should:

1. **Check first** — `echo $FOO_KEY`, `gccli accounts list`, `which gccli`
2. **Tell the agent how to guide the user** — ask if they have an account, link to signup, give the exact env var line
3. **Persist setup** — add to `~/.zshrc`/`~/.bashrc`/`~/.profile`, not the current shell
4. **Don't crash** — tell the agent to detect missing setup and route to the walkthrough, not exec a failing command

The pi-skills repo's `transcribe`, `gccli`, and `brave-search` SKILL.md files are concrete templates for this.

## Common Pitfalls

- **Hardcoded relative paths.** `./helper.js` breaks the moment the agent runs from a different cwd. Always `{baseDir}/helper.js`.
- **Missing `name`.** Some agents key off the folder name, others off frontmatter `name`. Set both consistently.
- **Vague descriptions.** "Helps with files" won't get matched. Front-load specific verbs and nouns the user will type.
- **Skipping the install/setup section.** The agent only knows what's in `SKILL.md` — undocumented `npm install` requirements turn into mystery failures.
- **Hardcoding the user's shell config file.** `~/.zshrc` vs `~/.bashrc` vs `~/.profile` differs — instruct the agent to detect and offer the right one.
- **Adding agent-specific frontmatter.** Breaks portability across pi/Codex/Amp/Droid/Claude Code.
- **Symlinking the parent repo into Claude Code's skills dir.** Claude Code looks one level deep — symlink each skill folder individually.
- **Bundling secrets.** Never commit API keys to a skill folder. The skill walks the user through env-var setup; it doesn't ship credentials.
- **Forgetting the `{baseDir}` substitution.** It only applies inside the SKILL.md body text — your helper script's own internals can't reference it.

## When to Use This Mode

- Writing a new cross-tool skill or porting an existing one
- Reviewing a `SKILL.md` for portability, description quality, and setup-walkthrough completeness
- Diagnosing why an agent didn't pick a skill up (description match, install path, depth limit)
- Bundling a folder of skills into a pi package (pair with Pi Packages Expert)

## Sources

- https://pi.dev/docs/latest/packages
- https://pi.dev/docs/latest/extensions
- https://github.com/badlogic/pi-skills
- https://github.com/badlogic/pi-skills/blob/main/brave-search/SKILL.md
- https://github.com/badlogic/pi-skills/blob/main/gccli/SKILL.md
- https://github.com/badlogic/pi-skills/blob/main/transcribe/SKILL.md
- https://github.com/badlogic/pi-skills/blob/main/vscode/SKILL.md