CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

planning-first

Enforce a planning-first workflow. Before non-trivial implementation, write or update plan.md with goals, approach, file-level changes, risks, and a checklist. Use when the user asks to build a feature, refactor, fix a non-obvious bug, or whenever scope is unclear. Skip only for one-line tweaks or pure questions.

Quality

90%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Quality

Content

92%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.

The body is a tight, well-structured process skill: a copy-paste-ready plan template, a sequenced loop with approval and contradiction-handling checkpoints, and clear skip/escalation rules. The only meaningful criticism is mild duplication between the Triggers section and the frontmatter description.

DimensionReasoningScore

Conciseness

The body is lean and assumes Claude's competence — no basic concepts are explained, and the plan template, loop, and escalation sections all earn their tokens. It sits at 4 rather than 5 because the Triggers section substantially restates the frontmatter description, a small amount of duplication that could be trimmed.

4 / 5

Actionability

Guidance is fully executable for a process skill: a copy-paste-ready plan.md skeleton with section-by-section instructions ("One paragraph. What does done look like?", "Note alternatives considered and why rejected"), a concrete file-level changes format, and a specific escalation path ("create an ADR in docs/adr/ (use /adr if available)"). The scoring note's exception for instruction-only skills applies, and the guidance is unambiguously actionable.

5 / 5

Workflow Clarity

The Loop section gives a clear sequence with explicit checkpoints: user approval before implementation ("get approval (or explicit 'go ahead')"), a feedback loop for error recovery ("If reality contradicts the plan, stop and update the plan before continuing"), and a completion summary comparing planned vs. actual. A checklist is built into the plan template, matching the 5 anchor; no destructive or batch operations apply a cap.

5 / 5

Progressive Disclosure

This is a short (~54 lines), single-purpose skill with no bundle files, and the simple-skill guidance applies: all content appropriately lives in one well-organized file with clear section headers (Triggers, Plan Structure, Loop, Escalation) and no nested references. The only external pointers (docs/adr/, the /adr skill) are one level deep and clearly signaled.

5 / 5

Total

19

/

20

Passed

Description

83%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 strong description that clearly states what the skill does and when to use it, with concrete trigger phrases and an explicit skip condition. Its main weaknesses are trigger coverage that lags the body (missing migrate/upgrade and multi-file triggers) and broad triggers that slightly raise conflict risk with general coding skills.

DimensionReasoningScore

Specificity

The description names concrete actions — "write or update plan.md with goals, approach, file-level changes, risks, and a checklist" — enumerating the plan's required components. It falls short of the 5 anchor because body-level capabilities (ADR escalation, the implement/update/summarize loop) are absent, leaving minor gaps in coverage.

4 / 5

Completeness

It explicitly answers both what ("write or update plan.md with goals, approach, file-level changes, risks, and a checklist" before non-trivial implementation) and when ("Use when the user asks to build a feature, refactor, fix a non-obvious bug, or whenever scope is unclear"), plus an explicit skip clause ("Skip only for one-line tweaks or pure questions") that exceeds the 5 anchor's standard.

5 / 5

Trigger Term Quality

Natural user phrases like "build a feature", "refactor", "fix a non-obvious bug", and "scope is unclear" are present and would be said verbatim. A few natural terms are missing — the body's "migrate / upgrade dependencies" and "anything spanning more than ~2 files" triggers are not surfaced in the description, and no synonyms are offered.

4 / 5

Distinctiveness Conflict Risk

The planning-workflow niche with its distinct artifact (plan.md) is clear and unlikely to be confused with domain skills. Broad triggers like "build a feature" and "refactor" create minor overlap risk with general coding skills, keeping it below the 5 anchor.

4 / 5

Total

17

/

20

Passed

Validation

100%

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

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

g23polar/dotfiles

Path

pi/agent/skills/planning-first/SKILL.md

Reviewed

Table of Contents

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.