Trellis Session Insight
mindfold-ai/Trellis
Reach into past AI conversation history through the trellis mem CLI.
A skill your agent uses when asked for first-principles or Occam's-razor review, or when high-risk decisions involve competing constraints, fallback growth, duplicate owners, or architecture…
$ npx skills add GanyuanRan/Aegis --skill first-principles-review -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install GanyuanRan/Aegis first-principles-review --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/GanyuanRan/Aegis.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/first-principles-review .claude/skills/first-principles-review && rm -rf skills-srcUse ~/.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/
Install the "first-principles-review" agent skill from https://github.com/GanyuanRan/Aegis/tree/main/skills/first-principles-review into .claude/skills/first-principles-review/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "first-principles-review", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/GanyuanRan/Aegis/tree/main/skills/first-principles-reviewType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add GanyuanRan/Aegis --skill first-principles-review -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install GanyuanRan/Aegis first-principles-review --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/GanyuanRan/Aegis.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/first-principles-review .agents/skills/first-principles-review && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "first-principles-review" agent skill from https://github.com/GanyuanRan/Aegis/tree/main/skills/first-principles-review into .agents/skills/first-principles-review/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "first-principles-review", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add GanyuanRan/Aegis --skill first-principles-review -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install GanyuanRan/Aegis first-principles-review --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/GanyuanRan/Aegis.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/first-principles-review .cursor/skills/first-principles-review && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "first-principles-review" agent skill from https://github.com/GanyuanRan/Aegis/tree/main/skills/first-principles-review into .cursor/skills/first-principles-review/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "first-principles-review", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/GanyuanRan/Aegis.git --path skills/first-principles-review--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add GanyuanRan/Aegis --skill first-principles-review -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install GanyuanRan/Aegis first-principles-review --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/GanyuanRan/Aegis.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/first-principles-review .gemini/skills/first-principles-review && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "first-principles-review" agent skill from https://github.com/GanyuanRan/Aegis/tree/main/skills/first-principles-review into .gemini/skills/first-principles-review/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "first-principles-review", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install GanyuanRan/Aegis first-principles-reviewInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add GanyuanRan/Aegis --skill first-principles-review -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/GanyuanRan/Aegis.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/first-principles-review .github/skills/first-principles-review && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "first-principles-review" agent skill from https://github.com/GanyuanRan/Aegis/tree/main/skills/first-principles-review into .github/skills/first-principles-review/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "first-principles-review", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add GanyuanRan/Aegis --skill first-principles-review -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install GanyuanRan/Aegis first-principles-review --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/GanyuanRan/Aegis.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/first-principles-review .opencode/skills/first-principles-review && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "first-principles-review" agent skill from https://github.com/GanyuanRan/Aegis/tree/main/skills/first-principles-review into .opencode/skills/first-principles-review/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "first-principles-review", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
first-principles-reviewA skill your agent uses when asked for first-principles or Occam's-razor review, or when high-risk decisions involve competing constraints, fallback growth, duplicate owners, or architecture…
First Principles Review is an agent skill from GanyuanRan/Aegis. Use when asked for first-principles or Occam's-razor review, or when high-risk decisions involve competing constraints, fallback growth, duplicate owners, or architecture direction risk. Ordinary bug fixes stay on the fast path.
Its SKILL.md is about 2.5k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.
It sits in Development, covering Debugging. The repository describes itself as: Make AI coding agents architecture-aware: baseline-first, evidence-verified, drift-checked, and safe across long tasks. The licence is MIT.
Read from SKILL.md and the folder at commit 61867e9. It shows what the files ask for, not the result of running them.
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.
No scripts in the folder and no shell commands in SKILL.md.
From the folder's file list and the shell code blocks in SKILL.md.
No URLs in SKILL.md.
From URLs in SKILL.md, links to its own repository left out.
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
First Principles Review loads about 2.5k tokens when it runs. Until then it costs about 63 tokens; SKILL.md has 803 words of instructions outside code blocks.
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.
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); files beside SKILL.md are not scanned.
The full file from GanyuanRan/Aegis at commit 61867e9, republished under its MIT licence (© GanyuanRan). 803 words, ~2,485 tokens.
.claude/skills/first-principles-review/SKILL.md (or your agent's skills folder).Use this as a lightweight decision review before another Aegis workflow makes a directional choice. It is a compositional skill, not a standalone workflow.
Do not replace brainstorming, systematic-debugging, writing-plans,
requesting-code-review, or verification-before-completion. Use it to clean
the decision surface those skills will act on.
When this review materially changes the direction, surface Aegis Visibility
in natural prose: name the first principle, dropped assumption, smallest
sufficient path, or owner / retirement falsifier that changed the decision.
Keep it advisory and task-specific; do not turn the lens into approval
authority or a generic skill trace.
Answer only what is needed, usually in five short lines:
First Principle: What irreducible outcome must this satisfy?
Non-negotiables: What constraints cannot be broken?
Assumptions to Drop: What is habit, inherited shape, or unproven preference?
Smallest Sufficient Path: What is the least complex path that satisfies the first principle?
Escalation Signal: What finding would require spec/design/architecture review?When the direction depends on a new mechanism or an unfamiliar domain, insert one optional line between path and escalation:
Known Prior Art: proven external pattern worth adopting or adapting to project
constraints (cite source), or `unknown` when precedent cannot be verified hereFor repair choices, "smallest" means smallest sufficient stable repair, not the smallest textual diff:
Minimality Check:
- Smallest textual diff:
- Correct owner:
- Bug class fixed:
- New branch/fallback added:
- Old path retired or scheduled:
- Verdict: sufficient repair | local patch | needs first-principles reviewUse this escalation only when a design, fix, or plan needs endorsement before it is written into a spec or implementation plan.
Escalate from the five-line review when any of these risk signals appear:
Use this compact shape:
First-principles invariants:
- Non-negotiable goal:
- Non-negotiable constraints:
- Historical assumptions to delete:
Bounded preservation reminder:
- Evidence-backed behavior that must remain correct:
- Highest-risk counterexample:
- Material unknown / uninspected surface:
- Known explicit anchors / upstream-downstream refs and disposition:
- Role-before-value ambiguity, if any:
Owner / retirement matrix:
- New canonical owner:
- Old owner:
- Compat-only carrier:
- Delete-first / retirement trigger:
Falsification matrix (evaluate in order; stop at the first failing gate):
- Gate 0 - Premise evidence (stage-graded): design stage accepts spec/logic
refs; implementation/runtime stage requires log, telemetry, or test
evidence. No evidence -> park as watch-listed, do not enter value
evaluation.
- Gate 1 - Decidability: no obtainable evidence to judge it -> park as a
watched falsifier, do not act.
- Gate 2 - Value (any one): lowers future fix probability / shrinks the
solution set / exposes a missing actionable acceptance criterion / the same
broken assumption is reused elsewhere. Passing here still requires
gates 3-5.
- Gate 3 - Cost match: change cost vs business priority, costed at the
current stage; a valid but deferred counterexample is recorded in the owner
doc, never parked orally.
- Gate 4 - Goal regression: the constrained solution still meets the original
goal; re-read the accepted-constraint list at existing checkpoints (design
review, plan approval, pre-completion verification).
- Gate 5 - Minimize then classify: boundary-shaped destructive claims must be
minimized first; premise attacks classify as destructive directly.
Classes: destructive (refactor/retirement track) | supplementary (boundary
constraint) | watch-listed (falsifier). Conflicting counterexamples are
decided by business-goal ranking, never by stacking constraints.
- Gate 6 - Adoption trace: the cheapest checkable form (regression test for
destructive; contract, assertion, or checklist line for supplementary),
written into the existing owner doc.
Verdict:
- Adopt / revise / reject / needs evidence:
- Blocking gaps:
- Next evidence:Use this narrower lens when a proposal is executable but may still encode the
wrong owner, abstraction, contract boundary, or retirement path. It is advisory
method-pack output and may be embedded inside Decision Hygiene Review when
that is enough.
Trigger it when any of these appear before approach selection, task decomposition, review, or completion-risk reporting:
Use this compact shape:
Architecture Integrity Lens:
- Invariant: What must remain true for the system to be coherent?
- Canonical owner / contract: Which owner, contract, or source-of-truth should carry the behavior?
- Responsibility overlap: What duplicate owner, caller-side patch, fallback, or stale path might still carry real logic?
- Higher-level simplification: Can the problem be solved at the owner / contract / source-of-truth layer instead of by another local branch?
- Retirement / falsifier: What old path retires, or what evidence would disprove this architecture judgment?
- Responsibility / capability boundary: Which invalid authority retires, and
does the same carrier still serve a separately evidenced legitimate role?
- Verdict: proceed | revise design | split owner | return to baseline | needs ADR/baseline syncBounded preservation reminder is a risk-triggered reasoning aid, not a
universal artifact or an exhaustive behavior inventory. Inspect the smallest
relevant contract, consumer, test, or history evidence. Preserve, rebind,
retire, or reject each known explicit reference; state unresolved relationships
as unknown instead of re-inferring them or claiming semantic completeness. The
Method Pack does not build an authoritative relationship graph, prove
referential integrity or input lineage, calculate complete behavior coverage,
or issue a runtime gate.
Do not run this lens for every low-risk task. If it does not change the decision surface, return to the active workflow immediately.
brainstorming: run before approach selection when the request is broad,
ambiguous, likely to inherit a poor product shape, or involves owner /
retirement / fallback / adapter risk. Use Decision Hygiene Review or the
narrower Architecture Integrity Lens before recommending or selecting an
approach when those signals appear.systematic-debugging: run after evidence shows repeated fixes, fallback
growth, duplicate owners, or consumer-side patching.writing-plans: run before task decomposition when the plan could encode
the wrong owner, abstraction, compatibility boundary, fallback, adapter, or
retirement schedule. If the approved spec did not already cover this, use
Decision Hygiene Review or the Architecture Integrity Lens before writing
tasks.requesting-code-review: run when review should check direction and
owner integrity, not just code quality.verification-before-completion: use only to name residual directional
risk. It does not grant completion authority.GateDecision, PolicySnapshot, or completion
authority.© GanyuanRan, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Just SKILL.md in skills/first-principles-review of GanyuanRan/Aegis.
Open the folder on GitHubat commit 61867e9
We found 1 copy of this SKILL.md (exact, near-identical or edited) in other folders, from 1 other GitHub owner. This page covers the copy in GanyuanRan/Aegis, which our catalogue first saw on October 7, 2026.
First Principles Review 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.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| First Principles Review this skillGanyuanRan/Aegis | 1.3k | 1 repos | ~2.5k | Automated safety check: Pass | MIT | |
| Trellis Session Insightmindfold-ai/Trellis | 15k | 4 repos | ~1.7k | Automated safety check: Pass | AGPL-3.0 | |
| Native Data FetchingCherryHQ/cherry-studio-app | 4k | 6 repos | ~2.9k | Automated safety check: Notes | MIT | |
| Debugging Executionsn8n-io/n8n | 207k | — | ~2.6k | Automated safety check: Pass | Custom licence | |
| Aoti Debugpytorch/pytorch | 104k | 1 repos | ~1.7k | Automated safety check: Pass | Custom licence | |
| Herdr Throwaway Reproductionherdrdev/herdr | 43k | — | ~2.4k | Automated safety check: Pass | Apache-2.0 |
mindfold-ai/Trellis
Reach into past AI conversation history through the trellis mem CLI.
CherryHQ/cherry-studio-app
A skill your agent uses when implementing or debugging ANY network request, API call, or data fetching.
n8n-io/n8n
Debug failed or wrong-output workflow executions using executions tools.
pytorch/pytorch
Debug AOTInductor (AOTI) errors and crashes. An agent skill from pytorch/pytorch.
herdrdev/herdr
Runs a disposable, uniquely named Herdr session inside an existing one so runtime, pane, terminal or API bugs can be reproduced without touching the main session.
ultralisp/ultralisp
A skill your agent uses when encountering any bug, test failure, or unexpected behavior, before proposing fixes
GanyuanRan/Aegis
A skill your agent uses when touching retiring old logic, collapsing duplicate owners, removing fallbacks, or schema/persistence/source-of-truth boundaries; identify opportunities automatically…
GanyuanRan/Aegis
A skill your agent uses when executing a written implementation plan across sessions or with review checkpoints.
GanyuanRan/Aegis
A skill your agent uses when the user explicitly sets an Aegis goal with /aegis-goal, Aegis goal:, or asks to define goal, success evidence, stop condition, or task boundaries before work.
GanyuanRan/Aegis
A skill your agent uses when the user asks to establish shared project language, or project work exposes a conflicting, renamed, or deprecated domain term that needs active semantic modeling.
GanyuanRan/Aegis
A skill your agent uses when the user asks to create, write, update, amend, supersede, or evaluate an ADR, architecture decision record, durable architecture decision, decision log, or baseline sync…
GanyuanRan/Aegis
A skill your agent uses when requesting independent code review, after implementation slices, before merging high-risk work, or when verification exposes evidence, baseline, architecture…
Categories
A skill your agent uses when asked for first-principles or Occam's-razor review, or when high-risk decisions involve competing constraints, fallback growth, duplicate owners, or architecture…. First Principles Review is an agent skill from GanyuanRan/Aegis. Use when asked for first-principles or Occam's-razor review, or when high-risk decisions involve competing constraints, fallback growth, duplicate owners, or architecture direction risk.
First Principles Review fits situations like: asked for first-principles; occams-razor review; high-risk decisions involve competing constraints; fallback growth.
Run `npx skills add GanyuanRan/Aegis --skill first-principles-review -a claude-code`. Or copy the skill folder (skills/first-principles-review in GanyuanRan/Aegis) into .claude/skills/first-principles-review in your project. Claude Code loads it when a task matches its description.
Run `npx skills add GanyuanRan/Aegis --skill first-principles-review -a codex`. Or copy the skill folder (skills/first-principles-review in GanyuanRan/Aegis) into .agents/skills/first-principles-review in your project. Codex loads it when a task matches its description.
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add GanyuanRan/Aegis --skill first-principles-review -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/first-principles-review, .gemini/skills/first-principles-review, .github/skills/first-principles-review and .opencode/skills/first-principles-review in your project.
SKILL.md names no scripts, command-line tools or credentials: First Principles Review is instructions for the agent only.
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.
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. Review the folder before installing.
First Principles Review is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.
About 2.5k tokens (SKILL.md is roughly 9.9k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.
Skills that share tags, products or a category with First Principles Review: Trellis Session Insight (mindfold-ai/Trellis, 15k stars), Native Data Fetching (CherryHQ/cherry-studio-app, 4k stars), Debugging Executions (n8n-io/n8n, 207k stars) and Aoti Debug (pytorch/pytorch, 104k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
GanyuanRan (a GitHub user) maintains it in GanyuanRan/Aegis, which has 1,337 GitHub stars. The repository holds 21 skills in this directory. The repository was last updated on October 10, 2026.
Source: GanyuanRan/Aegis on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.