agent-goal-planner

Agent skill for goal-planner - invoke with $agent-goal-planner

1.42x

Quality

35%

Does it follow best practices?

Impact

87%

1.42x

Average score across 3 eval scenarios

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/agent-goal-planner/SKILL.md

Quality

Content

42%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 persona prompt rather than a skill document: it motivates and describes GOAP planning but gives little executable guidance. Its most concrete material is a malformed MCP example block, it wastes tokens on concepts Claude already knows, and it contains a duplicated frontmatter block that signals file corruption. The workflow skeleton is reasonable but lacks any concrete validation checkpoints or state/action schemas.

Suggestions

Replace the pseudocode MCP block with syntactically valid, executable examples, and add a concrete schema for actions (name, preconditions, effects, cost) plus a small worked planning example.

Cut the persona preamble, the generic capability bullet list, and the explanations of A*/OODA that Claude already knows; keep only the GOAP-specific procedure and validation checkpoints.

Delete the stray second frontmatter block from the body, and split detailed material (MCP tool usage, replanning heuristics) into a references/ file linked from a short overview.

Dimension	Reasoning	Score
Conciseness	The body opens with a padded persona preamble ('You are a Goal-Oriented Action Planning (GOAP) specialist, an advanced AI planner...'), re-explains concepts Claude already knows (A* search, the OODA loop, 'what is true now' glosses), carries a generic 11-item capability list, and includes a stray duplicated frontmatter block. Fits anchor 2 ('several unnecessary explanations or padded sections'); not 3 because the padding is pervasive, not incidental.	2 / 5
Actionability	The 5-step methodology gives structure and names concrete MCP tools, but the guidance stays abstract — no schema for representing state, actions, preconditions, effects, or costs — and the MCP examples are non-executable pseudocode ('mcp__claude-flow__task_orchestrate { ... }' with JSON.stringify inside a config value). Fits anchor 3 ('some concrete guidance but incomplete; pseudocode instead of executable code'); not 2 because the methodology and tool names are specific, and not 4 because nothing is copy-paste runnable.	3 / 5
Workflow Clarity	The numbered methodology (State Assessment → Action Analysis → Plan Generation → Execution Monitoring → Dynamic Replanning) is a coherent sequence with a conceptual feedback loop (OODA decide/replan). However, checkpoints are implicit and abstract — no concrete validation step tells Claude how to verify a plan or detect failure in practice. Fits anchor 3 ('sequence present but checkpoints missing or implicit'); not 4 because there is no concrete verification command or checkpoint.	3 / 5
Progressive Disclosure	No bundle files exist and the ~70-line body has essentially one header ('## MCP Integration Examples'), mixing persona, capability lists, methodology, and tool examples in one slab with no navigation. Fits anchor 3 ('some structure but could be better organized'); not 2 because the content is overview-level rather than an inlined API reference, and not 4/5 because there are no well-signaled sections or reference files despite the body exceeding 50 lines.	3 / 5
	Total	11 / 20 Passed

Description

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

The frontmatter description is a low-information wrapper: it tells the reader how to invoke the skill but not what it does or when to use it. It also duplicates a second, richer description in an orphaned frontmatter block inside the body, indicating a malformed file. Scores are uniformly low, with the trigger and completeness gaps being the most damaging.

Suggestions

Rewrite the description to state concrete capabilities in third person, e.g.: 'Creates and optimizes multi-step action plans using Goal-Oriented Action Planning (GOAP): decomposes goals into sub-goals, evaluates action preconditions/effects, and replans adaptively when execution fails.'

Add an explicit trigger clause such as: 'Use when the user needs to plan a complex multi-step objective, break a goal into sub-goals, or recover a plan after failed actions.'

Remove the duplicate embedded frontmatter block from the body and keep a single, canonical frontmatter so the real description is the one that gets indexed.

Dimension	Reasoning	Score
Specificity	The description names the domain ("goal-planner") but the only action stated is the meta-verb "invoke with $agent-goal-planner" — no concrete capability actions at all. It matches anchor 2 ('names the domain but actions are minimal or generic'), not anchor 1 (it is not pure abstract language) and not anchor 3 (it lists zero concrete actions like 'Processes PDF files and extracts content').	2 / 5
Completeness	"Agent skill for goal-planner" is a vague 'what' (a label, not a capability statement) and there is no 'when' or 'Use when...' guidance anywhere. This matches anchor 2 exactly ('has a vague what and no when'); not 1 because the domain label weakly gestures at what it does, and not 3 because even the 'what' is not clear.	2 / 5
Trigger Term Quality	The only keywords are the skill's own name and its invocation syntax ("$agent-goal-planner") — technical meta-language, not phrases a user would naturally say when needing planning help. Fits anchor 2 ('one or two generic keywords; missing the natural phrases users say'); not 3 because there are no genuine natural trigger terms beyond the skill name itself.	2 / 5
Distinctiveness Conflict Risk	"goal-planner" names a recognizable niche, but the description provides no distinctive trigger phrases, so it could still overlap with generic planning, reasoning, or task-management skills. Fits anchor 3 ('somewhat specific but could still overlap with similar skills'); not 4 because nothing in the text distinguishes it from those neighbors.	3 / 5
	Total	9 / 20 Passed

Validation

100%

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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: ruvnet/ruflo
Path: .agents/skills/agent-goal-planner/SKILL.md
Commit: b14c79e

Reviewed: 3 days 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.