task-planning

Turn a Paperclip issue or request into a structured implementation plan with child task graph, blockers, owners, and acceptance criteria, then save it as the issue `plan` document.

Quality

82%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

90%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A dense, high-signal operations skill: concrete API endpoints with idempotency and revision handling, a prescribed plan document structure, and sharp anti-patterns. The only gaps are the absence of a post-filing validation/retry loop and an unlinked reference to the companion execution skill.

Dimension	Reasoning	Score
Conciseness	The body is lean and operational throughout — no line explains concepts Claude already knows; every section adds Paperclip-specific or project-specific knowledge (e.g. "A child must be checkout-able by the owner from its title and description alone", "Acceptance written as 'code review approval'. Reviewers need a behavior bar, not a process bar"). Each token earns its place.	5 / 5
Actionability	Fully executable guidance: concrete API calls with exact fields — `PUT /api/issues/{issueId}/documents/plan` with `baseRevisionId` on conflict, `POST /api/issues/{issueId}/interactions` with `kind: request_confirmation`, `targetRevisionId`, `continuationPolicy: wake_assignee`, and a literal `idempotencyKey: "confirmation:{issueId}:plan:{revisionId}"` template. The plan structure and splitting rules are equally specific (owner specialties enumerated, `blockers: none` convention, imperative child titles).	5 / 5
Workflow Clarity	The sequence is clear — when/when not to use, outputs, plan structure, then filing via API in order — with an explicit approval checkpoint ("Do not create implementation subtasks until the plan is accepted", request_confirmation, `in_review`, stay assigned so the acceptance wakes the planner). It stops short of a 5 because there is no validate/retry loop after filing (e.g. handling a `baseRevisionId` conflict or verifying the plan revision landed) and no verification that the comment and interaction were attached to the right revision.	4 / 5
Progressive Disclosure	Well-organized single-file skill with clear sections and no nested references. It falls short of 5 on two counts: the body is ~70 lines (above the under-50-lines simple-skill exception) and the "companion skill" for converting accepted plans into executable tasks is named but never linked by key or path, so navigation to that dependent material is left implicit.	4 / 5
	Total	18 / 20 Passed

Description

75%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A specific, distinctive, third-person description whose only real weakness is the missing use-when trigger clause — the body contains excellent trigger phrases ("plan", "scope", "break down", "design the rollout") that never made it into the description.

Suggestions

Append a use-when clause mirroring the body's own trigger list, e.g. "Use when an issue or user asks to plan, scope, break down, or design the rollout of non-trivial work, or when a manager needs to delegate work whose shape is not obvious."

Add the natural synonyms already present in the body — "scope", "break down", "delegate", "design the rollout" — so the description catches the phrasings users actually say.

State the boundary case for when NOT to use it (single small change shippable in one heartbeat) to further separate this from general planning or diagnosis skills.

Dimension	Reasoning	Score
Specificity	Multiple concrete actions with comprehensive coverage, all in third person: "Turn a Paperclip issue or request into a structured implementation plan with child task graph, blockers, owners, and acceptance criteria, then save it as the issue `plan` document" names the input, four plan components, and the exact write action. Not a 4 because no capability is left as a generic gesture — even the persistence target (`plan` document) is named.	5 / 5
Completeness	The 'what' is explicit and strong, but the 'when' is entirely missing — there is no "Use when…" clause or equivalent trigger guidance, which the judging guidelines cap at 3. Not a 2 because the 'what' is fully specified with concrete actions rather than vague.	3 / 5
Trigger Term Quality	Good natural-keyword coverage: "issue", "request", "plan", "implementation plan", "break down"-adjacent phrasing like "structured implementation plan". Not a 5 because common user phrasings the body itself knows are strong triggers — "scope", "break down", "design the rollout", "propose the work", "delegate" — are absent from the description.	4 / 5
Distinctiveness Conflict Risk	Clear niche with distinct triggers: "Paperclip issue" and "issue `plan` document" are unambiguous platform-specific terms, so it would not fire for generic planning or non-Paperclip work. Minimal conflict risk.	5 / 5
	Total	17 / 20 Passed

Validation

93%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: paperclipai/paperclip
Path: packages/skills-catalog/catalog/bundled/paperclip-operations/task-planning/SKILL.md
Commit: 1c07b59

Reviewed: 1 day ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.