Closing the intent-to-code chasm - specification-driven development with BDD verification chain
95
Does it follow best practices?
Validation for skill structure
iikit-clarify
skills/iikit-clarify/SKILL.md
Discovery
100%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is an excellent skill description that hits all the marks. It provides specific concrete actions, includes natural trigger terms users would actually say, explicitly answers both what and when, and carves out a distinct niche that won't conflict with other skills. The description is comprehensive yet concise.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'auto-detects the most recent artifact', 'asks targeted questions with option tables', 'writes answers back into the artifact's Clarifications section'. Also enumerates specific artifact types (spec, plan, checklist, testify, tasks, constitution). | 3 / 3 |
Completeness | Clearly answers both what ('Resolve ambiguities...auto-detects...asks targeted questions...writes answers back') AND when with explicit 'Use when' clause covering six specific trigger scenarios. | 3 / 3 |
Trigger Term Quality | Includes natural trigger terms users would say: 'requirements are unclear', 'trade-off gaps', 'thresholds feel wrong', 'scenarios are imprecise', 'dependencies seem off', 'principles are vague'. Also mentions specific artifact types as keywords. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive with a clear niche: resolving ambiguities specifically in project artifacts with a defined workflow (detect artifact → ask questions → write to Clarifications section). The specific artifact types and 'Clarifications section' make it unlikely to conflict with other skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
85%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-crafted skill with excellent actionability and workflow clarity. The multi-step process is clearly sequenced with validation checkpoints, and external references are appropriately organized. Minor verbosity from repeated Windows command alternatives and some redundant explanations prevent a perfect conciseness score.
Suggestions
Consider consolidating Windows command alternatives into a single reference note or table at the top rather than repeating the pattern for each command
The target detection section could combine the argument mapping table and auto-detection list into a single unified reference to reduce duplication
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is reasonably efficient but includes some redundant explanations (e.g., the detailed Windows alternatives for every command could be consolidated). The structure is good but could be tightened in places like the target detection table which duplicates information. | 2 / 3 |
Actionability | Provides fully executable bash/powershell commands, specific file paths, concrete tables for argument mapping, and clear step-by-step procedures. The commands are copy-paste ready with actual script paths. | 3 / 3 |
Workflow Clarity | Excellent multi-step workflow with clear sequencing (Prerequisites → Target Detection → Scan → Question → Integrate → Validate → Report). Includes explicit validation steps ('Save artifact after each integration'), error handling ('If no clarifiable artifact exists: ERROR'), and feedback loops for the questioning process. | 3 / 3 |
Progressive Disclosure | Well-structured with clear references to external files (ambiguity-taxonomies.md, conversation-guide.md, clarification-format.md, model-recommendations.md, constitution-loading.md). References are one level deep and clearly signaled with descriptive link text. | 3 / 3 |
Total | 11 / 12 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 — 11 / 11 Passed
Validation for skill structure
No warnings or errors.