facts-refine

Operate on @draft facts — collaboratively refine them into precise, actionable @spec facts. Resolve ambiguities, fill gaps, eliminate contradictions, and sharpen labels until every fact is ready to implement. Use when asked to refine facts, clarify the spec, review facts for quality, or "work on facts" with the user.

Quality

86%

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

85%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 well-structured, executable skill body with a clear multi-step workflow and built-in validation. It loses points only on progressive disclosure — everything is inlined into SKILL.md with no external references — and minor conciseness slack in the issue taxonomy.

Suggestions

Split the six-category issue taxonomy (structural/vague/gaps/contradictions/compound/vocabulary/missing-validation) into a references/ file and keep a condensed checklist inline, reducing token load while preserving the decision tree.

Move the full worked example session into a separate EXAMPLES.md and link to it one level deep, leaving only a short illustrative snippet in SKILL.md.

Tighten the example block by not re-listing the load commands already shown in step 1, trimming redundant lines.

Dimension	Reasoning	Score
Conciseness	Mostly lean and assumes Claude's competence — the problem taxonomy and example session are directly useful — but the six-bullet issue taxonomy and the duplicated load commands in the example add some length that could be trimmed without losing clarity.	4 / 5
Actionability	Fully executable: concrete `facts` commands throughout (`facts list --tags "draft"`, `facts edit <id> --label ... --remove-tag "draft" --add-tag "spec"`, `facts check`, `facts lint`) and a complete copy-paste-ready example session covering the common refine workflow.	5 / 5
Workflow Clarity	Clear five-step sequence (Load → Identify → Discuss → Apply → Verify) with explicit validation checkpoints (`facts check`, `facts lint`) and a feedback loop — the user-decides gate before each apply and the verify-and-summarize step with retry guidance match the top anchor.	5 / 5
Progressive Disclosure	The body is a single self-contained SKILL.md with no bundle files and no one-level-deep references to split out detail; it is reasonably sectioned, but content that could live in references (the full issue taxonomy, the worked example) is inlined rather than progressively disclosed.	3 / 5
	Total	17 / 20 Passed

Description

88%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, third-person description that concretely lists refinement actions and pairs them with explicit 'Use when...' triggers. It is specific and complete; the only soft spot is trigger-term synonym coverage and slight overlap with a sibling facts skill.

Dimension	Reasoning	Score
Specificity	Multiple concrete actions are named — 'refine them into precise, actionable @spec facts', 'Resolve ambiguities, fill gaps, eliminate contradictions, and sharpen labels' — giving comprehensive coverage of the skill's capabilities rather than vague abstraction.	5 / 5
Completeness	It explicitly answers both 'what' (refine @draft facts into @spec facts by resolving ambiguities, filling gaps, eliminating contradictions, sharpening labels) and 'when' with concrete trigger phrases ('Use when asked to refine facts, clarify the spec, review facts for quality, or "work on facts"').	5 / 5
Trigger Term Quality	Natural user phrases appear ('refine facts', 'clarify the spec', 'review facts for quality', 'work on facts'), but coverage leans on the 'facts/spec' vocabulary and omits common synonyms a user might say ('clean up the spec', 'tighten requirements'); a few natural terms are missing.	4 / 5
Distinctiveness Conflict Risk	The @draft → @spec lifecycle and the 'refine' framing carve a clear niche distinct from generic fact authoring, but the 'review facts for quality' trigger has some overlap with a sibling 'facts' skill, leaving minor conflict risk.	4 / 5
	Total	18 / 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: av/harbor
Path: .agents/skills/facts-refine/SKILL.md
Commit: 67cbe66

Reviewed: 2 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.