Finding-Unknowns Skills
13 installable agent skills that surface what you don't know before your coding agent builds it — so unknowns don't get expensive.
- Source repo
- Neeeophytee/finding-unknowns-skills
- Stars
- ★ 353
- Last updated
- 27d ago
- License
- MIT
- Primary language
- Python
- FA score
- 76/100 · Good
At a glance
- How it runs
- Works with
- Universal · cross-platformClaude Code · Claude.aiCodex (Partial support)
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A developer new to an unfamiliar part of the codebase or a whole domain, using blindspot-pass before writing any code
- Not a fit if
- Teams not using a host coding agent like Claude Code, Codex, Cursor, Kimi, or Hermes
- Users wanting a standalone tool that runs without a host agent
- Users who need official Anthropic support or guarantees
- Source review
- 76/100 · Good
What does this agent do, and when should you use it?
A collection of 13 installable skills packaged in SKILL.md format for coding agents including Claude Code, OpenAI Codex, Kimi Code CLI, Cursor, and Hermes Agent. Eleven skills are distilled, with attribution, from two public essays by Thariq Shihipar of Anthropic's Claude Code team: eight task-level skills (blindspot-pass, interview-me, reference-hunt, implementation-plan, and others) plus three context-level skills (context-audit, agent-interface-design, progressive-disclosure). The remaining two — assumption-test and test-blindspots — are maintainer-designed extensions grounded in established testing practice. These skills are instruction packages for an agent, not standalone programs: once installed, the host agent triggers them from their descriptions or you invoke them via slash commands at the right phase (before, during, or after implementation). The project is community-maintained, explicitly not an official Anthropic repository, and MIT-licensed.
Each skill is a folder containing a SKILL.md that injects concrete instructions and deliverable definitions into the agent. Task-level skills: blindspot-pass (surface unknown unknowns in unfamiliar areas), brainstorm-prototypes (throwaway variations to react to), interview-me (architecture-changing questions one at a time), reference-hunt (use working source code as the spec, even across languages), implementation-plan (leads with decisions you're most likely to change), implementation-notes (log every deviation from plan), pitch-packager (bundle spec + prototype + notes into a buy-in doc), and change-quiz (comprehension quiz before merging). Context-level skills: context-audit (find contradictions, duplicates, dead rules in CLAUDE.md and skills), agent-interface-design (design tools an agent can't misuse), and progressive-disclosure (split oversized skills into an entry file plus on-demand files). Extensions: assumption-test (turn a consequential assumption into a bounded, falsifiable experiment) and test-blindspots (probe what passing tests do not establish). Install via npx skills add Neeeophytee/finding-unknowns-skills (auto-detects your agent), as a Claude Code plugin, or by copying skill folders into the agent's skills directory.
- A developer new to an unfamiliar part of the codebase or a whole domain, using blindspot-pass before writing any code
- Anyone making 'you'll know it when you see it' decisions in design, UX, or tone, using brainstorm-prototypes to generate variations
- A team whose CLAUDE.md has grown unreadable and whose agent ignores its own instructions, using context-audit to cut dead rules
- Someone building a tool, MCP server, or script that an agent will call, using agent-interface-design to make misuse hard
- A user whose single skill or spec is too long to keep loading, using /progressive-disclosure to split it into on-demand files
- A developer about to merge a risky change, using change-quiz to test comprehension and test-blindspots to check what passing tests miss
How do you install or deploy this agent?
Option one (recommended): npx skills add Neeeophytee/finding-unknowns-skills — the Vercel skills CLI detects your agent (Claude Code, Cursor, Codex, Copilot, Gemini, etc.); add --list to preview or --skill blindspot-pass for one skill. Option two (Claude Code plugin, all 13): /plugin marketplace add Neeeophytee/finding-unknowns-skills then /plugin install finding-unknowns@finding-unknowns-skills. Option three (manual): copy any skills/<name>/ folder into your project's .claude/skills/ or global ~/.claude/skills/. Codex uses ~/.agents/skills/, Kimi uses ~/.kimi/skills/, and Hermes points skills.external_dirs in ~/.hermes/config.yaml at the cloned skills directory. Alternatively copy guidance/finding-unknowns.md as your project's CLAUDE.md or AGENTS.md for passive guidance. You need the host coding agent CLI installed; no API key setup exists in the repo itself (skills are instruction files read by the host agent).
How do you use this agent?
After installation the agent reaches skills on its own from their descriptions, or you trigger them manually: Claude Code via slash command (e.g. /context-audit), Codex via $context-audit or the /skills picker, Hermes via /context-audit, and Cursor/Kimi K3 via their own skills UI or SKILL.md autodiscovery. Note that progressive-disclosure sets disable-model-invocation: true, making it user-invoked only in Claude Code; Codex (verified on v0.143) ignores the flag and loads it into the model-visible prompt anyway. Pick by phase: before building use blindspot-pass, interview-me, reference-hunt, or assumption-test; run implementation-notes during; use pitch-packager and change-quiz after; use context-audit, agent-interface-design, and progressive-disclosure on the context layer your agent carries into every task.
What are this agent's strengths and limitations?
- Cross-agent portability: the same SKILL.md files are natively read by Claude Code, Codex, Kimi K3, Cursor, and Hermes, with a one-command installer via
npx skills add - Three distinct layers of method — task-level, context-level, and evidence-level — covering both unknowns in a single prompt and unknowns baked into inherited context
- Traceable provenance: eleven skills are explicitly attributed to two public essays, the two extensions ship with an evaluation protocol and fixtures (evals/), and a CI workflow validates the skills
- Unusually detailed documented receipts, including re-test dates for Codex CLI v0.143 and Hermes v0.15.1, verification commands (codex debug prompt-input), and known behavioral differences
- Documented behavioral inconsistency costs:
disable-model-invocationis ignored by Codex so progressive-disclosure occupies context there, and CLI discovery does not prove Cursor actually invokes skills - It is a community project, not an official Anthropic repository; skill quality depends on the maintainer's distillation, so you should review EXAMPLES.md before adopting
- Compatibility verification is incomplete on some surfaces: Hermes was only checked for
enabledstatus inhermes skills list, and skills require a host agent CLI as runtime — they cannot run standalone - The method derives from context-engineering essays written for Claude 5-generation models; no documented evidence covers effectiveness on other model families
How does this agent compare with similar options?
Compared with reading Thariq Shihipar's essays directly, this repo turns the method into installable, triggerable, reusable SKILL.md skills; compared with passive CLAUDE.md/AGENTS.md guidance, it adds imperative workflows plus two testing extensions, while still shipping a passive guidance file (guidance/finding-unknowns.md).
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Finding-Unknowns Skills This agent | 76 · Good | Agent plugin / skillFree | ★ 353 | 27d ago | Python | Claude Code · Claude.ai |
| Waza | 63 · Some gaps | CLIFree | ★ 7.4k | 1d ago | Python | Codex · Claude Code |
| EOC — Everything OpenAI Codex Workflow OS | 75 · Good | Agent plugin / skillFree + model costs | ★ 83 | 2mo ago | JavaScript | Codex |
| Agent Skills for Context Engineering | 49 · Major gaps | Agent plugin / skillFree + model costs | ★ 18k | 13d ago | Python | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
All 13 skills are pure instruction files with no tool calls, credential access, or network side effects, so least privilege and external effects are inherently constrained — scored 2 each (no privilege surface seen, but no explicit safety argument either); user confirmation scored 2 (README supports --list preview before install; interview-me is question-by-question); data flow transparency 2 (all skill text is inspectable); sensitive data handling is never addressed — 1; rollback/uninstall path is undocumented — 1; source attribution is exemplary (both essays, NOTICE.md, explicit non-official-Anthropic disclaimer) — 3.
Self-consistency is strong: CI validation enforces directory names, YAML keys, version agreement, README counts, and link validity, and tests/test_repository.py proves these gates via mutation tests — 3; availability depends on external CLIs (skills CLI, Codex, Hermes, Kimi) whose tested versions are recorded but unverifiable statically — 2; validator failure messages are specific (visible in test assertions) but cover repo structure, not runtime behavior — 2.
Audience and scenarios are well mapped via the 'When to reach for which' table — 3; trigger precision is good, including per-agent handling of disable-model-invocation — 3; environment fit is excellent with four agent-specific install and verification paths — 3; capability boundaries are partially stated (task vs context layers) but failure modes and unsuitable cases are not — 2.
Information architecture is strong: phase grouping, per-skill folders, a single-file guidance variant, and documented relocation of root CLAUDE.md/AGENTS.md — 3; install notes cover all four agents with dedicated docs — 3; naming stability is CI-enforced with digests — 3; known limitations are honestly stated (Codex ignoring the flag, untested Hermes surfaces) — 3; MIT LICENSE present in full — 3; CHANGELOG, tagged releases, and version-drift tests support versioning — 3; EXAMPLES.md is referenced but its content is not in evidence — 2; maintenance rests on a pseudonymous identity with CI/CONTRIBUTING present but no accountable maintainer signal — 2.
Output usability: each skill promises concrete deliverables with consistent structure, but static review cannot confirm output quality — 2; marginal value: packaging of a public methodology into installable commands is incremental rather than novel — 2; cost-benefit is favorable: lightweight instructions that actively manage context cost — 2.
Claim traceability: versions, test dates, and verification commands are named but not executable in a static review — 2; cross-source corroboration: external essays and docs are cited and link-checked, but content accuracy is unconfirmed — 2; fact/inference separation is excellent — 'verified on v0.143' is distinguished from general claims, and 'CLI discovery alone does not verify Cursor invocation' shows the distinction explicitly — 3.
- Publisher is an unverified pseudonymous identity; audit skill instruction content yourself before enterprise use.
- All runtime verification claims (Codex v0.143, Hermes v0.15.1) are self-reported in the README; this review executed nothing — re-verify after upgrades.
- Codex ignores disable-model-invocation, so progressive-disclosure enters the model-visible prompt there.
- No uninstall/rollback path or sensitive-data guidance is documented; mind context exposure when using interview-me or pitch-packager on confidential material.
- Skills rely on the host agent following natural-language instructions; static review cannot guarantee actual behavior.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v1.5.0 v1.5.0 — Regression proof
Release notes excerpt
Adds regression-proof, bringing the collection to 14 skills. It guides bug fixes through a reproducer, a regression test that fails on the original behavior, a scoped correction, and verification of neighboring behavior. Review-only requests remain review-only. - All 13 existing skill files are unchanged, protected by SHA-256 regression checks. - Both plugin manifests are version 1.5.0; the Claude plugin explicitly includes the new skill. - Includes usage examples, concise source attribution, and a repository citation crediting Shilpa Mitra. …View on GitHub ↗ -
v1.4.0 v1.4.0 — Evidence skills and repository validation
Release notes excerpt
New skills - assumption-test turns a consequential technical assumption into a bounded, falsifiable experiment. - test-blindspots investigates important behavior that passing tests do not establish. All eleven existing skill files are unchanged byte-for-byte from v1.3.0. Both plugin manifests are updated together, and the Claude plugin includes the two new skills. Documentation and maintenance - Add live README badges, expanded examples, contribution guidance, a Code of Conduct, compatibility records, a roadmap, and a changelog. …View on GitHub ↗ -
v1.3.0 v1.3.0 — Codex plugin + Hermes install
Release notes excerpt
Extends multi-agent support with two verified install routes. No new skills, and no change to the existing eight or the v1.2.0 three — all 11 are untouched. New install routes OpenAI Codex — as a plugin ``` codex plugin marketplace add Neeeophytee/finding-unknowns-skills codex plugin add finding-unknowns@finding-unknowns ``` …View on GitHub ↗