Spec

What it does

When your agent uses it

• Tasks that involve Planning

Example prompts

• “Use the spec skill to create a concise engineering implementation plan based on user requirements and saves it to specs directory”
• “/spec”

Requirements

• Python 3

Workflow steps

6 steps, taken from the first numbered list in SKILL.md.

1. 1Analyze Requirements - THINK HARD and parse the USER_PROMPT to understand the core problem and desired outcome
2. 2Explore Codebase - Understand existing patterns, architecture, and relevant files
3. 3Design Solution - Develop technical approach including architecture decisions and implementation strategy
4. 4Document Plan - Structure a comprehensive markdown document with problem statement, implementation steps, and testing approach
5. 5Generate Filename - Create a descriptive kebab-case filename based on the plan's main topic, prefixed with spec-
6. 6Save & Report - Follow the Report section to write the plan to PLAN_OUTPUT_DIRECTORY/spec-.md and provide a summary of key components

What it can do on your machine

Read from SKILL.md and the folder at commit cbb8cc3. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  No scripts in the folder and no shell commands in SKILL.md (its code samples are markdown).

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  No URLs in SKILL.md.

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Spec loads about 1.3k tokens when it runs. Until then it costs about 28 tokens; SKILL.md has 329 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~28

When it runs · the whole SKILL.md, loaded when a task matches

~1.3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from disler/pi-agent-observability at commit cbb8cc3, republished under its MIT licence (© disler). 329 words, ~1,264 tokens.

name

spec

description

Creates a concise engineering implementation plan based on user requirements and saves it to specs directory

argument-hint

[user prompt]

# Plan: <task name>

## Task Description
<describe the task in detail based on the prompt>

## Objective
<clearly state what will be accomplished when this plan is complete>

<if task_type is feature or complexity is medium/complex, include these sections:>
## Problem Statement
<clearly define the specific problem or opportunity this task addresses>

## Solution Approach
<describe the proposed solution approach and how it addresses the objective>
</if>

## Relevant Files
Use these files to complete the task:

<list files relevant to the task with bullet points explaining why. Include new files to be created under an h3 'New Files' section if needed>

<if complexity is medium/complex, include this section:>
## Implementation Phases
### Phase 1: Foundation
<describe any foundational work needed>

### Phase 2: Core Implementation
<describe the main implementation work>

### Phase 3: Integration & Polish
<describe integration, testing, and final touches>
</if>

## Step by Step Tasks
IMPORTANT: Execute every step in order, top to bottom.

<list step by step tasks as h3 headers with bullet points. Start with foundational changes then move to specific changes. Last step should validate the work>

### 1. <First Task Name>
- <specific action>
- <specific action>

### 2. <Second Task Name>
- <specific action>
- <specific action>

<continue with additional tasks as needed>

<if task_type is feature or complexity is medium/complex, include this section:>
## Testing Strategy
<describe testing approach, including unit tests and edge cases as applicable>
</if>

## Acceptance Criteria
<list specific, measurable criteria that must be met for the task to be considered complete>

## Validation Commands
Execute these commands to validate the task is complete:

<list specific commands to validate the work. Be precise about what to run>
- Example: `uv run python -m py_compile apps/*.py` - Test to ensure the code compiles

## Notes
<optional additional context, considerations, or dependencies. If new libraries are needed, specify using `uv add`>

✅ Implementation Plan Created

File: PLAN_OUTPUT_DIRECTORY/spec-<filename>.md
Topic: <brief description of what the plan covers>
Key Components:
- <main component 1>
- <main component 2>
- <main component 3>

© disler, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .claude/skills/spec of disler/pi-agent-observability.

Open the folder on GitHubat commit cbb8cc3