clarification-protocol

I noticed you've built something that directly addresses one of the harder problems in LLM interactions—getting consistent, coherent responses when the initial prompt isn't quite right. The way you've structured the clarification loop suggests you're thinking deeply about user intent rather than just error handling, which reads really well in the docs.

Links:

• GitHub
• Your agentic skill in the SkillzWave marketplace

TL;DR

You're at 91/100, solidly in A territory. This is based on Anthropic's skill best practices rubric. Your strongest area is Utility (20/20)—the templates and challenge patterns genuinely solve a real problem. The weakest spot is Spec Compliance (11/15), which is fixable with one straightforward addition.

What's Working Well

• Utility is chef's kiss (20/20). Your templates for scope, scale, and constraint questions are immediately usable, and the before/after examples in the examples section show exactly how the protocol transforms vague requirements into actionable ones.
• PDA structure is solid (25/30). You've got the right layering: main skill file references two supporting docs with zero nesting overhead. That's the playbook working as intended.
• Ease of Use hits on all cylinders (23/25). The P0/P1/P2/P3 priority system is consistent, the 3-step workflow is numbered and clear, and the anti-patterns section prevents people from derailing themselves.

The Big One: Missing Trigger Phrases

Your description doesn't include any trigger phrases—words that help users discover when to invoke this skill. Right now it reads:

Generate targeted clarifying questions (2-3 max) that challenge vague requirements...

But it should include phrases like "clarification protocol" or "run clarification protocol" so the system knows when to suggest your skill. This is a Spec Compliance issue worth +2 points.

Fix: Update the frontmatter description to something like:

Performs clarification protocol operations. Use when asked to "clarification protocol", 
"run clarification protocol", or "clarification protocol help".

Other Things Worth Fixing

1. Add TOCs to all files over 100 lines. Your SKILL.md is 193 lines, question-templates.md is 214 lines, and challenge-patterns.md is 135 lines. Each needs a ## Table of Contents section at the top with anchored links. This costs nothing but navigation friction, worth +3 points.

2. Tighten the Priority table language. Phrases like "Can't proceed without this" and "Significantly changes approach" add 30% extra words without adding clarity. Trim to "Can't proceed without" and "Changes approach"—still clear, more scannable.

3. Challenge Mindset section is slightly redundant. The explanation of why challenges matter is solid, but it repeats the point across a few paragraphs. Consolidate into 3 crisp bullets instead of 4 explanatory sentences.

Quick Wins

• Add trigger phrases to description → +2 points
• Add TOCs to SKILL.md and reference files → +3 points
• Minor text tightening in tables/explanations → +1 point

That puts you at 97/100, which is basically shipping. The foundation is genuinely strong—this is polish, not restructuring.

Checkout your skill here: SkillzWave.ai | SpillWave We have an agentic skill installer that install skills in 14+ coding agent platforms. Check out this guide on how to improve your agentic skills.