clarify-first

A tiny Agent Skill that makes Codex, Claude Code, and Gemini CLI ask before they guess.

AI agents are great at filling in blanks. That is useful—until the blank is which database to delete from, what “done” means, or whether an API break is acceptable.

clarify-first adds an explicit clarification mode:

cf: clean up old customer data

Instead of guessing, the agent inspects what it can safely discover, asks one to three decisions that actually matter, and repeats until the task has one clear interpretation. Then it gets to work.

One skill, three runtimes

Codex, Claude Code, and Gemini CLI all support the SKILL.md-based Agent Skills format. This repository keeps one portable source of truth instead of three copies that can drift apart. agents/openai.yaml adds Codex UI metadata; the core behavior lives entirely in clarify-first/SKILL.md.

Why it is useful

• Focused: asks only about choices that can change the result.
• Context-aware: discovers answers from the workspace before bothering you.
• Persistent: one partial answer does not silently resolve every ambiguity.
• Action-oriented: once the contract is clear, it executes without asking for redundant confirmation.
• Tiny: one instruction file, no scripts, no dependencies.

Install

Clone once:

git clone https://github.com/geniusBrainLsm/clarify-first.git

Then install for any or all supported runtimes:

Codex

mkdir -p ~/.codex/skills
cp -R clarify-first/clarify-first ~/.codex/skills/

Restart Codex, then invoke $clarify-first or prefix a request with cf:.

Claude Code

mkdir -p ~/.claude/skills
cp -R clarify-first/clarify-first ~/.claude/skills/

Run /skills to verify discovery. Invoke /clarify-first or use cf:.

Gemini CLI

mkdir -p ~/.gemini/skills
cp -R clarify-first/clarify-first ~/.gemini/skills/

Run /skills reload, then /skills list. Use cf: and approve skill activation when Gemini asks.

Use

Prefix a request with cf::

cf: migrate our authentication flow

Or invoke the skill directly in Codex or Claude Code:

Codex:      Use $clarify-first to plan the customer-data cleanup.
Claude Code: /clarify-first plan the customer-data cleanup

What it clarifies

• scope and exclusions;
• source of truth and data boundaries;
• expected behavior and acceptance criteria;
• destructive side effects and rollback expectations;
• compatibility, API contracts, migrations, and deployment targets;
• conflicts between the request and existing constraints.

It does not turn trivial implementation details into meetings. Details that are already known, safely discoverable, or delegated to the agent stay out of your way.

Example

You
cf: remove inactive accounts

Agent
Should “inactive” mean no sign-in for 90 days, no paid subscription, or both?
This determines which accounts are eligible for removal.

You
No sign-in for 90 days and no paid subscription.

Agent
Should the accounts be hard-deleted or deactivated with a recovery window?
The first is irreversible; the second preserves rollback.

Small questions. Much smaller disasters.

Repository layout

clarify-first/
├── README.md
└── clarify-first/
    ├── SKILL.md
    └── agents/openai.yaml

If this saves you from one expensive misunderstanding, consider starring the repo so other agent builders can find it.

License

MIT