{"id":51617662,"url":"https://github.com/hiendinhngoc/unknowns","last_synced_at":"2026-07-12T15:03:50.163Z","repository":{"id":369414179,"uuid":"1289753929","full_name":"hiendinhngoc/unknowns","owner":"hiendinhngoc","description":"Agent skills (SKILL.md) for discovering your unknowns across the dev lifecycle — from Thariq Shihipar's 'Know Your Unknowns'","archived":false,"fork":false,"pushed_at":"2026-07-05T06:58:49.000Z","size":20,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-05T08:13:55.238Z","etag":null,"topics":["agent-skills","ai-agents","claude-code","codex-cli","hermes-agent","opencode"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hiendinhngoc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-05T06:49:36.000Z","updated_at":"2026-07-05T06:58:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hiendinhngoc/unknowns","commit_stats":null,"previous_names":["hiendinhngoc/unknowns"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/hiendinhngoc/unknowns","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hiendinhngoc%2Funknowns","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hiendinhngoc%2Funknowns/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hiendinhngoc%2Funknowns/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hiendinhngoc%2Funknowns/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hiendinhngoc","download_url":"https://codeload.github.com/hiendinhngoc/unknowns/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hiendinhngoc%2Funknowns/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35394859,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-12T02:00:06.386Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","ai-agents","claude-code","codex-cli","hermes-agent","opencode"],"created_at":"2026-07-12T15:03:49.445Z","updated_at":"2026-07-12T15:03:50.158Z","avatar_url":"https://github.com/hiendinhngoc.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# unknowns\n\nAgent skills for systematically discovering and closing knowledge gaps before,\nduring, and after implementation.\n\nThe techniques come from\n[Know Your Unknowns](https://thariqs.github.io/html-effectiveness/unknowns/)\nby Thariq Shihipar — all credit for the ideas goes to him. This repo turns\nthem into invocable [Agent Skills](https://www.agensi.io/learn/agent-skills-open-standard)\n(SKILL.md format) for Claude Code, Codex CLI, OpenCode, and other agents.\n\n## Skills\n\n| Skill | Phase | What it does |\n|---|---|---|\n| `/unknowns:blindspot` | pre-implementation | Read-only risk recon of an unfamiliar system |\n| `/unknowns:verify-ref` | pre-implementation | Comprehension proof before porting existing code |\n| `/unknowns:mock` | pre-implementation | Throwaway interactive prototype before production code |\n| `/unknowns:log-deviation` | during | Log every place the code forced a plan deviation |\n| `/unknowns:merge-quiz` | pre-merge | Quiz the USER on the riskiest parts of the diff |\n| `/unknowns:unknowns` | any | Orchestrator: detects phase, routes to the right skill |\n\n## Installation\n\n### Claude Code (as a plugin)\n\n```\n/plugin marketplace add hiendinhngoc/unknowns\n/plugin install unknowns@unknowns\n```\n\nRestart Claude Code. Skills appear as `/unknowns:\u003cname\u003e` in every project.\n\nFor local development, add your clone by path instead:\n\n```\n/plugin marketplace add /path/to/unknowns\n```\n\n### Codex CLI\n\nCopy the skill directories into Codex's skills folder:\n\n```bash\ncp -r skills/* ~/.codex/skills/\n```\n\n### OpenCode\n\n```bash\n# global (all projects)\ncp -r skills/* ~/.config/opencode/skills/\n# or per project\ncp -r skills/* .opencode/skills/\n```\n\n### Other agents (Gemini CLI, Cursor, Cline, Hermes, ...)\n\nThe skills are plain `SKILL.md` files following the open Agent Skills standard\n(YAML frontmatter + markdown instructions). Any agent that supports the\nstandard can load them from its skills directory. For agents without native\nskill support, paste a SKILL.md's body into the system/custom prompt — it\nworks as a plain instruction set.\n\n## Usage\n\nInvoke skills directly by name, or let the agent auto-trigger them from the\ndescriptions (\"what am I missing here?\" triggers blindspot, \"port X\" triggers\nverify-ref, etc.).\n\n**Starting work in unfamiliar code:**\n\n```\n/unknowns:blindspot src/billing/\n```\n\n→ ranked list of 5–7 risks, each with a ready-to-paste follow-up prompt.\n\n**Porting or adapting existing code:**\n\n```\n/unknowns:verify-ref port the retry logic from legacy/http_client.py\n```\n\n→ the agent must produce a comprehension proof (data flow, edge cases,\ninvariants, hidden deps) and get your confirmation before writing any code.\n\n**Undecided UX or behavior:**\n\n```\n/unknowns:mock the new filter panel — inline vs sidebar?\n```\n\n→ disposable interactive HTML prototype; ends with a short spec of validated\ndecisions. Prototype code is never copied into the codebase.\n\n**Mid-implementation, when reality contradicts the plan:**\n\n```\n/unknowns:log-deviation the API doesn't support batch deletes after all\n```\n\n→ appends a structured entry to `docs/deviations/YYYY-MM-DD-\u003ctask\u003e.md`.\n\n**Before merging:**\n\n```\n/unknowns:merge-quiz\n```\n\n→ 3–5 questions about the riskiest parts of your diff. Missed answers get\nexplained and flagged; ends with a paste-ready merge-readiness note for the PR.\n\n**Not sure which applies:**\n\n```\n/unknowns:unknowns\n```\n\n→ detects your phase from git state and routes to the right skill.\n\n## Portability notes\n\nThree skills mention Claude Code-specific tools; each degrades gracefully\nelsewhere (the SKILL.md files say so inline):\n\n- **mock** renders via the Artifact tool → other agents write the HTML file\n  and you open it in a browser.\n- **merge-quiz** uses AskUserQuestion for multiple choice → other agents ask\n  in plain text.\n- **unknowns** invokes sub-skills via the Skill tool → other agents follow the\n  named skill's instructions directly.\n\nThe plugin packaging (`.claude-plugin/`) is Claude Code-only; the `skills/`\ndirectory is the portable part.\n\n## Contributing\n\nNew skills welcome — the bar is that they surface unknowns and don't duplicate\nwhat the ecosystem already covers. See [CONTRIBUTING.md](CONTRIBUTING.md) for\nskill structure conventions and local testing. `tests/eval.sh` behavior-tests\nthe non-interactive skills against a live agent (manual, costs tokens). Design\ndocs live in [`docs/specs/`](docs/specs/), with historical implementation plans\nin [`docs/plans/`](docs/plans/).\n\n## Releases\n\nAutomated by [release-please](https://github.com/googleapis/release-please)\nfrom conventional commits: `fix:` bumps patch, `feat:` bumps minor, `feat!:`\nbumps major. It keeps a release PR open on main; merging it tags the release,\nwrites the changelog, and bumps the version in `.claude-plugin/plugin.json`.\n\nThis repo also uses Lore trailers in commit bodies. The two conventions are\nmeant to be combined, not chosen between. Put the conventional commit prefix on\nthe first line, then keep the Lore body and trailers below it. Examples:\n\n```text\nfix: keep local agent state out of reviews\nfeat: add a skill for pre-merge comprehension checks\nfeat!: rename the public skill namespace\n```\n\nTo force a specific version, add a `Release-As: x.y.z` footer to any commit\non main.\n\n## License\n\n[MIT](LICENSE) © 2026 Hien Dinh. Techniques by\n[Thariq Shihipar](https://thariqs.github.io/html-effectiveness/unknowns/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhiendinhngoc%2Funknowns","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhiendinhngoc%2Funknowns","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhiendinhngoc%2Funknowns/lists"}