Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
55 lines (37 loc) · 2.78 KB

CONTRIBUTING.md

File metadata and controls

55 lines (37 loc) · 2.78 KB
Raw

Contributing to staff-engineering-skills

Thanks for helping AI coding agents reason more like a staff engineer. This repo is a collection of skills — each one teaches an agent to recognize and avoid a specific class of production failure. Contributions fall into two buckets: improving an existing skill or adding a new trap.

Please keep one skill (or one fix) per pull request.

What a skill is

Each skill is a single skills/staff-engineering-skills-<slug>/SKILL.md file with YAML frontmatter:

---
name: staff-engineering-skills-<slug>
description: <what it does>. Use when <situations>. Activates on patterns like <concrete code signals>.
---

The description is the most important line: the agent runtime reads it to decide when to activate the skill — there is no manual invocation. Encode concrete, pattern-matchable triggers ("Promise.all on a dynamic-sized array", "cache.set without cache.delete on the write path"), not vague themes. Keep it under 1024 characters.

The body follows a consistent shape:

  • A one-line framing hook — the trap in a sentence.
  • Detection — "if you see X, stop and think." This is the core value; be specific.
  • Patterns — the correct approach, with real, runnable code. One canonical example per distinct lesson.
  • Anti-Patterns — what not to do, and why.
  • Related Traps — how this skill interacts with others (by name).

Skills are loaded into a live agent's context window, so they pay a context-budget cost every time they activate. Keep them tight. Cut redundancy, prefer one strong example over three similar ones, and compress reference material into tables.

Adding a new trap

  1. Pick a short slug (e.g. connection-pool-exhaustion).
  2. Create skills/staff-engineering-skills-<slug>/SKILL.md following the structure above.
  3. Add a row to the Traps table in README.md with a memorable one-liner.
  4. Cross-link it from the Related Traps section of any skill it interacts with.

Good candidates are listed under "Suggested Additions" in the README.

Conventions

  • The skill's name: frontmatter must match its directory name exactly.
  • Code examples must be correct — no pseudo-code that wouldn't run.
  • Match the existing voice: direct, concrete, tradeoff-aware. No hand-waving about "scalability."

Self-check before opening a PR

  • name: matches the directory name.
  • description encodes concrete activation triggers and is under 1024 characters.
  • Sections present: a framing hook, Detection, Patterns, Anti-Patterns, Related Traps.
  • Code fences are balanced and examples are correct.
  • If it's a new trap: README table row added and cross-links wired up.

Code of Conduct

By participating, you agree to uphold our Code of Conduct.