Spec-Driven Development
addyosmani/agent-skills
Writes a structured specification before any code, moving through gated specify, plan, tasks and implement phases, with an optional capability map for multi-part requests.
Works with you to turn draft behavioral facts into precise, implementable spec facts, resolving vague labels, gaps and contradictions one at a time through discussion.
Install Facts Spec Refiner
$ npx skills add av/mi --skill facts-refine -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install av/mi facts-refine --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/av/mi.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/facts-refine .claude/skills/facts-refine && rm -rf skills-srcUse ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.
Claude Code skills documentation · loads skills from .claude/skills/
Install the "facts-refine" agent skill from https://github.com/av/mi/tree/master/.agents/skills/facts-refine into .claude/skills/facts-refine/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "facts-refine", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/av/mi/tree/master/.agents/skills/facts-refineType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add av/mi --skill facts-refine -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install av/mi facts-refine --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/av/mi.git skills-src && mkdir -p .agents/skills && cp -r skills-src/.agents/skills/facts-refine .agents/skills/facts-refine && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "facts-refine" agent skill from https://github.com/av/mi/tree/master/.agents/skills/facts-refine into .agents/skills/facts-refine/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "facts-refine", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add av/mi --skill facts-refine -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install av/mi facts-refine --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/av/mi.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/.agents/skills/facts-refine .cursor/skills/facts-refine && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "facts-refine" agent skill from https://github.com/av/mi/tree/master/.agents/skills/facts-refine into .cursor/skills/facts-refine/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "facts-refine", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/av/mi.git --path .agents/skills/facts-refine--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add av/mi --skill facts-refine -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install av/mi facts-refine --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/av/mi.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/.agents/skills/facts-refine .gemini/skills/facts-refine && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "facts-refine" agent skill from https://github.com/av/mi/tree/master/.agents/skills/facts-refine into .gemini/skills/facts-refine/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "facts-refine", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install av/mi facts-refineInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add av/mi --skill facts-refine -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/av/mi.git skills-src && mkdir -p .github/skills && cp -r skills-src/.agents/skills/facts-refine .github/skills/facts-refine && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "facts-refine" agent skill from https://github.com/av/mi/tree/master/.agents/skills/facts-refine into .github/skills/facts-refine/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "facts-refine", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add av/mi --skill facts-refine -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install av/mi facts-refine --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/av/mi.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/.agents/skills/facts-refine .opencode/skills/facts-refine && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "facts-refine" agent skill from https://github.com/av/mi/tree/master/.agents/skills/facts-refine into .opencode/skills/facts-refine/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "facts-refine", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
facts-refine- GitHub stars
- 102
- Token cost
- ~1.5k tokens
- SKILL.md length
- 581 words
- Files
- 1
- Skills in repo
- 20
- Repo updated
- First seen
- Licence
- None found
At a glance
Works with you to turn draft behavioral facts into precise, implementable spec facts, resolving vague labels, gaps and contradictions one at a time through discussion.
- Works in 5 steps: Load and identify @draft facts → Identify problems → Discuss with the user → …
- Turning a set of vague draft specs into precise, testable facts
- SKILL.md covers When to use this skill, Process, Guidelines and Example session
- Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
What it does
The skill turns a project's draft facts into spec-ready facts through conversation rather than automation, always proposing a change and letting you decide instead of bulk-editing the fact sheet silently. It starts by loading the fact sheet with facts list and facts list --tags draft, and short CLI aliases like ll, at and rt are available for quick tagging during the session.
Each draft fact is checked against four problem categories: structural facts that describe what exists rather than what happens, which are tested by asking whether the fact alone would let an agent rebuild the right behavior; vague or untestable labels such as handles errors properly; gaps where a section has far fewer facts than its topic implies; and contradictions where two facts, or their validation commands, cannot both be true. The excerpt is cut off while still listing the contradiction category.
When your agent uses it
- Turning a set of vague draft specs into precise, testable facts
- Reviewing a fact sheet for gaps, contradictions or vague labels
- Sharpening a fact's wording together with the user before marking it spec-ready
Example prompts
- “Refine the draft facts in the auth section into testable spec facts.”
- “Check the fact sheet for contradictions between the billing and auth sections.”
- “Walk through each draft fact with me and help me make the vague ones testable.”
Requirements
- The facts CLI
Workflow steps
5 steps, taken from the step headings in SKILL.md.
- Load and identify @draft facts
- Identify problems
- Discuss with the user
- Apply agreed changes
- Verify and summarize
What it can do on your machine
Read from SKILL.md and the folder at commit 2bf50c9. It shows what the files ask for, not the result of running them.
Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
No scripts in the folder and no shell commands in SKILL.md.
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Context cost
Facts Spec Refiner loads about 1.5k tokens when it runs. Until then it costs about 83 tokens; SKILL.md has 581 words of instructions outside code blocks.
Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.
Safety
Auto-check passed
The automated check found no risky patterns in SKILL.md.
Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.
SKILL.md
Without a licence we can't republish the file, so here is its outline and opening line. It has 581 words (~1,480 tokens).
“You are a fact sheet editor. Your job is to take @draft facts and work with the user to turn them into precise, actionable @spec facts — through conversation, not automation. This is the @draft → @spec lifecycle transition.”
- name
- facts-refine
Files
Just SKILL.md in .agents/skills/facts-refine of av/mi.
Open the folder on GitHubat commit 2bf50c9
Used in 1 other repository
We found 1 copy of this SKILL.md (exact, near-identical or edited) in other folders. This page covers the copy in av/mi, which our catalogue first saw on October 7, 2026.
Compare with similar skills
Facts Spec Refiner next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Facts Spec Refiner this skillav/mi | 102 | — | ~1.5k | Automated safety check: Pass | None | |
| Spec-Driven Developmentaddyosmani/agent-skills | 103k | 1 repos | ~3.2k | Automated safety check: Pass | MIT | |
| MoAI SPEC Workflowmodu-ai/moai-adk | 1.2k | — | ~5.1k | Automated safety check: Pass | Apache-2.0 | |
| Feature Spec Generatorcashew-labs/libretto | 904 | — | ~2.4k | Automated safety check: Pass | MIT | |
| Spec Writergarrytan/gstack | 136k | — | ~14k | Automated safety check: Notes | MIT | |
| Feature Specificationowainlewis/blueprint | 412 | — | ~938 | Automated safety check: Pass | MIT |
Similar skills
MoAI SPEC Workflow
modu-ai/moai-adk
Manages SPEC documents for MoAI-ADK development, with GEARS or EARS requirement notation, acceptance criteria and a link into the Plan-Run-Sync workflow.
Feature Spec Generator
cashew-labs/libretto
Researches the codebase and relevant docs, asks clarifying questions, then writes a spec sheet in specs/ for a significant feature or complex fix.
Spec Writer
garrytan/gstack
Converts a vague idea into a precise, executable spec in five phases, files it as an issue and can start an agent on it in a fresh worktree.
Feature Specification
owainlewis/blueprint
Writes one implementation-ready spec for a feature or major change, settling behavior, technical design, failure handling and acceptance checks before delivery.
Spec Coder
LeoYeAI/openclaw-master-skills
Structured spec-first development workflow with multi-role expert review gates: clarify requirements, author spec documents (requirements/design/tasks), generate code from spec, verify with real…
More from av/mi
All 20 skills in this repoWrites plain-English integration test specs with verifiable steps and expectations, then runs each one through a subagent that reports pass or fail with logs.
Anneal
av/mi
A skill your agent uses when the user wants to systematically fix AI code slop — duplicated logic, over-engineering, silent error swallowing, convention drift, cargo-cult patterns, and other…
Scans a codebase to tag every fact as draft, spec or implemented based on what the code actually shows, adding missing facts and fixing or removing wrong ones.
Facts Implementer
av/mi
Implements every @spec fact from a project's fact sheet in code, tags each one @implemented once done, and reports exactly what is left if it cannot finish.
Ideate
av/mi
Timeboxed ideation on a topic using propose-and-critique subagent pairs.
Self
av/mi
Answer questions about how 'mi' works, write new tools, or modify the harness.
Related
Categories
Questions about Facts Spec Refiner
What does Facts Spec Refiner do?
Works with you to turn draft behavioral facts into precise, implementable spec facts, resolving vague labels, gaps and contradictions one at a time through discussion. The skill turns a project's draft facts into spec-ready facts through conversation rather than automation, always proposing a change and letting you decide instead of bulk-editing the fact sheet silently. It starts by loading the fact sheet with facts list and facts list --tags draft, and short CLI aliases like ll, at and rt are available for quick tagging during the session.
When should I use Facts Spec Refiner?
Facts Spec Refiner fits situations like: turning a set of vague draft specs into precise, testable facts; reviewing a fact sheet for gaps, contradictions or vague labels; sharpening a fact's wording together with the user before marking it spec-ready.
How do I install Facts Spec Refiner in Claude Code?
Run `npx skills add av/mi --skill facts-refine -a claude-code`. Or copy the skill folder (.agents/skills/facts-refine in av/mi) into .claude/skills/facts-refine in your project. Claude Code loads it when a task matches its description.
How do I install Facts Spec Refiner in Codex?
Run `npx skills add av/mi --skill facts-refine -a codex`. Or copy the skill folder (.agents/skills/facts-refine in av/mi) into .agents/skills/facts-refine in your project. Codex loads it when a task matches its description.
Can I use Facts Spec Refiner in Cursor, Gemini CLI or GitHub Copilot?
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add av/mi --skill facts-refine -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/facts-refine, .gemini/skills/facts-refine, .github/skills/facts-refine and .opencode/skills/facts-refine in your project.
What does Facts Spec Refiner need to run?
SKILL.md names no scripts, command-line tools or credentials: Facts Spec Refiner is instructions for the agent only. Our summary lists: The facts CLI.
Does Facts Spec Refiner access the network?
SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.
Is Facts Spec Refiner safe to install?
Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.
What licence does Facts Spec Refiner use?
No licence was found for Facts Spec Refiner or its repository. Without one, default copyright applies: ask the author before reusing or redistributing it.
How many tokens does Facts Spec Refiner use?
About 1.5k tokens (SKILL.md is roughly 5.9k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.
What are the alternatives to Facts Spec Refiner?
Skills that share tags, products or a category with Facts Spec Refiner: Spec-Driven Development (addyosmani/agent-skills, 103k stars), MoAI SPEC Workflow (modu-ai/moai-adk, 1.2k stars), Feature Spec Generator (cashew-labs/libretto, 904 stars) and Spec Writer (garrytan/gstack, 136k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains Facts Spec Refiner?
av (a GitHub user) maintains it in av/mi, which has 102 GitHub stars. The repository holds 20 skills in this directory. The repository was last updated on September 26, 2026.
Source: av/mi on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.