Questions? hello@viberation.devGet supportBlogDocsChangelog

Colour mode

XGitHub
Get started

Writing Plans

Skills

Turn a spec into a step-by-step plan before touching code.

From Superpowers. When there is a spec or set of requirements for a multi-step task, your agent writes an implementation plan first, before it changes any code.

Install this skill

npx skills add https://github.com/obra/superpowers --skill writing-plans

Runs the open-source skills CLI in your own terminal. It asks which agents to add the skill to. Read what it tells your agent to do before you install it.

Download skill (.zip)

Install for your agent

  • Claude Code

    Run this in your project

    npx skills add https://github.com/obra/superpowers --skill writing-plans -a claude-code

    Add -g to install it for every project instead.

    Or ask Claude Code to do it

    Install the "writing-plans" skill from https://github.com/obra/superpowers for Claude Code.
Copy the skill folder (the one containing SKILL.md, with any scripts or reference files next to it) into .claude/skills/ in this project.
Before copying, show me the SKILL.md and list any scripts it includes, and wait for me to confirm.

    Or copy the folder yourself

    Unzip the download into .claude/skills/ for this project, or ~/.claude/skills/ for all your projects.

    Picked up in the current session, no restart needed.

    Claude Code skills docs
  • Claude.ai

    Upload the ZIP

    1. In Settings > Capabilities, turn on Code execution and file creation.
    2. Go to Customize > Skills, press +, then Create skill.
    3. Choose Upload a skill and pick the ZIP you downloaded.

    Free, Pro and Max plans. On Team and Enterprise, an owner turns skills on in Organization settings first.

    Claude.ai skills docs
  • ChatGPT

    Upload the ZIP

    1. Open Skills in ChatGPT and select Create.
    2. Select Upload from your computer and pick the ZIP you downloaded.
    3. Wait for ChatGPT's safety scan. A skill marked Needs Review asks you to check it before use.

    Skills that rely on scripts or a terminal may not work unchanged in ChatGPT.

    ChatGPT skills docs
  • Codex

    Run this in your project

    npx skills add https://github.com/obra/superpowers --skill writing-plans -a codex

    Add -g to install it for every project instead.

    Or ask Codex to do it

    Install the "writing-plans" skill from https://github.com/obra/superpowers for Codex.
Copy the skill folder (the one containing SKILL.md, with any scripts or reference files next to it) into .agents/skills/ in this project.
Before copying, show me the SKILL.md and list any scripts it includes, and wait for me to confirm.

    Or copy the folder yourself

    Unzip the download into .agents/skills/ for this project, or ~/.agents/skills/ for all your projects.

    Restart Codex if the skill does not show up.

    Codex skills docs
  • Cursor

    Run this in your project

    npx skills add https://github.com/obra/superpowers --skill writing-plans -a cursor

    Add -g to install it for every project instead.

    Or ask Cursor to do it

    Install the "writing-plans" skill from https://github.com/obra/superpowers for Cursor.
Copy the skill folder (the one containing SKILL.md, with any scripts or reference files next to it) into .cursor/skills/ in this project.
Before copying, show me the SKILL.md and list any scripts it includes, and wait for me to confirm.

    Or copy the folder yourself

    Unzip the download into .cursor/skills/ for this project, or ~/.cursor/skills/ for all your projects.

    Run it by typing / and the skill name in chat.

    Cursor skills docs
  • GitHub Copilot

    Run this in your project

    npx skills add https://github.com/obra/superpowers --skill writing-plans -a github-copilot

    Add -g to install it for every project instead.

    Or ask GitHub Copilot to do it

    Install the "writing-plans" skill from https://github.com/obra/superpowers for GitHub Copilot.
Copy the skill folder (the one containing SKILL.md, with any scripts or reference files next to it) into .github/skills/ in this project.
Before copying, show me the SKILL.md and list any scripts it includes, and wait for me to confirm.

    Or copy the folder yourself

    Unzip the download into .github/skills/ for this project, or ~/.copilot/skills/ for all your projects.

    Works in Copilot CLI, the cloud agent and agent mode in VS Code and JetBrains.

    GitHub Copilot skills docs
  • Antigravity

    Run this in your project

    npx skills add https://github.com/obra/superpowers --skill writing-plans -a antigravity

    Add -g to install it for every project instead.

    Or ask Antigravity to do it

    Install the "writing-plans" skill from https://github.com/obra/superpowers for Antigravity.
Copy the skill folder (the one containing SKILL.md, with any scripts or reference files next to it) into .agents/skills/ in this project.
Before copying, show me the SKILL.md and list any scripts it includes, and wait for me to confirm.

    Or copy the folder yourself

    Unzip the download into .agents/skills/ for this project, or ~/.gemini/config/skills/ for all your projects.

    Antigravity skills docs
  • Gemini CLI

    Run this in your project

    npx skills add https://github.com/obra/superpowers --skill writing-plans -a gemini-cli

    Add -g to install it for every project instead.

    Or ask Gemini CLI to do it

    Install the "writing-plans" skill from https://github.com/obra/superpowers for Gemini CLI.
Copy the skill folder (the one containing SKILL.md, with any scripts or reference files next to it) into .gemini/skills/ in this project.
Before copying, show me the SKILL.md and list any scripts it includes, and wait for me to confirm.

    Or copy the folder yourself

    Unzip the download into .gemini/skills/ for this project, or ~/.gemini/skills/ for all your projects.

    Run /skills to check it was found.

    Gemini CLI skills docs
Installs
247.4K via skills.sh
GitHub
286.3K stars ↗
Last updated
12 Sept 2026
Licence
MIT

Security checks

Run by independent scanners and published on skills.sh. Their results, not a Viberation review.

  • Gen Agent Trust Hub Pass

    The skill processes user-provided specifications to generate implementation plans containing executable commands. This creates an attack surface for indirect prompt injection if the input requirements are malicious.

    6 May 2026

  • Socket Pass

    No alerts

    6 May 2026

  • Snyk Pass

    Risk: LOW · No issues

    6 May 2026

  • Runlayer Pass

    2 files scanned · No issues

    12 Mar 2026

  • ZeroLeaks Pass

    1 finding · Score: 86/100

    16 Apr 2026
What's inside (2 files)
  • plan-document-reviewer-prompt.md1.7K chars
  • SKILL.md7K chars

SKILL.md, first part. Shown as plain text.

---
name: writing-plans
description: Use when you have a spec or requirements for a multi-step task, before touching code
---

# Writing Plans

## Overview

Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.

Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.

**Announce at start:** "I'm using the writing-plans skill to create the implementation plan."

**Context:** If working in an isolated worktree, it should have been created via the `superpowers:using-git-worktrees` skill at execution time.

**Save plans to:** `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`
- (User preferences for plan location override this default)

## Scope Check

If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans — one per subsystem. Each plan should produce working, testable software on its own.

## File Structure

Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in.

- Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility.
- You reason best about code you can hold in context at once, and your edits are more reliable when files are focused. Prefer smaller, focused files over large ones that do too much.
- Files that change together should live together. Split by responsibility, not by technical layer.
- In existing codebases, follow established patterns. If the codebase uses large files, don't unilaterally restructure - but if a file you're modifying has grown unwieldy, including a split in the plan is reasonable.

This structure informs the task decomposition. Each task should produce self-contained changes that make sense independently.

## Task Right-Sizing

A task is the smallest unit that carries its own test cycle and is worth a
fresh reviewer's gate. When drawing task boundaries: fold setup,
configuration, scaffolding, and documentation steps into the task whose
deliverable needs them; split only where a reviewer could meaningfully
reject one task while approving its neighbor. Each task ends with an
independently testable deliverable.

## Bite-Sized Task Granularity

**Each step is one action (2-5 minutes):**
- "Write the failing test" - step
- "Run it to make sure it fails" - step
- "Implement the minimal code to make the test pass" - step
- "Run the tests and make sure they pass" - step
- "Commit" - step

## Plan Document Header

**Every plan MUST start with this header:**

```markdown
# [Feature Name] Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

**Spec:** [path to the spec/design doc this plan implements — the plan
argues from the spec, so the spec travels with it; executors read both]

## Global Constraints

[The spec's project-wide requirements — version floors, dependency limits,
naming and copy rules, platform requirements — one line each, with exact
values copied verbatim from the spec. Every task's requirements implicitly
include this section.]

---
```

## Task Structure

````markdown
### Task N: [Component Name]

**Files:**
- Create: `exact/path/to/file.py`
- Modify: `exact/path/to/existing.py:123-145`
- Test: `tests

Key info

Pricing
Open source
Category
Skills

More in Skills