@gonzih/skills-engineering 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gonzih
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# @gonzih/skills-engineering
+
+Claude Code skill suite for software engineers, tech leads, and engineering managers.
+
+## Skills
+
+| Skill | Invoke | What it does |
+|-------|--------|--------------|
+| `architecture-doc` | `/architecture-doc` | Generate an ADR or system design doc |
+| `code-review-brief` | `/code-review-brief` | Write a structured code review summary |
+| `incident-postmortem` | `/incident-postmortem` | Write a blameless postmortem |
+| `tech-spec` | `/tech-spec` | Write a technical specification |
+
+## Install
+
+```bash
+npx @gonzih/skills-engineering
+```
+
+Then restart Claude Code.
+
+## Usage
+
+### `/architecture-doc`
+```
+/architecture-doc We need to decide between a monorepo and polyrepo for our new platform.
+```
+Produces an ADR with context, options considered, decision, and consequences.
+
+### `/code-review-brief`
+```
+/code-review-brief [paste PR description or diff]
+```
+Produces a review summary with key changes, risk areas, and a testing checklist.
+
+### `/incident-postmortem`
+```
+/incident-postmortem Database went down at 14:32 UTC, came back at 15:19 UTC. Root cause was a bad deploy.
+```
+Produces a blameless postmortem with timeline, root cause, contributing factors, and action items.
+
+### `/tech-spec`
+```
+/tech-spec Rate limiting on our public API — need per-user and per-IP limits.
+```
+Produces a spec with goals, non-goals, proposed solution, API design, rollout plan, and open questions.
+
+## License
+
+MIT

package/install.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { copyFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const skillsDir = join(homedir(), '.claude', 'skills');
+const skills = ['architecture-doc', 'code-review-brief', 'incident-postmortem', 'tech-spec'];
+
+for (const skill of skills) {
+  const dest = join(skillsDir, skill);
+  if (!existsSync(dest)) mkdirSync(dest, { recursive: true });
+  copyFileSync(new URL(`./skills/${skill}/SKILL.md`, import.meta.url).pathname, join(dest, 'SKILL.md'));
+  console.log(`✓ Installed /${skill}`);
+}
+console.log('\nSkills installed! Restart Claude Code to use them.');

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@gonzih/skills-engineering",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Claude Code skill suite for software engineers, tech leads, and engineering managers",
+  "main": "install.js",
+  "bin": {
+    "skills-engineering": "./install.js"
+  },
+  "scripts": {
+    "postinstall": "node install.js"
+  },
+  "files": [
+    "skills/",
+    "install.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "skills",
+    "engineering",
+    "architecture",
+    "postmortem",
+    "tech-spec",
+    "code-review"
+  ],
+  "author": "gonzih",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skills/architecture-doc/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: architecture-doc
+description: Generate an architecture decision record (ADR) or system design doc covering context, options considered, decision, and consequences.
+triggers: ["architecture doc", "write an ADR", "architecture decision record", "system design doc", "document this decision"]
+---
+
+# Architecture Doc
+
+## What this skill does
+Produces a structured Architecture Decision Record (ADR) or system design document from a brief description of the problem space. It captures the context driving the decision, the options that were evaluated, the chosen approach, and the consequences — both positive and negative — of that choice.
+
+## How to invoke
+/architecture-doc [decision or system to document]
+
+## Workflow steps
+
+### Step 1 — Gather context
+Ask clarifying questions if the trigger message is sparse: What problem are we solving? What constraints apply (team size, latency, cost, existing stack)? What is the scope — single service, cross-cutting concern, or full system?
+
+### Step 2 — Draft the document
+Produce a document with the following sections:
+- **Title** — short imperative phrase (e.g. "Use Kafka for async event delivery")
+- **Status** — Proposed / Accepted / Deprecated / Superseded
+- **Context** — background, forces at play, and why a decision is needed now
+- **Options considered** — at least two alternatives, each with pros and cons
+- **Decision** — the chosen option and the primary rationale
+- **Consequences** — what becomes easier, what becomes harder, open risks
+
+### Step 3 — Review and refine
+Present the draft and offer to adjust: swap in a different decision, add an option, expand the consequences, or reformat as a Markdown file ready to commit to a `docs/adr/` directory.
+
+## Example outputs
+A Markdown document titled "ADR-0012: Adopt event sourcing for the orders domain" with a two-paragraph context section, a comparison table of three options, a clear decision statement, and a bullet list of consequences including a note on operational complexity.

package/skills/code-review-brief/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: code-review-brief
+description: Write a code review summary covering what changed, why, risk areas to scrutinize, and a testing checklist.
+triggers: ["code review brief", "review summary", "write a review brief", "summarize this PR", "review checklist"]
+---
+
+# Code Review Brief
+
+## What this skill does
+Produces a structured code review brief from a pull request description, diff, or verbal summary of changes. It surfaces what changed and why, calls out the riskiest areas for reviewers to focus on, and generates a concrete testing checklist so nothing falls through the cracks.
+
+## How to invoke
+/code-review-brief [PR description, diff, or summary of changes]
+
+## Workflow steps
+
+### Step 1 — Understand the change
+Parse the provided input. If given a diff or file list, identify the affected layers (data model, API, business logic, UI, infra). If the input is a natural-language summary, ask for the PR title and key files changed if they are not present.
+
+### Step 2 — Draft the brief
+Produce a document with the following sections:
+- **Summary** — one paragraph: what changed, why it was needed, and the intended outcome
+- **Key changes** — bullet list of the most significant modifications grouped by layer or concern
+- **Risk areas** — ranked list of spots that deserve the closest review attention, with a one-line reason for each (e.g. "Auth middleware — privilege escalation if condition is inverted")
+- **Testing checklist** — concrete, checkable items covering happy path, edge cases, regressions, and rollback/feature-flag behaviour where applicable
+
+### Step 3 — Tailor and hand off
+Offer to expand any section, add a migration or deploy note, or reformat the brief as a GitHub PR comment ready to paste.
+
+## Example outputs
+A brief for a database schema migration PR with a two-sentence summary, five bullet points of key changes, three risk areas flagged (index drop, backfill script, ORM model sync), and a nine-item testing checklist including a rollback verification step.

package/skills/incident-postmortem/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: incident-postmortem
+description: Write a blameless postmortem covering timeline, root cause, contributing factors, and action items with owners.
+triggers: ["incident postmortem", "write a postmortem", "blameless postmortem", "post-incident review", "incident report"]
+---
+
+# Incident Postmortem
+
+## What this skill does
+Produces a blameless postmortem document from an incident summary, chat logs, or verbal description of what happened. It reconstructs the event timeline, identifies the root cause and contributing factors using systems-thinking rather than finger-pointing, and surfaces concrete action items with suggested owners to prevent recurrence.
+
+## How to invoke
+/incident-postmortem [incident summary, timeline notes, or description of what happened]
+
+## Workflow steps
+
+### Step 1 — Collect incident data
+Extract or ask for: incident start and end times, severity/impact (users affected, revenue, SLA breach), services involved, who responded, and a rough sequence of events. If chat logs or monitoring screenshots are available, use them to anchor the timeline.
+
+### Step 2 — Draft the postmortem
+Produce a document with the following sections:
+- **Incident summary** — one paragraph: what broke, duration, customer impact, and severity level
+- **Timeline** — chronological table of events (UTC timestamps, event description, actor)
+- **Root cause** — the deepest systemic cause, stated without blaming individuals
+- **Contributing factors** — other conditions that made the incident worse or harder to detect (e.g. lack of alerting, deployment process gap, unclear runbook)
+- **What went well** — things the team did right during the response
+- **Action items** — table with columns: Action | Owner | Priority | Due date. Minimum: one item addressing root cause, one improving detection, one improving response.
+
+### Step 3 — Review and finalize
+Offer to sharpen the root cause statement, add a "lessons learned" narrative section, adjust tone for executive vs. engineering audiences, or export as a Confluence-ready format.
+
+## Example outputs
+A postmortem for a 47-minute database failover incident with a six-row timeline, a root cause of "manual failover runbook not tested after infrastructure upgrade," three contributing factors, two "went well" items, and a five-row action items table with owners and due dates.

package/skills/tech-spec/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: tech-spec
+description: Write a technical specification covering goals, non-goals, proposed solution, API design, rollout plan, and open questions.
+triggers: ["tech spec", "write a spec", "technical specification", "design doc", "RFC", "write an RFC"]
+---
+
+# Tech Spec
+
+## What this skill does
+Produces a technical specification from a feature idea, bug mitigation plan, or system change description. It defines what is and is not in scope, proposes a concrete solution with enough detail to start implementation, sketches the API or data model, and surfaces open questions that need resolution before work begins.
+
+## How to invoke
+/tech-spec [feature, change, or problem to specify]
+
+## Workflow steps
+
+### Step 1 — Clarify scope
+Ask if needed: What is the motivation or user need? Who are the stakeholders? Are there hard constraints (latency, cost, backward compatibility, regulatory)? What is the target ship date or milestone?
+
+### Step 2 — Draft the specification
+Produce a document with the following sections:
+- **Overview** — one paragraph describing what is being built and why
+- **Goals** — bullet list of outcomes the spec must achieve
+- **Non-goals** — explicit list of things this spec intentionally does not address
+- **Proposed solution** — narrative description of the approach, key components, and how they interact; include a simple ASCII or Mermaid diagram if helpful
+- **API / interface design** — endpoints, function signatures, data schemas, or CLI flags as appropriate; use code blocks
+- **Rollout plan** — phases, feature flags, migration steps, and rollback strategy
+- **Alternatives considered** — brief note on other approaches that were rejected and why
+- **Open questions** — numbered list of unresolved decisions with a suggested owner for each
+
+### Step 3 — Iterate
+Offer to expand any section, add a security or privacy consideration section, generate a skeleton implementation, or produce a trimmed one-pager version for stakeholder alignment.
+
+## Example outputs
+A spec for a rate-limiting feature with a two-paragraph overview, five goals, three non-goals, a solution section describing a token-bucket algorithm backed by Redis, a `POST /api/rate-limit/config` endpoint schema, a three-phase rollout with a feature flag, and four open questions around burst limits, observability, and multi-region behaviour.