Review: obra's writing-plans Skill for Claude Code

An agentskill is a packaged prompt and instruction set that Claude Code (or Claude in other agentic harnesses) can invoke to accomplish a specific task. The writing-plans skill, authored by obra and hosted on agentskill.sh, focuses on converting a specification or requirements document into a structured, executable implementation plan before any code is written.

Metric	Value
agentskill Rating	4.33 / 5 (3 ratings)
Installs	2
Security Score	100 / 100
Content Quality	83 / 100
Upstream GitHub Stars	87,265
Last Updated	2026-04-30

The skill lives in .claude/skills/obra/writing-plans/SKILL.md when installed on Claude Code. Its trigger description is “Use when you have a spec or requirements for a multi-step task, before touching code,” which correctly sets expectations: this is a planning artifact, not an execution tool.

What the Skill Does

The writing-plans SKILL.md is a 250-line prompt guide that asks Claude to produce a detailed implementation plan based on a feature spec. The plan output itself is a Markdown document saved to docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md (or a user-specified location).

The core workflow is:

1. Announce the skill: “I’m using the writing-plans skill to create the implementation plan.”
2. Scope check: if the spec spans independent subsystems, suggest breaking it into separate plans.
3. Map file structure before tasks. The instruction emphasizes “design units with clear boundaries” and splitting by responsibility, not by technical layer.
4. Decompose into bite-sized tasks (2 to 5 minutes each): write failing test, verify failure, implement, verify pass, commit.
5. Apply a plan review loop: optionally dispatch a subagent plan-document-reviewer after each chunk, re-iterate until approved.
6. Hand off to an execution skill (superpowers:executing-plans or superpowers:subagent-driven-development).

The supporting file in the skill folder is plan-document-reviewer-prompt.md, though the SKILL.md only hints at it and does not include its contents in the provided data.

Declared Capabilities and Fit

The skill tags itself as covering frontend, design, docx, git, api, testing, and backend. The job categories are development, product, and project-management. In practice, the SKILL.md is tightly bound to software engineering: it assumes a codebase, exact file paths, test runners, and git workflows. The broader tags (design, docx, product-management) feel overstated.

The skill’s strongest fit is a team or solo developer with a detailed spec, zero context about the codebase, and a need for an audit trail (commit per step, frequent checkpoints). The instruction “Assume they are a skilled developer, but know almost nothing about our toolset” targets onboarding or hands-off delegation.

Installation and Usability

Installing the skill on Claude Code is straightforward: point Claude to https://agentskill.sh/obra/writing-plans (the agentskill.sh listing), and Claude will fetch the SKILL.md and supporting files. No package manager, no external dependencies.

One friction point: the skill assumes you already have a dedicated worktree created by a “brainstorming skill” (which is not supplied or linked). If you invoke writing-plans without that context, you will need to set up the directory structure yourself or ignore that instruction.

Comparison to Alternatives

Capability	writing-plans	Claude Native Planning	Specialized Planning Tools
File-level decomposition	Yes, required first	Ad-hoc, depends on prompt	Often optional
Test-first structure	Yes, enforced	Optional, user directs	Varies
Commit granularity	Yes, per step	Not addressed	Usually not addressed
Save to persistent doc	Yes (Markdown)	No default	Depends on tool
Multi-agent review loop	Yes, built-in	No	Rare in open tools
Low config overhead	Yes	Yes	No (setup per project)

Claude’s native planning (a simple multi-step prompt) is faster to set up and flexible. It does not enforce file structure or TDD. Specialized planning tools (e.g., Jira templates, custom Markdown generators) offer domain-specific fields but require upfront config.

Writing-plans occupies a middle ground: more structured than vanilla Claude, simpler than bespoke tooling. It makes sense if your team values repeatable, auditable, test-driven workflows.

Strengths

The SKILL.md is methodical and prescriptive, which is a strength for repeatability. The focus on file structure (“Design units with clear boundaries”) before task decomposition is sound engineering practice, especially for scaling to large features. The bite-sized task granularity (2 to 5 minutes per step) makes handoff to a junior or to an agentic executor straightforward.

The inclusion of a plan review loop (plan-document-reviewer subagent) is rare in planning guidance. It reduces the chance of a broken plan reaching execution.

Security and content quality scores are strong (100 and 83, respectively), suggesting the SKILL.md is well-vetted for prompt injection and clarity.

Weaknesses and Red Flags

Low adoption. Only 2 installs and 3 ratings. This is a narrow early-adopter base. There is minimal real-world feedback on whether the generated plans actually execute well, or whether the file structure guidance scales to legacy codebases (the SKILL.md does hedge on this: “if the codebase uses large files, don’t unilaterally restructure”).

Narrow scope. The skill is exclusively for pre-coding planning. It requires a separate execution skill downstream. The dependency on superpowers:subagent-driven-development or superpowers:executing-plans means the full workflow is fragmented across multiple skills, and those skills are not provided or validated.

Incomplete supporting materials. The SKILL.md references plan-document-reviewer-prompt.md, which is mentioned as a file in the skill folder, but its contents are not included in the provided data. A reviewer cannot assess the quality of the review loop without seeing that prompt.

Untested TDD assumption. The skill heavily emphasizes “Write the failing test” as the first step. This works for greenfield projects and codebases with existing test infrastructure, but it glosses over setup (pytest, mocking, test data). A developer in a codebase without tests may find the task steps incomplete.

Fixed naming convention. Plans are saved to docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md. This assumes a docs/ directory and a superpowers/plans/ subdirectory structure that may not exist. The instruction says “User preferences override this,” but the skill gives no guidance on how to specify an override at invocation time.

Who Should Use This

Use writing-plans if you:

• Have a full specification and want a detailed, test-driven roadmap.
• Work in a codebase with good test coverage and established patterns.
• Want an audit trail (plans saved, reviewable, versioned).
• Are onboarding a junior developer or delegating to an agentic worker.
• Value step-by-step commit hygiene.

Skip writing-plans if you:

• Are prototyping or iterating incrementally (plan overhead not worth it).
• Work in a codebase without test infrastructure.
• Prefer freeform planning or use a dedicated project management tool.
• Have a small task (under 1 to 2 hours) that does not need a detailed map.

Real-World Usability Gaps

The SKILL.md does not explain how to invoke the skill in Claude Code’s interface. Does the user type @writing-plans in a message? Is there a command? The agentskill.sh spec assumes developers know this.

The skill also does not address version control conflict scenarios. If a plan assumes file paths that have changed since the spec was written, or if another developer edits the same file mid-plan, the instructions are silent.

The plan review loop is ambitious but adds latency. The SKILL.md notes “if loop exceeds 5 iterations, surface to human for guidance,” suggesting the loop can get stuck. A low-install base means few reports of this issue.

Takeaways

The writing-plans skill is well-structured and disciplined, making it a good fit for teams that value test-first development and repeatable workflows. The file-level decomposition guidance before task planning is sound engineering practice.

However, the 2 installs and 3 ratings indicate minimal real-world usage. The skill is untested at scale, and the dependency on downstream execution skills (not included) creates friction. The TDD assumption works in mature codebases but may be a poor fit for legacy or test-sparse environments.

If you have a detailed spec, strong test infrastructure, and a need for an audit trail, writing-plans is worth a trial. For faster iteration or smaller tasks, Claude’s native planning is likely sufficient.

Further reading

• agentskill.sh listing for obra/writing-plans - the official skill page and source of record
• agentskill.sh GitHub documentation - background on how agentskills are packaged and installed (if available in the org)
• Test-driven development fundamentals - the TDD discipline underlying this skill’s task structure
• Claude Code documentation - how to install and invoke skills in Claude Code
• obra’s GitHub profile - the skill author’s public work (87,265 stars upstream suggests significant open-source activity)