HanzheLee-skills

Skills For Real Engineers

My agent skills that I use every day to do real engineering - not vibe coding.

Developing real applications is hard. Approaches like GSD, BMAD, and Spec-Kit try to help by owning the process. But while doing so, they take away your control and make bugs in the process hard to resolve.

These skills are designed to be small, easy to adapt, and composable. They work with any model. They're based on decades of engineering experience. Hack around with them. Make them your own. Enjoy.

This is a fork of mattpocock/skills that adds an artifact-driven understanding layer for data-shaped work (pipelines, parsers, indexers). See What this fork adds below.

Quickstart (30-second setup)

1. Run the skills.sh installer:

npx skills@latest add HanzheLee/skills

2. Pick the skills you want, and which coding agents you want to install them on. Make sure you select /setup-skills.

3. Run /setup-skills in your agent. It will:

   • Ask you which issue tracker you want to use (GitHub, Linear, or local files)
   • Ask you what labels you apply to tickets when you triage them (/triage uses labels)
   • Ask you where you want to save any docs we create

4. Bam - you're ready to go.

What this fork adds

The original repo optimizes for architecture — its four pillars (grilling for alignment, a shared CONTEXT.md language, red-green-refactor loops, deep-module design) assume the unit of understanding is code structure. This fork adds a complementary layer for data-shaped work, where the failure mode is different: the agent doesn't understand the contract of an artifact (a parsed file, an indexed dataset, a transformed table). When the contract is wrong, code quality is moot — you get a clean implementation of the wrong shape.

Modifications

• New skill: /artifact-driven-tdd — test-first development where the first goal is human understanding of an artifact's input/output contract. For pipelines, parsers, indexers, and schema-shaped systems.
• /grilling — Decision Card mode — for artifact/contract-shaped decisions, each question becomes a card: the affected artifact, options A/B/C with concrete output differences, a ≤5-line sample, the recommended default, and the test that would catch a wrong choice. You answer only A / B / C / defer.
• /domain-modeling — artifact contracts — capture an artifact's contract in CONTEXT.md (input sources/formats, output schema, red lines/invariants, primary keys and relationships, eligibility/quarantine rules), alongside but separate from the terminology glossary.
• /grill-with-docs — closed-loop mode — validate one artifact/step's contract at a time before moving on; use Decision Cards for ambiguous choices; defer whole-architecture questions to a later pass.
• Three-Piece Delivery (in artifact-driven-tdd) — every data-artifact stage ships tests + an explanatory notebook + an audit summary.
• Renames (fork housekeeping) — setup-matt-pocock-skills → setup-skills; ask-matt → ask-router. Install target: HanzheLee/skills.

Design philosophy: artifact-driven understanding

Three ideas, layered on top of the original:

1. Understanding before code. The first deliverable is a human-readable statement of the artifact's contract — tiny fixtures, readable tables, short JSON. The formal parser/indexer is written from that contract, not before it. (The original's "small deliberate steps" applied to data: one small fixture → one understood row → repeat.)
2. Decisions grounded in artifacts, not abstractions. Decision Cards replace open-ended architectural grilling for contract-shaped choices. Every question is pinned to a concrete artifact, shows the concrete output difference per option, and names the test that would catch a wrong choice. Abstract questions ("should this be a class?") are forbidden; every question produces a sample you can eyeball.
3. The audit is the control surface. A stage too complex to hold in your head gets a three-piece delivery — tests, an explanatory notebook, and an audit summary — so a human can govern it without reading the implementation.

This composes with, not replaces, the original skills: grilling gains Decision Cards, domain-modeling gains artifact contracts, grill-with-docs gains closed-loop mode, and tdd gains a sibling (artifact-driven-tdd) for contract-shaped work.

中文摘要

本仓库是 mattpocock/skills 的 fork，在原有「架构对齐 + 共享语言 + TDD 反馈环 + 深模块设计」之上，新增一层面向数据型工作（管道、解析器、索引器、schema）的设计哲学——以产物为中心的理解（artifact-driven understanding）。