write-a-skill

Skill authoring uses progressive disclosure to avoid token overload by drafting a concise entry point and moving deep details into references. This keeps standing context lightweight while retaining in-depth operational guidance.

Progressive disclosure for agent workflows separates a concise trigger entry point from detailed references. This design reduces token-heavy standing context and allows the agent to load deep operational guidance on demand.

Writing YAML frontmatter for a new Pi skill requires defining a name and description. You must also provide an instruction body specifying the entry protocol, topology check, verification gate, red lines, and output contract.

Every agent skill needs a safety contract and verification gate to ensure reliable operation. Defining red lines and an output contract establishes clear boundaries for safe execution and expected workflow results.

Organizing scripts and references in a skill repository involves using dedicated directories for deterministic tasks and in-depth guidance. This aligns with repo conventions and maintains a maintainable layout for the package.

You should not use a progressive disclosure layout for skill authoring if your workflow lacks deep details or complex references. Simple tasks with minimal instructions do not require separating triggers from a references directory.