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

85%

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

81%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-crafted instruction skill: fully sequenced workflow with validation checkpoints appropriate to batch fact edits, concrete commands, and a realistic worked example. The main improvement areas are minor redundancy between the intro, 'When to use', and 'Guidelines' sections, and one placeholder command.

Suggestions

Consolidate the collaboration rule stated twice ('Do NOT silently bulk-edit the fact sheet' and 'Every change requires the user's agreement. You propose, they decide.') into one place, and trim the 'When to use this skill' section that restates the description.

Replace the '--section ...' placeholder in the apply-changes command with a concrete example (e.g., '--section api/auth') so every command is copy-paste ready.

Dimension	Reasoning	Score
Conciseness	The body is dense and nearly every section earns its tokens (problem taxonomy, concrete commands, worked example). Minor trimmable repetition exists: the 'When to use this skill' section restates the description, and 'Do NOT silently bulk-edit the fact sheet' is restated as 'Every change requires the user's agreement' in Guidelines. Not 5 due to this duplicated guidance; not 3 since padding is minor and incidental.	4 / 5
Actionability	Concrete, executable CLI commands throughout (facts list --tags "draft", facts edit <id> --label ... --remove-tag "draft" --add-tag "spec", facts check) plus a fully worked example session. Not 5: one command uses a literal placeholder — 'facts add "new fact split from compound" --section ... --tags "spec"' — leaving a small gap in copy-paste readiness; not 3: guidance is overwhelmingly executable rather than pseudocode.	4 / 5
Workflow Clarity	A clear five-step sequence (load -> identify problems -> discuss -> apply -> verify) with explicit validation checkpoints: 'facts check' on load, per-change confirmation ('Confirm each change landed correctly before moving on'), and 'facts check' / 'facts lint' after all changes — an explicit feedback loop for a batch-edit skill. Not 4: both entry and exit validation plus error-recovery ordering are present.	5 / 5
Progressive Disclosure	No bundle files exist, and the single SKILL.md is well-sectioned with clear headers and pointers to external CLI help ('facts --help', 'facts skills show facts'), so nothing is misfiled. Not 5: at ~145 lines with a long inline problem taxonomy, some content could be tightened or split; not 3: structure and organization are good, not merely adequate.	4 / 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 description: concrete, action-oriented, third-person, and with an explicit and specific 'Use when' clause covering natural trigger phrasings. Its only weaknesses are a slightly narrow set of trigger synonyms and minor overlap risk with sibling facts-related skills.

Dimension	Reasoning	Score
Specificity	Lists four concrete actions — "Resolve ambiguities, fill gaps, eliminate contradictions, and sharpen labels" — which comprehensively covers the refine workflow within the facts domain. Not 4: the actions are specific and coverage is complete, not merely 'several with minor gaps'.	5 / 5
Completeness	Explicitly answers both what ("collaboratively refine them into precise, actionable @spec facts... resolve ambiguities, fill gaps...") and when ("Use when asked to refine facts, clarify the spec, review facts for quality, or 'work on facts' with the user") with concrete trigger phrases. Not 4: the 'when' clause is explicit and specific rather than merely adequate.	5 / 5
Trigger Term Quality	Natural phrases users would say are present — "refine facts", "clarify the spec", "review facts for quality", "'work on facts'" — giving good keyword coverage. Not 5: a few natural variations (e.g., 'improve the fact sheet', 'finalize facts') are missing; not 3: coverage goes well beyond 'some relevant keywords'.	4 / 5
Distinctiveness Conflict Risk	The @draft-to-@spec lifecycle niche is clearly distinct, but phrases like "review facts for quality" could overlap with adjacent fact-sheet management skills. Mostly distinct with minor overlap risk; not 5 given the related 'facts' skill family, not 3 since the core lifecycle trigger is unambiguous.	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: e38ae4c

Reviewed: 1 day 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.