# principal-engineering

Enforces core engineering discipline for AI agents: mandates pre-change checkpoints, bans silent error suppression, and requires evidence from real code.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 18000 installs · ★ 6
- Author: riekelt
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/riekelt/principal-engineer/tree/HEAD/plugins/principal-engineer/skills/principal-engineering/SKILL.md
- Updated: 2026-09-11
- HTML: https://affpapa.org/en/nevibecode/skills/principal-engineering

## What it does

The skill injects principal engineering discipline before any non-trivial change to code, databases, or infrastructure. Before modifying files, the agent must document a pre-change checkpoint in working notes: current behavior grounded in code, blast radius, invariant guarantees, and the exact verification command. This stops guesswork before coding starts.

It establishes non-negotiable safety rules across all repositories. Silent error suppression is an immediate blocker: every failure must rethrow, log, return a typed error, or enter a documented degraded state. Applied database migrations cannot be edited retroactively, secrets cannot be printed to disk, and destructive actions require inspection first. The project's declared risk tiers dictate the required level of verification rigor.

Project instructions in `CLAUDE.md` and repository code styles explicitly outrank this skill. It acts as an architectural foundation, delegating specialized tasks to sibling skills like `handling-failures`, `verifying-before-done`, or `guarding-architecture`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add riekelt/principal-engineer --skill principal-engineering -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/principal-engineering/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/principal-engineering/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add riekelt/principal-engineer --skill principal-engineering -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/principal-engineering/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add riekelt/principal-engineer --skill principal-engineering -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/principal-engineering/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install riekelt/principal-engineer principal-engineering
```

2. **Manually: put the files in place**
- File: `.github/skills/principal-engineering/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add riekelt/principal-engineer --skill principal-engineering -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/riekelt/principal-engineer --path plugins/principal-engineer/skills/principal-engineering
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/principal-engineering/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add riekelt/principal-engineer --skill principal-engineering -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/riekelt/principal-engineer/tree/HEAD/plugins/principal-engineer/skills/principal-engineering/SKILL.md

## When to use it
- Stop silent exception swallowing in error-handling paths
- Establish invariants and blast radius before touching unfamiliar code
- Prevent destructive edits to already applied database migrations
- Enforce proof of verification through actual test command output

## Example prompts
- Prepare the pre-change checkpoint and assess the blast radius before refactoring the auth service.
- Investigate the payment failure using code evidence rather than assumptions.
- Review this error handling logic to ensure no failures are silently swallowed.

## Similar
- [Principal software engineer](https://affpapa.org/en/nevibecode/agents/principal-software-engineer.md) — subagent · ★ 40418
- [improve-code-quality](https://affpapa.org/en/nevibecode/skills/improve-code-quality.md) — skill · 2300 installs
- [vanity-engineering-review](https://affpapa.org/en/nevibecode/skills/vanity-engineering-review.md) — skill · 3200 installs
- [architecture-optimization](https://affpapa.org/en/nevibecode/skills/architecture-optimization.md) — skill · 1300 installs
- [improve](https://affpapa.org/en/nevibecode/skills/owainlewis-improve.md) — skill · 332 installs
- [refactor-code](https://affpapa.org/en/nevibecode/commands/refactor-code.md) — command · 4890 installs

From the same set: [riekelt/principal-engineer](https://affpapa.org/en/nevibecode/by/riekelt/principal-engineer.md) — 4 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md