If you work with a coding agent CLI — OpenCode, Claude Code, or Codex CLI — you've probably noticed the gap between "an LLM that can write code" and "an agent that understands your codebase before it touches anything." This repository closes that gap with two focused, battle-tested skills.
📦 What's in the box
A skill is a bundled set of instructions (a SKILL.md plus optional scripts and references) that teaches your agent a repeatable workflow. This collection ships two:
-
codebase-explorer🔍 — Maps an unfamiliar repository: entry points, module responsibilities, data flow, and the gotchas that bite newcomers. Read-only by design. -
software-engineering-workflow🧱 — Turns a vague task into a deliberate change: discover requirements, pick the simplest safe design, implement, then verify and hand off.
🔍 codebase-explorer: know before you code
When you point it at a repo, it reads top-level docs and local agent instructions first, inventories files with rg --files (or repomix if available), then follows real execution paths — routes, services, storage, output. The result is a structured report: a one-paragraph system overview, a module list, a data-flow diagram, and a "gotchas" section listing surprising conventions or config traps. It scales to the repo: a small project gets a full end-to-end walkthrough; a large one gets only the paths you asked about. It never edits files or leaks secrets.
Use it when: onboarding to a new codebase, scoping a bug, or prepping an agent for a change.
🧱 software-engineering-workflow: change with intent
This skill enforces a lightweight loop. Before coding, it establishes the outcome and inspects the relevant code, tests, and conventions — asking you only what it can't safely infer. For larger codebases it recommends running codebase-explorer first:
npx skills add https://github.com/mbuyco/skills --skill codebase-explorer
During implementation it favors the simplest design that meets the need (KISS, YAGNI), often prototyping core logic in one file before fanning out. Afterward it runs the narrowest meaningful checks — not just lint — and reports what changed, the key decision, assumptions made, and remaining risks.
Use it when: you want the agent to plan and implement, not just autocomplete.
🤝 Why they work together
codebase-explorer answers "how does this work?"; software-engineering-workflow answers "how do we change it safely?" Run the explorer to build shared context, then hand that context to the workflow skill so your agent edits with understanding instead of guesses.
🚀 Getting started
Drop the skills into skills/, .opencode/skills/, or ~/.config/opencode/skills/. Invoke by name — /skill codebase-explorer — or let your harness auto-select based on your request.
Both are compatible with OpenCode, Claude Code, and Codex CLI. Start exploring, then start building. 🎯
