giant-brains-claude-skills
Claude-AI-Tools-Ventura-County/giant-brains-claude-skills
Instalação
npx convez-ai Claude-AI-Tools-Ventura-County/giant-brains-claude-skills1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Giant Brains Claude Skills
Eight Claude Code skills that catch you at the moment of a decision — and again when you're improving something — and force a short, honest answer you can act on in seconds.
New here? Jump to Install — a symlink loop puts all eight in Claude Code in under a minute.
About
A suite of skills for Claude Code that bring hygiene to the whole life of getting something better — first deciding well, then improving it verifiably. Each fires at a different moment and forces the response into a short, scannable shape — so a human operator can act fast without missing what matters. The throughline: make the implicit explicit, lead with the line that survives skimming, and refuse rather than fake it.
What you get
- Faster calls, fewer blind spots. Every answer leads with the one line that must survive skimming, then adds only the fields that change the decision — no wall of text to wade through.
- Hidden tradeoffs made explicit. The cost you're actually paying — the corner you're sacrificing, the assumption you're betting on, the blast radius of the path you picked — gets named out loud before you commit.
- A shared reversibility read. The decision skills speak one vocabulary — Easy / Costly / One-way door — so a cheap two-way door never gets treated like a commitment that's expensive to unwind.
- Honest signal, not constant alarm. They stay quiet when a change is small and reversible, and refuse rather than fake a verdict they can't stand behind. Calibration is as much about declining as raising a flag.
- Improvement you can prove. Act II turns "make it better" into a metric, an un-gameable oracle, and a baseline, then runs a self-verifying loop that returns a real, numbered win — or a clean "no gain found."
- A paper trail that outlives the chat. The decision, the bet it rides on, and a revisit date get written to the repo at commit time — so six months later, "why is it built this way?" has an answer.
When to reach for it
- You're about to commit to a plan or migration and want to pressure-test the framing before you start — take-a-step-back.
- A deadline is squeezing you and you need to name which of speed, cost, or quality you're actually trading away — iron-triangle.
- You're eyeing a refactor or schema change and need to know how far it ripples and how hard it is to undo — blast-radius.
- An agent handed you a wall of options and you just need the call — bottom-line.
- An agent gave you scattered steps or a verbose completion message and you need the execution sequence — linear.
- You told an agent "make this faster" but can't tell whether it actually did — baseline-spec to define what "better" means, then auto-improve to prove it.
- You just made a call that's expensive to unwind and want the bet written down before it evaporates — record-decision.
Act I — Deciding well (decision hygiene)
Four skills that fire around a decision, each answering a different question at a different moment.
| Skill | The operator's question | Its job |
|---|---|---|
| take-a-step-back | "Am I making the best decision possible?" | Frame — challenge the plan and the problem before committing |
| iron-triangle | "Which of speed, cost, or quality am I trading away?" | Price — make the implicit tradeoff explicit |
| blast-radius | "How big is the path I chose, what breaks, how hard to undo?" | Size — measure cost and reversibility of a chosen path |
| bottom-line | "There's too much here — what's the call?" | Cut — compress overload and analysis paralysis into a decision |
They chain along the life of a decision: frame it (should I, and is this the right problem?), price the tradeoff (which corner gives?), size the chosen path (how big, what breaks?), then cut to the bottom line when the analysis balloons. The same situation can touch all four precisely because they answer different questions at different moments.
The bridge — from deciding to doing
Once the call is made, one skill turns it into motion.
| Skill | The operator's question | Its job |
|---|---|---|
| linear | "The steps are scattered — what's the execution order?" | Sequence — extract and order procedural steps into one top-to-bottom plan |
linear is not a decision skill — it fires once a call exists and the doing is scattered. It's the natural handoff from bottom-line (decision made → ordered plan), but it earns its keep anywhere steps hide in prose: a verbose how-to from an agent mid-project, or a completion message at the tail end whose remaining work is smeared across "what I didn't do," "open items," and "next steps." Whenever someone must execute three or more steps, linear collapses them into one numbered, top-to-bottom plan — branches as sub-bullets, verification inline, nothing actionable after the list.
Act II — Improving verifiably (measure, then optimize)
Once you've decided to make something concretely better, a second pair carries it from a vibe to a proven result.
| Skill | The operator's question | Its job |
|---|---|---|
| baseline-spec | "What does 'better' even mean, and how would I know?" | Define — turn "make it better" into a metric, oracle, budget, and baseline |
| auto-improve | "Now make it better — provably, not just plausibly." | Improve — run a bounded, self-verifying loop, or honestly report no gain |
These chain too: define the measurable contract, then improve against it. The routing is deliberately one-directional — a cold-start request like "optimize this" belongs to baseline-spec (the definer), which fires first; auto-improve (the executor) defers any undefined request back to it and only runs once a metric, an un-gameable oracle, and a budget already exist. baseline-spec refuses to optimize a goal it can't measure — exactly the Act I instinct of refuse rather than fake it — and hands off to auto-improve once the three pillars are locked. auto-improve is the suite's one executional skill: instead of emitting a verdict, it runs a ratcheted mutate-measure-keep-or-revert search and returns either a verified, numbered win or a clean "no real improvement found." See its README and operator FAQ.
The two acts join end to end: decide whether and what (Act I), sequence the work (linear), then prove the improvement (Act II).
The ledger — remembering why
Every skill above produces a sharp one-shot verdict — and then the verdict evaporates when the chat ends. One skill makes them durable.
| Skill | The operator's question | Its job |
|---|---|---|
| record-decision | "We made the call — what did we bet on, and when will we know we were right?" | Record — write the bet to the repo at commit time, close the loop when reality reports back |
record-decision is the suite's memory. At commit time it writes the decision to a dated file — the call, the fragile assumption it rides on, the expected signal with a by-when, the reversibility read, and a revisit trigger — then keeps the record and the project docs current as findings arrive. It's mostly a receiver: take-a-step-back's fragile assumption becomes the bet, blast-radius's verdict becomes the reversibility line, baseline-spec's metric becomes the expected signal. The records carry machine-readable frontmatter, so "find every Costly decision not yet Validated" is one query, and a date-based revisit trigger can become a /schedule appointment instead of a hope.
It is deliberately not Claude's memory (MEMORY.md / CLAUDE.md): memory is operator-private and about how Claude should work with you; decision records live in git, address the whole team — humans and future agents — and answer why the system is shaped this way. The skill file carries the full comparison.
What they share
- Short, structured output. Every skill leads with the one line that must survive skimming, then adds only the fields that change the call. Drop anything that doesn't; never pad the template.
baseline-specfollows the same one-shot, scannable shape as the four decision skills;linear's output is the structure — one numbered list, nothing actionable outside it;record-decisionwrites the same scannable shape to a file instead of the chat;auto-improveis the lone exception — it executes a loop rather than emitting a verdict, but still leads with an honest headline number. - A shared reversibility read. Where it applies, the skills speak one vocabulary — Easy / Costly / One-way door — so a two-way door is treated differently from a commitment that is expensive to unwind. (Iron-triangle's version asks whether a sacrificed corner stays contained or compounds.)
- Refuse rather than fake it. Accurate signal over constant alarm. The decision skills stay quiet when a change is small and reversible;
baseline-specrefuses to optimize a goal it can't measure;auto-improverejects any "win" that's gamed or lost in the noise. Calibration is as much about declining as raising a flag.
Calibration — what good output looks like
Good output names the one thing that changes the call and ends with a move that reduces uncertainty. Example, from take-a-step-back:
Decision: You're about to execute the 3-PR plan doc as written — cherry-picking and sequencing the PRs onto the drifted source branch.
Step-back check:
- Most fragile assumption: That the plan doc is still the right path now that the branch has drifted — it was written against a tree that no longer exists.
- Alternative frame: This may not be a "merge the existing PRs" problem at all, but a "re-land the ideas as fresh work against current main" problem.
- Reversibility: Costly — once the PRs are cherry-picked and merged in sequence, untangling them from main is real work.
Do next: Diff each PR's intent against current main and decide per PR — cherry-pick as-is, or re-cut as new work. The plan doc is an input, not a destiny.
What makes it good:
- One sharp counterpoint, not five. It names the single fragile assumption instead of listing every possible risk.
- It challenges the frame, not just the option — the real question is "follow the plan, or re-cut?", not "how do I cherry-pick cleanly?".
- Concrete, honest reversibility — a specific cost, on the shared scale.
- A do-next that reduces uncertainty rather than describing it.
The inverse matters just as much: a good skill also knows when not to escalate. See blast-radius's small-change example, where the right answer is "ship it, low risk" — calibration is as much about staying quiet as raising a flag.
The compression skills earn their keep on the delta — what goes in versus what comes out. From linear:
In: "To get this working you'll first want to install the CLI, which you can do with npm. Then there's some configuration to think about — the config file lives at ~/.toolrc and needs your API key. Oh, and note that on Linux you may need sudo for the install. Once configured, run
tool syncto pull data. If sync fails with a 401, your key is wrong. Finally you can runtool build, though if you're on the beta channel you'd usetool build --betainstead."Out:
- Install the CLI:
npm install -g tool
- If on Linux: prefix with
sudoif you get a permissions error.- Add your API key to
~/.toolrc.- Run
tool syncto pull data. → expect "Sync complete"
- If 401 error: API key is wrong — fix step 2 before continuing.
- Build:
- Stable channel:
tool build- Beta channel:
tool build --beta
Every detail survived — the sudo caveat, the 401 diagnosis, the beta variant — but now it executes top-to-bottom without re-reading.
Install
These are Agent Skills built on the open SKILL.md standard, so the same files install across every Claude surface.
Claude.ai (web) and Claude Desktop
The web app and desktop app share one flow: enable code execution, then upload each skill as its own ZIP.
- Enable execution. Open Settings > Capabilities and turn on Code execution and file creation. (Available on Free, Pro, Max, Team, and Enterprise plans. On Team/Enterprise, an owner must first enable it under Organization settings > Skills.)
- Zip each skill folder — one ZIP per skill, each with a
SKILL.mdat its root. Run from the repo root:for s in take-a-step-back iron-triangle blast-radius bottom-line linear baseline-spec auto-improve record-decision; do (cd "$s" && zip -rX "../$s.zip" . -x '.*') done - Upload. In Claude, go to Customize > Skills, click + > + Create skill > Upload a skill, and select one ZIP. Repeat for each skill.
- Turn it on under Customize > Skills.
Uploaded custom skills are private to your account. Install only from sources you trust, and review each SKILL.md before enabling.
Claude Code
Put each skill directory where Claude Code looks for skills — personal (all projects): ~/.claude/skills/, or project (shared with a repo): <project>/.claude/skills/. Symlink them so a git pull keeps them current (run from the repo root):
mkdir -p "$HOME/.claude/skills"
for s in blast-radius bottom-line linear iron-triangle take-a-step-back baseline-spec auto-improve record-decision; do
ln -s "$PWD/$s" "$HOME/.claude/skills/$s"
done
Claude auto-invokes a skill when the request matches its description, or you can call it by name. The entry file must be named exactly SKILL.md (uppercase) — the loader matches it case-sensitively even on case-insensitive macOS, so a lowercase skill.md is silently never discovered.
Authoring conventions
Lessons baked into these files. Keep them if you add more skills:
- Valid frontmatter on line 1. The file must open with
---and a YAMLname+description, with no prose preamble and no```yamlcode fence wrapping it — otherwise the skill silently fails to load and never appears. - Entry file must be
SKILL.md, exact case. The loader matches it case-sensitively even on case-insensitive macOS, so a lowercaseskill.mdis silently skipped — and watch for git hiding a case-only rename whencore.ignorecaseis true. - ASCII punctuation. Straight quotes and regular hyphens. Curly quotes and non-breaking hyphens (
‑) look identical but break grep, copy, and matching. Em-dashes are fine. - Triggers live in the
description. That is the surface Claude matches against — keep it concrete and observable ("about to recommend a migration"), never circular ("fire when the change is major", which the skill can only know after running). - Examples calibrate behavior. Include at least one counter-example where the skill correctly does not escalate — a small change, a cheap reversible call — or it will skew toward alarm.
- Brevity is the product. Each skill's output should be just enough meat that a human operator will actually read it.
Layout
.
├── take-a-step-back/SKILL.md # Act I — decision hygiene
├── iron-triangle/SKILL.md
├── blast-radius/SKILL.md
├── bottom-line/SKILL.md
├── linear/SKILL.md # The bridge — decide → do
├── baseline-spec/SKILL.md # Act II — measure, then optimize
├── auto-improve/
│ ├── SKILL.md
│ ├── README.md
│ └── FAQS.md
├── record-decision/SKILL.md # The ledger — record → revisit
├── snapshot/SKILL.md # Session recovery
├── utils/ # Standalone tooling — not part of the suite
│ ├── README.md
│ └── read-only/SKILL.md # Pre-approve read-only permissions
└── README.md
Maintainer & reviewers
- Maintainer: Noel Saw
- Built with: Claude Code (Effort Max)
- Cross-reviewed by: Gemini Pro 3.1, ChatGPT 5.5, and DeepSeek DeepThink
Sponsored by
This project is supported by two Southern California meetup communities and HiQS.ai.
License
GPL v2 — see LICENSE for details. Provided "as is", without warranty of any kind.