senior-engineering — Claude Code skill: what it does, how to install
senior-engineering is a Claude Code skill for non-trivial tasks: it defines done first, then keeps the project runnable and checks a gate list before reporting completion.
MIT ★ 239 updated 2026-08-30
npx skills add jdrhyne/agent-skills --skill senior-engineering -a claude-codeWhat senior-engineering does
This skill loads a set of engineering principles into context and changes how the agent handles work that isn't trivial. It writes down the definition of done and how to verify it, sorts choices by how hard they are to reverse, and pins the interface before the internals. Building starts after that.
While code is being written, the principles push for a project that still compiles and runs, with working checkpoints committed along the way. Logging goes in as you build, not during an incident. A gate list sits before the word done: linter, type checker, tests, a manual smoke test, edge cases.
A separate section covers running several agents at once. Each one gets a narrow job and the smallest context that lets it finish, and its output is reviewed the way you would review a pull request. The safety section forbids widening the scope of a request and making up validation results. An agent that reports passing tests it never ran has broken the rule.
What it helps with
- split a large feature into units you can verify one at a time
- write acceptance criteria before any code exists
- sort decisions into ones worth debating and ones to just make
- run the pre-ship gate: linter, types, tests, smoke test
- hand work to several agents with clear input and output contracts
Example prompts for the agent
- Plan the payment module rewrite: definition of done first, then the code.
- Break this into independent pieces and tell me which choices are hard to reverse.
- Show what we actually ran before calling this done, and what is still unverified.
How to install senior-engineering
1Skills CLI (Vercel)
npx skills add jdrhyne/agent-skills --skill senior-engineering -a claude-code2Manually: put the files in place
~/.claude/skills/senior-engineering/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/senior-engineering/
1Skills CLI (Vercel)
npx skills add jdrhyne/agent-skills --skill senior-engineering -a codex2Manually: put the files in place
.agents/skills/senior-engineering/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add jdrhyne/agent-skills --skill senior-engineering -a cursor2Manually: put the files in place
.cursor/skills/senior-engineering/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install jdrhyne/agent-skills prompts/senior-engineering/SKILL.md2Manually: put the files in place
.github/skills/senior-engineering/SKILL.md1Skills CLI (Vercel)
npx skills add jdrhyne/agent-skills --skill senior-engineering -a gemini-cli2Platform CLI
gemini skills install https://github.com/jdrhyne/agent-skills --path prompts/senior-engineeringManually: put the files in place
.devin/skills/senior-engineering/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about senior-engineering
How do I install senior-engineering in Claude Code?
Run npx skills add jdrhyne/agent-skills --skill senior-engineering -a claude-code. The skill file lands at ~/.claude/skills/senior-engineering/SKILL.md.
What does senior-engineering do?
It gives the agent a working method: state what done means, cut the task into verifiable pieces, keep the project runnable, then pass checks before claiming completion.
Does the skill require approval for every change?
No. It blocks skipping your approval on destructive or high-risk changes, while reversible choices are left to the agent.
Source text
SKILL.md · MIT
--- name: senior-engineering description: Engineering principles for building software like a senior engineer. Load when tackling non-trivial development work, architecting systems, reviewing code, or orchestrating multi-agent builds. Covers planning, delivery, quality gates, and LLM-specific patterns. --- # Senior Engineering Principles Guidelines for building software with the judgment and discipline of a senior engineer. ## Safety Boundaries - Do not treat these principles as permission to skip user approval for destructive or high-risk changes. - Do not expand scope beyond the user's request just because a broader rewrite seems cleaner. - Do not invent validation results; report what was actually checked and what remains unverified. ## Before Writing Code ### Define Done First - What does success look like? Write it down. - What are the acceptance criteria? - How will you verify it works? ### Identify Load-Bearing Decisions - Which choices are hard to reverse? → More scrutiny - Which are easily changed? → Decide fast, move on - Reversible decisions don't need consensus ### Decompose Before Building - Break work into clear, testable units - Each unit should be independently verifiable - If you can't explain the pieces, you don't understand the whole ### Surface Risks Upfront - What could go wrong? - What are the dependencies? - What's the rollback plan? - Time-box exploration — analysis paralysis is real ### Interface First, Implementation Second - Define the contract (types, API shape, error cases) before internals - Forces clarity on what you're actually building - Implementation becomes "fill in the blanks" ### Ask: What's the Simplest Thing That Could Work? - Start there. Add complexity only when the simple version fails. - Most features need 20% of what we imagine. ## During Build ### Always Have a Runnable State - Never be more than 30 mins from something that compiles/runs - Commit working checkpoints frequently - Big-bang integration is where projects die ### Prefer Incremental Over Big-Bang - Ship small, verify, iterate - Each step should be independently deployable if possible - Reduce blast radius of mistakes ### Instrument As You Build - Add logging/metrics while coding, not when debugging prod - "I wish I had visibility into X" = you waited too long - Observability is a feature, not an afterthought ### Read Errors Carefully - 80% of debugging is actually reading what the system tells you - Read the error, then read it again - Stack traces have answers — follow them ### Boring > Clever - If someone has to pause to understand it, it's too clever - Save big-brain moves for genuinely hard problems - Maintainability beats elegance ### Optimize for Delete - Write code that's easy to remove - Tight coupling makes features immortal - Good abstractions have clear boundaries ## Quality Gates ### Before Declaring Done - [ ] Linter passes - [ ] Type checker passes - [ ] Tests pass (unit + integration where applicable) - [ ] Manual smoke test completed - [ ] Edge cases considered and handled ### Tests Are Documentation - A good test suite tells you what code is *supposed* to do - Treat tests as first-class citizens - If it's not tested, it's not done ### Code Review Mindset - Review like you'll maintain it at 3am - Check: correctness, clarity, edge cases, security - "It works" is necessary but not sufficient ## LLM Orchestration Principles ### Context Management - Context window is your RAM — manage it deliberately - Bloated context = degraded reasoning - Give each agent minimum viable context, no more ### Agent Delegation - Single responsibility per agent - Clear handoff contracts: inputs, outputs, success criteria - Parallel when independent, sequential when dependent ### Verify, Don't Trust - First output is a draft, always - Review agent output like a code review - Agents are junior engineers, not oracles ### Checkpoints Over Marathons - Long-running agents should checkpoint progress - If it crashes at 90%, don't lose everything - Log state to files, not just memory ### Fail Fast, Surface Early - If something's going wrong, stop and reassess - Don't compound errors hoping they'll resolve - Human in the loop for high-stakes decisions ## Ownership & Accountability ### Own Failures, Credit Others - Own failures publicly - Credit others for wins - No ego-driven attachment to being right ### Strong Opinions, Weakly Held - Have a position, defend it with evidence - Update beliefs when evidence demands it - "I was wrong" is a sign of growth ### Leave It Better - Codebases, teams, processes — improve what you touch - Fix the small things while you're there - Documentation is a gift to future-you ## The Meta-Principle > "Make the change easy, then make the easy change." — Kent Beck Most senior engineering is about *preparation* — setting up the codebase so the actual feature is trivial. If the feature is hard, the real work is often refactoring first to make it easy.
© jdrhyne · MIT · jdrhyne/agent-skills