AI Engineering Workflow Skills

Canonical source for engineering workflow, product, and productivity skills.

In plain terms: you tell your agent what stage of a software change you're in — scoping it, defining done, breaking it into issues, reviewing before merge, releasing, or handing off context — and it routes to the matching engineering-workflow skill instead of improvising its own process each time.

How the pack fits together

flowchart TD
    REQ([" Work request "]) --> ROUTER
    ROUTER["workflow-router<br/>route to the smallest applicable workflow"]

    subgraph CTX["Loaded before any skill runs"]
        direction LR
        CORE["system-level/core.md<br/>invariant operating rules"]
        MAP["AGENTS.md / CLAUDE.md<br/>trigger map"]
        FLOW["AI_ENGINEERING_WORKFLOW.md<br/>stages, risk levels, gates"]
    end
    CTX -.- ROUTER

    subgraph S0["0 - Pressure-test the idea"]
        direction LR
        s_roast["roast"]
    end

    subgraph S1["1 - Clarify"]
        direction LR
        s_clarify_work["clarify-work"]
        s_to_prd["to-prd"]
    end

    subgraph S2["2 - Decompose"]
        direction LR
        s_decompose_to_issues["decompose-to-issues"]
        s_define_done["define-done"]
    end

    subgraph S3["3 - Execute"]
        direction LR
        s_subagent_pipeline["subagent-pipeline"]
        s_diagnose["diagnose"]
        s_resolving_merge_conflicts["resolving-merge-conflicts"]
        s_wizard["wizard"]
    end

    subgraph S4["4 - Verify & Review"]
        direction LR
        s_review_gate["review-gate"]
        s_ai_agent_pr_metadata["ai-agent-pr-metadata"]
        s_open_code_review_setup["open-code-review-setup"]
        s_design_composition_check["design-composition-check"]
    end

    subgraph S5["5 - Release"]
        direction LR
        s_release_gate["release-gate"]
        s_changesets_release["changesets-release"]
    end

    subgraph CTXOUT["Any stage - context runs out"]
        direction LR
        s_handover["handover"]
        s_caveman["caveman"]
    end

    subgraph EXT["External-repo contribution track"]
        direction LR
        s_external_pr_viability["external-pr-viability"]
        s_external_pr_style["external-pr-style"]
        s_external_campaign_triage["external-campaign-triage"]
        s_external_pr_viability --> s_external_pr_style
        s_external_pr_style --> s_external_campaign_triage
    end

    subgraph GUARD["Always-on guardrails & repo setup"]
        direction LR
        s_git_guardrails_claude_code["git-guardrails-claude-code"]
        s_docker_volume_guardrails["docker-volume-guardrails"]
        s_docker_db_guardrails["docker-db-guardrails"]
        s_writing_for_agents["writing-for-agents"]
        s_write_prompt_guide["write-prompt-guide"]
        s_tmux_orphaned_socket["tmux-orphaned-socket"]
        s_vps_cleanup["vps-cleanup"]
    end

    subgraph BLOCK["Blocked on a human"]
        direction LR
        s_hitl_blocker["hitl-blocker"]
    end

    subgraph X_engineering["Unrouted engineering skills"]
        direction LR
        s_git_identity_guard["git-identity-guard"]
    end

    ROUTER --> S0
    S0 --> S1
    S1 --> S2
    S2 --> S3
    S3 --> S4
    S4 --> S5
    S5 --> DONE([" Merged & released "])
    S3 -.session or agent boundary.-> CTXOUT
    ROUTER --> EXT
    S3 -.human-only blocker.-> BLOCK
    GUARD -.enforced throughout.-> ROUTER

Loading

30 skills across engineering, product, productivity. Generated by scripts/generate-workflow-diagram.mjs and regenerated on every Changesets release.

Install

Pick whichever fits how you work. All three end up in the same place: the skill files sitting where your agent looks for them.

1. Everything, via npx (recommended)

npx skills@latest add wakqasahmed/ai-engineering-workflow-skills

This installs every skill in the pack for whichever agent you're using (Claude Code, Cursor, Codex, and 70+ others — see the skills CLI). Add -g to install once for every project instead of per-project, or -a claude-code to target one agent specifically.

2. Just one skill

Don't need the whole pack? Install a single skill by its name (skill names match their folder, e.g. clarify-work):

npx skills@latest add wakqasahmed/ai-engineering-workflow-skills --skill clarify-work

Or point straight at one skill's folder on GitHub:

npx skills add https://github.com/wakqasahmed/ai-engineering-workflow-skills/tree/main/skills/engineering/clarify-work

3. No Node/npx available — manual zip install

1. On this repo's GitHub page: Code → Download ZIP.
2. Unzip it.
3. Copy whichever skills/<category>/<name>/ folder(s) you want into your agent's own skills directory (for Claude Code, that's .claude/skills/ in your project, or ~/.claude/skills/ for a global install; other agents use their own equivalent path).

No installer, no dependency — just files your agent already knows how to read.

External Skill Prerequisites

Three workflow skills referenced in this playbook (test-driven-development, code-simplification, security-and-hardening) are external companions maintained in the addyosmani/agent-skills pack. To install them alongside this repository:

npx skills add addyosmani/agent-skills --skill test-driven-development
npx skills add addyosmani/agent-skills --skill code-simplification
npx skills add addyosmani/agent-skills --skill security-and-hardening

Using This Skillpack

Once installed, your agent discovers model-invoked skills automatically when your prompt matches each skill's description frontmatter. Skills with disable-model-invocation: true run only when explicitly invoked. For repositories adopting this workflow, AGENTS.md provides additional repo-level routing rules and a Trigger Map for agents that load it as an instruction file (you can also invoke skills explicitly by name or slash command, e.g. /roast, /clarify-work).

Standard Prompt Pattern

To anchor an agent session to this workflow playbook, reference system-level/core.md and AI_ENGINEERING_WORKFLOW.md in your project's instructions:

"Follow system-level/core.md for invariant operating rules. For non-trivial engineering work, follow AI_ENGINEERING_WORKFLOW.md and use the skills in this repository."

Worked Workflow Examples

1. Building a New Feature from Scratch

• Pressure-test the idea: Run roast to stress-test assumptions across product, architectural, and security angles.
• Clarify ambiguities: Run clarify-work to resolve requirements, constraints, and the smallest viable scope.
• Draft specification: Run to-prd to lock in clear acceptance criteria and verification plans.
• Decompose into vertical slices: Run decompose-to-issues to break the plan into independent, issue-sized units.
• Implement and verify: Use subagent-pipeline (or an issue-scoped agent followed by review-gate) to implement and test each slice.
• Ship: Run release-gate before releasing to staging or production.

2. Investigating Hard Bugs & Regressions

• Construct feedback loop & minimise: Run diagnose to build a fast, deterministic loop, reproduce the bug, and minimise it to load-bearing inputs.
• Test-first fix: Use test-driven-development to turn the minimised repro into a failing regression test and verify the fix.
• Semantic review: Run review-gate to check for unintended side effects, contract breaks, or performance regressions.

3. Contributing to an External Upstream Repo

• Verify maintainer receptivity: Run external-pr-viability to ensure the repository actively merges outside contributions before investing implementation time.
• Test and implement: Implement the fix following the target repo's exact existing conventions and test suites.
• Draft authentic PR text: Run external-pr-style to strip formulaic AI section templates, sycophancy, and verbose filler.
• Track state across a multi-repo campaign: Run external-campaign-triage when many candidates are in flight across repos we don't own, and before sending any follow-up comment on a stalled PR.
• Limit concurrent open PRs: Maintain at most 3 open external PRs concurrently per third-party repo (recommended), not a campaign-wide total, to avoid being flagged as an automated spammer by maintainers or platform abuse detection.

4. Releasing Versioned Packages

• Record release intent: Run changesets-release to create changesets, validate semver bumps, and check changelogs.
• Pre-release gate: Run release-gate to verify clean build artifacts, green CI, and smoke-tested installation scripts.

5. Context Compaction & Agent Handover

• Cross session or agent boundary: Run handover when context usage exceeds 40%, when 5-10% of context remains, or when passing work to a fresh agent.

6. Token-Saving Communication

• Compress ongoing technical chat: Use caveman only when the user explicitly asks for caveman mode or ultra-compressed replies; keep it active until the user says "stop caveman" or "normal mode", except for Auto-Clarity safety cases.

Available Skills

Start with workflow-router if you're not sure which skill applies — it routes a work request to the smallest applicable delivery workflow.

Skill	What it covers
ai-agent-pr-metadata	Add GitHub-visible AI agent and AI code-review metadata and exact agent labels without adding AI attribution to commits, and scope Alibaba/Open Code Review's review surface to control LLM token spend.
changesets-release	Records release intent with Changesets and guides semver, changelog, CI, and artifact-version checks for independently distributed packages.
clarify-work	Clarify non-trivial engineering work before implementation by resolving ambiguity, terminology, constraints, and the smallest viable path.
decompose-to-issues	Break high-level work into independently executable GitHub issues using vertical slices.
define-done	Define acceptance criteria, risk level, and verification before editing.
design-composition-check	Falsify a new or unfamiliar design system by rendering its hardest UI compositions before other features build on it.
diagnose	Disciplined diagnosis loop for hard bugs and performance regressions: reproduce → minimise → hypothesise → instrument → fix → regression-test.
docker-volume-guardrails	Set up a hook that unconditionally blocks Docker commands that permanently delete a volume (docker volume rm/prune, docker rm -v, docker system prune --volumes, docker compose down -v).
external-campaign-triage	Track state across many candidate issues, PRs, and repos in a multi-repo external open-source contribution campaign, using a local tracker instead of GitHub labels.
external-pr-style	Write PR descriptions for third-party upstream repos in natural human prose to avoid maintainer AI-rejection patterns.
external-pr-viability	Check whether an upstream repo actually merges outside contributors before investing implementation time in an unsolicited PR.
git-guardrails-claude-code	Keep agentic git operations safe and deterministic under Claude Code: protect main/master, enforce branch hygiene, and prevent destructive commands.
git-identity-guard	Install a $PATH-level git wrapper that hard-blocks any commit or push under the wrong author/committer identity, everywhere on the machine, with no override — for when commits keep landing under the wrong email and breaking CLA bots or account-linked contribution credit.
hitl-blocker	Convert human-only blockers into visible GitHub issues.
open-code-review-setup	Set up Alibaba Open Code Review (OCR) on a repository that lacks it, or audit and update an existing setup.
release-gate	Check deployment, staging, rollback, and health verification before release.
resolving-merge-conflicts	Resolve git merge conflicts safely by understanding both sides of the diff, preserving intent, and verifying resolution with tests.
review-gate	Run an independent semantic review gate before merging non-trivial work, on top of (not duplicating) Alibaba Code Review and CI.
subagent-pipeline	Run a cold-start implementer, reviewer, and fixer subagent chain for one issue, gated by CI, ending in a staging PR.
tmux-orphaned-socket	Diagnose and recover from an orphaned tmux socket (error connecting to /tmp/tmux-*/default) after a /tmp cleanup, without assuming the sessions are lost.
to-prd	Synthesize the current conversation and repository context into a concise product and engineering spec, publish it to the project issue tracker, and gate agent readiness before decomposition.
vps-cleanup	Reclaim disk on a shared dev/staging VPS in approval-gated tiers (regenerable caches, then /tmp worktrees and caches, then unused Docker images) without breaking concurrent sessions; volumes are report-only.
wizard	Generate an interactive bash wizard that walks a human through manual steps (provisioning infrastructure, setting up credentials or secrets, walking an unfamiliar dashboard, or running a cutover).
workflow-router	Routes a software-work request to the smallest applicable delivery workflow and records repository conventions once.
write-prompt-guide	Produce a pack-specific PROMPT_GUIDE.md that teaches end users what to type to get a good run out of one Agent Skill pack, from that pack's own SKILL.md, README, and open issues.
writing-for-agents	Reference for authoring documents an agent consumes: skills, AGENTS.md/CLAUDE.md, and progressive disclosure references.
roast	Use when someone asks to roast an idea, pressure-test or stress-test an idea, validate a business idea, "convene the council", get a brutal second opinion before building something, or says "/roast".
caveman	User-invoked persistent ultra-compressed communication mode that removes filler while preserving technical accuracy and temporarily restores full clarity for safety-critical content.
handover	Compact the current conversation into a handover document a fresh agent can pick up and continue seamlessly.

Contents

The installable skills live in skills/engineering/, skills/product/, and skills/productivity/.

Versioning and releases

This pack is versioned with Changesets. Nothing is published to npm — the install path stays npx skills add wakqasahmed/ai-engineering-workflow-skills — so Changesets only records release intent, sets the version, and writes CHANGELOG.md.

Add a changeset in the same PR as the change:

npx changeset

Bump sizes for this repository:

Bump	Use for
patch	Skill content fixes, clarifications, corrected references, doc and eval tweaks.
minor	A new skill, or a new capability inside an existing one.
major	A skill removed or renamed, or a documented interface changed (frontmatter name, invocation, hook contract, or template a consumer copies).

On push to main, .github/workflows/release.yml opens or updates a "Version Packages" PR that consumes the pending changesets, bumps the version, writes the changelog, and regenerates the README workflow diagram in the same commit. The diagram itself comes from scripts/generate-workflow-diagram.mjs, which reads the skills on disk; run it locally after adding or removing a skill:

node scripts/generate-workflow-diagram.mjs          # rewrite the README block
node scripts/generate-workflow-diagram.mjs --check  # what CI runs; fails on drift

Sources

Skills whose methodology rests on first-party vendor documentation cite it in SOURCES.md, a ledger of publisher, URL, and the specific claims each source supports.

Aggregate catalogue

Changes merged to this repository are automatically synchronized to wakqasahmed/skills. Treat this repository as the source of truth for engineering workflow skills.

Outcome-eval harness status

Several skills already have a deterministic eval layer. The gated model-harness layer — real skill-enabled vs. disabled comparisons against a live model — is still open work for 9 skills and is not yet tracked.

Fund the real harness runs

The deterministic checks wired into PR CI run free. Proving the outcome-eval harnesses with real, metered model calls costs money:

• Bitcoin (BTC): bc1p5xqamscrz7nu0d8jdmj748rj75sk8khtyxypn3qvsdjms4t4uw2qsjn0he
• Ethereum (ETH) / any ERC-20 including stablecoins: 0x59bc573e414D62d44461234dEf438247dfc3Cf6A

Double-check every character against this page before sending. Full portfolio picture and rationale: wakqasahmed/skills.