Agent skill

Unknowns Discovery

by secondsky in secondsky/claude-skills

Discover and reduce task unknowns — blindspots, missing context, and unknown unknowns — before committing to a plan, implementation, review, or merge.

MITAuto-check passed

Install Unknowns Discovery

skills CLI
$ npx skills add secondsky/claude-skills --skill unknowns-discovery -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install secondsky/claude-skills unknowns-discovery --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/secondsky/claude-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/plugins/unknowns-discovery/skills/unknowns-discovery .claude/skills/unknowns-discovery && rm -rf skills-src

Use ~/.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/

Facts

Skill name
unknowns-discovery
GitHub stars
227
Token cost
~1.9k tokens
SKILL.md length
822 words
Files
28 (incl. scripts, references, assets)
Skills in repo
169
Repo updated
First seen
Licence
MIT

At a glance

Discover and reduce task unknowns — blindspots, missing context, and unknown unknowns — before committing to a plan, implementation, review, or merge.

  • Works in 6 steps: State the map. Restate the task,… → Inspect the territory. Read relevant… → Build an unknowns matrix. Separate known… → …
  • SKILL.md covers Unknown types, When to activate, Core loop and Artifact mode selector, plus 5 more sections

What it does

Unknowns Discovery is an agent skill from secondsky/claude-skills. Discover and reduce task unknowns — blindspots, missing context, and unknown unknowns — before committing to a plan, implementation, review, or merge.

Its SKILL.md is about 1.9k tokens, which your agent loads only when the skill is triggered. The skill folder holds 30 other files, including scripts, reference files and assets (for example `assets/templates/assumptions-register.md`, `assets/templates/blindspot-pass.md` and `assets/templates/brainstorm-prototype.md`).

The repository describes itself as: Production-ready skills for Claude Code CLI - Cloudflare, React, Tailwind v4, and AI integrations. The licence is MIT.

Example prompts

  • “/unknowns-discovery”

Workflow steps

6 steps, taken from the first numbered list in SKILL.md.

  1. State the map. Restate the task, constraints, and what the user says they know.
  2. Inspect the territory. Read relevant files, docs, examples, data, screenshots, references, prior work, or user-provided context.
  3. Build an unknowns matrix. Separate known knowns, known unknowns, unknown knowns, and unknown unknowns.
  4. Choose the cheapest useful artifact. Pick the mode that exposes the highest-blast-radius unknown earliest.
  5. Gate implementation. Proceed only when dangerous unknowns are resolved, explicitly accepted, or isolated behind reversible decisions.
  6. Carry discoveries forward. Fold the discoveries into a better prompt, plan, implementation note, buy-in doc, quiz, tests, or review…

What it can do on your machine

Read from SKILL.md and the folder at commit 8837836. 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

    Ships 1 file in scripts/, which the agent can run.

    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

Unknowns Discovery loads about 1.9k tokens when it runs, and up to ~9.4k if it reads all its reference files. Until then it costs about 42 tokens; SKILL.md has 822 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~42
When it runs · the whole SKILL.md, loaded when a task matches
~1.9k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~9.4k

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); the scripts in this folder are not scanned.

SKILL.md

The full file from secondsky/claude-skills at commit 8837836, republished under its MIT licence (© secondsky). 822 words, ~1,926 tokens.

Download SKILL.mdSave it as .claude/skills/unknowns-discovery/SKILL.md (or your agent's skills folder). This skill also uses 27 other files; get the full folder from GitHub.
name
unknowns-discovery
description
Discover and reduce task unknowns — blindspots, missing context, and unknown unknowns — before committing to a plan, implementation, review, or merge.

Unknowns Discovery

Use this skill when an agent should discover what the user, spec, prompt, or codebase is missing before it commits to a plan, implementation, review, or merge.

The prompt, skill, ticket, screenshot, and context window are the map. The real codebase, product, users, data, constraints, history, and reviewer expectations are the territory. The gap between them is the task's unknowns.

Unknown types

TypeMeaningAgent move
Known knownsExplicit facts and constraints in the promptPreserve and restate briefly
Known unknownsQuestions already recognized as openAsk, research, parameterize, or gate
Unknown knownsTacit standards the user would recognize only after seeing themPrototype, mock, compare, or interview
Unknown unknownsHidden constraints, missing vocabulary, prior art, traps, or quality ceilings nobody mentionedRun blindspot passes, inspect references, search code/history, and surface landmines

When to activate

Activate this skill when any of these are true:

  • The work is multi-step, ambiguous, unfamiliar, high-risk, or likely to require judgment.
  • The user mentions “blindspot pass,” “unknown unknowns,” “what am I missing,” “interview me,” “prototype first,” “implementation notes,” “buy-in doc,” “quiz me,” or similar.
  • The user lacks domain vocabulary or does not know what good looks like.
  • The task involves codebase history, architecture, data model, permissions, migrations, UX, visual design, product scope, rollout, or reviewer approval.
  • The agent is about to start a long-horizon implementation or has already discovered that the plan and codebase disagree.

Do not activate for tiny deterministic tasks where exploration would add friction, such as fixing a typo, renaming a variable, or answering a direct question with no meaningful unknowns.

Core loop

  1. State the map. Restate the task, constraints, and what the user says they know.
  2. Inspect the territory. Read relevant files, docs, examples, data, screenshots, references, prior work, or user-provided context.
  3. Build an unknowns matrix. Separate known knowns, known unknowns, unknown knowns, and unknown unknowns.
  4. Choose the cheapest useful artifact. Pick the mode that exposes the highest-blast-radius unknown earliest.
  5. Gate implementation. Proceed only when dangerous unknowns are resolved, explicitly accepted, or isolated behind reversible decisions.
  6. Carry discoveries forward. Fold the discoveries into a better prompt, plan, implementation note, buy-in doc, quiz, tests, or review artifact.

Artifact mode selector

ModeUse whenOutput
blindspot-passUnfamiliar codebase/domain/design area; likely unknown unknownsBlindspot cards + better implementation prompt
teach-me-my-unknownsUser lacks vocabulary or quality criteriaMental model + vocabulary ladder + improved prompts
brainstorm-prototypeUser will know it when they see itDivergent prototypes/options + reaction template
mock-before-wireNeed to see UI/flow before backend/state/app changesThrowaway mock with fake data + wiring plan
option-space-brainstormProblem framing may be too narrow or too wideRanked interventions from cheapest to ambitious
one-question-interviewAmbiguity remains after explorationOne question at a time, ordered by blast radius
reference-semantics-mapExisting code/design/doc is the best descriptionSemantics map before porting/adapting
tweakable-planReady to implement but human should review change-prone partsPlan sorted by likely human-tweak points before execution order
implementation-notesImplementation is underway and surprises appearRunning log of deviations and conservative choices
buy-in-docWork needs approval or stakeholder alignmentDemo-first pitch/explainer with objections and signoffs
merge-readiness-quizHuman must understand a complex change before merge/releaseReport + quiz with pass criteria

Detailed procedures are in references/WORKFLOWS.md. Copyable prompt cards are in references/PROMPT_PATTERNS.md. Output schemas are in references/OUTPUT_SCHEMAS.md.

Show full SKILL.md (282 more words)Show less

Default output contract

Every unknowns artifact should include:

  1. Scope read: What was inspected or assumed.
  2. Unknowns found: Labels by unknown type and severity.
  3. Blast radius: What changes if this unknown is answered differently.
  4. Conservative default: What the agent will do if forced to proceed.
  5. Decision needed: What the user must choose, if anything.
  6. Prompt upgrade: A revised prompt/instruction incorporating discoveries.
  7. Stop conditions: Cases where guessing is unacceptable.

Autonomy rules

  • Ask before acting when an unknown can change architecture, data model, auth, privacy, compliance, cost, public API, migration, rollout, or user-facing behavior.
  • Proceed conservatively when the unknown is low-risk, reversible, and the user has asked not to be interrupted. Label assumptions as ASSUMED.
  • Prototype before wiring when feedback depends on taste, layout, copy tone, interaction flow, information architecture, or data density.
  • Prefer source references over prose when behavior already exists elsewhere.
  • During implementation, log every material deviation before continuing.
  • Do not merge complex agent work on diff-skimming alone; create a report and quiz if understanding matters.

Stop immediately when

  • The territory contradicts the task goal.
  • The unknown could cause data loss, auth bypass, privacy leak, billing impact, destructive migration, public API break, or compliance failure.
  • A prior failed/reverted attempt appears and the reason still applies.
  • Exact legal/security/compliance behavior is requested but the authoritative source is absent.

Minimal examples

text
Do a blindspot pass before implementation. Find unknown unknowns, explain why each matters, and rewrite my prompt with the discoveries folded in.
text
Before touching the app, make a single HTML mock with fake data so I can react to layout and product decisions.
text
Keep implementation-notes.md as you build. If code forces a plan deviation, choose the conservative option, log it under Deviations, and continue unless it affects security/data/migrations/API/compliance.
text
Give me a merge-readiness report with a quiz at the bottom. I should not merge until I pass it perfectly.

Packaged resources

© secondsky, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 27 other files (scripts, references, assets) in plugins/unknowns-discovery/skills/unknowns-discovery of secondsky/claude-skills.

  • SKILL.md
  • assets/templates/assumptions-register.md
  • assets/templates/blindspot-pass.md
  • assets/templates/brainstorm-prototype.md
  • assets/templates/buy-in-doc.md
  • assets/templates/domain-vocabulary-ladder.md
  • assets/templates/implementation-notes.md
  • assets/templates/merge-readiness-quiz.md
  • assets/templates/one-question-interview.md
  • assets/templates/prompt-upgrade.md
  • assets/templates/reference-semantics-map.md
  • assets/templates/tweakable-plan.md
  • assets/templates/unknowns-matrix.md
  • examples/coding-auth-provider.md
  • examples/generated-blindspot-starter.md
  • examples/product-design-dashboard.md
  • examples/research-project.md
  • references
  • … and 10 more

Open the folder on GitHubat commit 8837836

Compare with similar skills

Unknowns Discovery 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.

Unknowns Discovery compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Unknowns Discovery this skillsecondsky/claude-skills227—~1.9kAutomated safety check: PassMIT
Discover Pluginsruvnet/ruflo74k—~2kAutomated safety check: NotesMIT
Reduced Motionthedaviddias/Front-End-Checklist74k—~534Automated safety check: PassMIT
Aas Discoversickn33/agentic-awesome-skills47k1 repos~523Automated safety check: PassMIT
Discoverbrycewang-stanford/Auto-Empirical-Research-Skills4.5k—~2.2kAutomated safety check: PassCustom licence
Unknownteam-attention/plugins-for-claude-natives827—~1.7kAutomated safety check: PassMIT

Similar skills

  • Discover Plugins

    ruvnet/ruflo

    Discover and recommend ruflo plugins based on your workflow, installed MCP tools, and current task

    74k GitHub stars~2k tokensUpdated today
    Agent WorkflowsAuto-check: notes
  • Reduced Motion

    thedaviddias/Front-End-Checklist

    A skill your agent uses when reviewing rendered HTML, interactive components, or design-system patterns related to Respect reduced motion preferences.

    74k GitHub stars~534 tokensUpdated yesterday
    Frontend & DesignAuto-check passed
  • Aas Discover

    sickn33/agentic-awesome-skills

    Discover AAS skills for an explicit task and compare their complete instructions without installing them.

    47k GitHub starsUsed in 1 repo~523 tokens
    Auto-check passed
  • Discover

    brycewang-stanford/Auto-Empirical-Research-Skills

    Discovery phase combining research interviews, literature search, data discovery, and ideation.

    4.5k GitHub stars~2.2k tokensUpdated 2 days ago
    Agent WorkflowsAuto-check passed
  • Unknown

    team-attention/plugins-for-claude-natives

    This skill should be used when the user provides a strategy, plan, or decision document and wants to surface hidden assumptions and blind spots using the Known/Unknown 4-quadrant framework.

    827 GitHub stars~1.7k tokensUpdated 5 mo ago
    Auto-check passed
  • Reduce

    agenticnotetaking/arscontexta

    Extract structured knowledge from source material. An agent skill from agenticnotetaking/arscontexta.

    3.5k GitHub starsUsed in 1 repo~11k tokens
    Auto-check passed

More from secondsky/claude-skills

All 169 skills in this repo
  • Tanstack AI

    secondsky/claude-skills

    TanStack AI (alpha) provider-agnostic type-safe chat with streaming for OpenAI, Anthropic, Gemini, Ollama.

    227 GitHub starsUsed in 1 repo~3.6k tokens
    Auto-check: notes
  • Auto Animate

    secondsky/claude-skills

    AutoAnimate (@formkit/auto-animate) zero-config animations for React.

    227 GitHub stars~2.9k tokensUpdated 9 days ago
    Auto-check passed
  • Base UI React

    secondsky/claude-skills

    MUI Base UI unstyled React components with Floating UI. An agent skill from secondsky/claude-skills.

    227 GitHub stars~1.9k tokensUpdated 9 days ago
    Auto-check passed
  • Cloudflare Images

    secondsky/claude-skills

    This skill should be used when the user asks to "upload images to Cloudflare", "implement direct creator upload", "configure image transformations", "optimize WebP/AVIF", "create image variants"…

    227 GitHub stars~3.6k tokensUpdated 9 days ago
    Auto-check: notes
  • Cloudflare Nextjs

    secondsky/claude-skills

    Deploy Next.js to Cloudflare Workers via the OpenNext adapter (@opennextjs/cloudflare).

    227 GitHub stars~5.3k tokensUpdated 9 days ago
    Auto-check: notes
  • Cloudflare Sandbox

    secondsky/claude-skills

    Cloudflare Sandboxes SDK for secure code execution in Linux containers at edge.

    227 GitHub stars~4.5k tokensUpdated 9 days ago
    Auto-check passed

Questions about Unknowns Discovery

What does Unknowns Discovery do?

Discover and reduce task unknowns — blindspots, missing context, and unknown unknowns — before committing to a plan, implementation, review, or merge. Unknowns Discovery is an agent skill from secondsky/claude-skills. Discover and reduce task unknowns — blindspots, missing context, and unknown unknowns — before committing to a plan, implementation, review, or merge.

How do I install Unknowns Discovery in Claude Code?

Run `npx skills add secondsky/claude-skills --skill unknowns-discovery -a claude-code`. Or copy the skill folder (plugins/unknowns-discovery/skills/unknowns-discovery in secondsky/claude-skills) into .claude/skills/unknowns-discovery in your project. Claude Code loads it when a task matches its description.

How do I install Unknowns Discovery in Codex?

Run `npx skills add secondsky/claude-skills --skill unknowns-discovery -a codex`. Or copy the skill folder (plugins/unknowns-discovery/skills/unknowns-discovery in secondsky/claude-skills) into .agents/skills/unknowns-discovery in your project. Codex loads it when a task matches its description.

Can I use Unknowns Discovery 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 secondsky/claude-skills --skill unknowns-discovery -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/unknowns-discovery, .gemini/skills/unknowns-discovery, .github/skills/unknowns-discovery and .opencode/skills/unknowns-discovery in your project.

What does Unknowns Discovery need to run?

SKILL.md names no scripts, command-line tools or credentials: Unknowns Discovery is instructions for the agent only.

Does Unknowns Discovery 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 Unknowns Discovery 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. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Unknowns Discovery use?

Unknowns Discovery is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Unknowns Discovery use?

About 1.9k tokens (SKILL.md is roughly 7.7k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 7.5k tokens, read only when the agent opens those files.

What are the alternatives to Unknowns Discovery?

Skills that share tags, products or a category with Unknowns Discovery: Discover Plugins (ruvnet/ruflo, 74k stars), Reduced Motion (thedaviddias/Front-End-Checklist, 74k stars), Aas Discover (sickn33/agentic-awesome-skills, 47k stars) and Discover (brycewang-stanford/Auto-Empirical-Research-Skills, 4.5k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Unknowns Discovery?

secondsky (a GitHub user) maintains it in secondsky/claude-skills, which has 227 GitHub stars. The repository holds 169 skills in this directory. The repository was last updated on September 28, 2026.

Source: secondsky/claude-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.