# Skill authoring

Read this internal Workbench procedure when creating, revising or reviewing a Skill, including its description or supporting references. It is packaged guidance, not a separately installed or invoked Skill. Resolve every link relative to this file in the loaded Workbench package, not the conversation's cwd. System-Prompt writing uses [Direct Pi authoring](pi-authoring.md); executable integration uses the separate [Extension workflow](extensions.md).

## 1. Load the writing method

Read Matt Pocock's complete bundled original [Writing for Agents](writing-for-agents/SKILL.md) and [Skill Mechanics](writing-for-agents/SKILL-MECHANICS.md). Apply their writing and disclosure method to the actual Skill body, trigger pointers and affected references. Use these files even when the user has no authoring Skill installed; an abridged installed variant is not their replacement. Preserve binding requirements rather than optimizing for length alone.

The original Skill Mechanics describes other harness assumptions. Use the native Pi rules below for discovery, file access and invocation; hiding an advertised description does not prevent reading a file, and Pi has no skill-to-skill invocation API.

**Done when** both originals have been read and the relevant Skill-writing branch is identified, not merely named or summarized.

## 2. Establish the real target and permission

Follow [source and destination selection](pi-authoring.md#1-choose-the-purpose-and-owner), [one active original](pi-authoring.md#2-resolve-one-active-original) and [permission and pre-edit backup](pi-authoring.md#3-establish-permission-and-pre-edit-backup). Inspect the actual Skill and affected references. A review without a writing grant remains read-only. For an existing Pi original outside Git, require successful native archival before writing. Apply the shared resolved-path exemption to Git-backed Skills, including symlinks into repositories, and to files outside the Pi directory. Exemption is not edit permission. A genuinely new file has no prior original to archive.

**Done when** the target, relevant current sources, scope and actual grants are established, with the shared backup gate satisfied for any existing-original edit. Stop dependent changes when one is missing.

## 3. Author for native Pi

Use the original writing method, with these Pi-specific mechanics:

- Put the Skill in a directory containing `SKILL.md` with YAML frontmatter. `name` uses lowercase letters, numbers and hyphens, at most 64 characters, without leading, trailing or consecutive hyphens. Normally match the directory name for portability; Pi does not require that match.
- `description` is required, nonempty and at most 1024 characters. It is the routing pointer shown without the body; name the real triggering task or role and meaningful exclusions.
- Omit `disable-model-invocation` or use `false` for automatic advertising; use `true` for deliberate explicit-command use. This controls advertising, not file access or authorization.
- Keep supporting paths relative to the Skill root. Every pointer must reach a real file under its stated condition. Use native configured Skill locations or package paths, not a Workbench-managed collection.

Pi advertises Skill names, descriptions and paths; the model reads the body when relevant. Automatic selection can miss a Skill. `/skill:name` explicitly loads it, with following arguments appended as a user request. `enableSkillCommands` controls interactive command discovery; manually entered commands still work. Neither loading nor frontmatter guarantees compliance, grants permissions or provides a sandbox. For a concrete version gap, consult the current host's shipped `docs/skills.md` and `docs/packages.md`.

**Done when** the real Skill has valid native frontmatter, an actionable workflow and completion conditions, with every affected pointer and reference checked against the original writing method. For a review, return supported findings rather than changing the target.

## 4. Apply and verify the authorized result

For writing work, follow [direct original editing](pi-authoring.md#5-edit-the-authorized-original-directly). For writing or review, follow [checks and evidence limits](pi-authoring.md#6-check-the-claim-and-report-its-limits). Check the actual delivered files, not only a proposed change. Review authorized native diagnostics for malformed frontmatter, missing descriptions or collisions; malformed files and skills without descriptions are not loaded, and collisions keep the first discovered Skill with a warning.

**Done when** the result covers the confirmed goal, affected files and references agree, and reported checks distinguish static review, native discovery and real model behavior. Missing runtime evidence stays explicit; reading this procedure is not proof that an LLM followed it.