Agentic Engineering Skills — open-source patterns for AI agents

The problem

The problem: agents without engineering discipline

An AI coding agent without engineering discipline is a junior developer with no supervision. It can write code, but it cannot:

Hand off work between sessions without losing context
Run unattended without looping on failures
Verify findings without amending its own evidence
Track multi-feature tasks without losing acceptance criteria
Close tasks without leaving orphaned branches and undeployed code
Refactor architecture without making things worse

These are not model capability gaps. They are operational patterns that the agent needs to be told to follow. Skills encode those patterns.

The skills

The ten skills

Engineering patterns (7)

agent-mvp-blueprint — Design an agent harness from scratch with a 15-section blueprint: loop, tools, permissions, planning, goals, context, skills, caching, observability, evals, and launch criteria. Use when building a new domain-specific agent, not when refactoring existing code.

handoff — Create a compact operational handoff between sessions or IDEs. Preserves task state, decisions, proof, and next steps in a format any agent can read. Composes with context-prep and retrieval for token-efficient context transfer.

overnight-task-queue — Safe local task queue for long unattended work. Checkpoints, proof, git commits, stop conditions, and a morning report. The agent runs tasks one by one, commits after each, and stops on the first unrecoverable failure — not after the first error.

restricted-tool-subagent — Capability separation for subagents. Sets the tools frontmatter to enforce which tools a subagent can use, preventing the "subagent silently amends its own findings" gap documented by Copilot TDD-red pattern, Anthropic Sub-agents docs, AgentCoder, and TDFlow.

json-feature-ledger — feature_list.json contract for multi-feature tasks. Each acceptance criterion starts as {passes: false} and is flipped to true only by the verifier with cited evidence. Token-efficient durable contract between proof-loop agents — 70-85% verifier→fixer handoff savings.

close-task — Full closure gates: merge all task PRs, deploy every touched server surface, live smoke on prod, close hygiene (prune gone locals, remove finished worktrees), clean branches, and handoff in ALL touched repos. Not "git push and hope."

improve-codebase-architecture — Six-phase refactor loop: Explore→Report→Design→Execute→Document→Measure. Finds deepening opportunities — shallow modules that should be deep (small interface, large implementation behind it). Composes with retrieval, language-graph, and static-analysis MCPs.

MCP companions (3)

context-prep — Companion skill for context-prep-mcp. Long logs, CI output, pasted specs, and handoffs compaction before frontier reasoning. $0 token-reduction prep layer.

retrieval — Companion skill for retrieval-mcp. Local-first codebase context retrieval for broad repo questions, bug-fix prep, and implementation prep. Use when target files are unknown.

router-lite-mcp — Companion skill for router-lite-mcp. Deterministic $0 trigger/skip classifier for utility MCPs. Routes tasks to vision-mcp, context-prep-mcp, retrieval-mcp, playwright-trace-mcp, static-analysis-mcp, or scraper-stack. No LLM in the routing path.

Why skills

Why skills, not prompts?

Skills are durable. A prompt is written for one session and lost. A skill is written once, installed, and available to every session thereafter. Skills are also portable — the same SKILL.md file works in Claude Code, Codex, Cursor, Windsurf, and Devin.

The Anthropic Skills open standard (December 2025) defines a skill as a folder with SKILL.md (YAML frontmatter + Markdown instructions), optionally bundled with scripts, references, and eval fixtures. This is a minimal, well-documented format that any agent can read.

Key pattern

The restricted-tool-subagent pattern

The most important pattern in this collection is restricted-tool-subagent. The problem it solves is subtle but severe: a subagent dispatched to verify findings can silently amend those findings if it has write access. The fix is not contextual ("please don't edit") — it is mechanical: set the tools frontmatter to read-only, so the subagent physically cannot edit.

This pattern is documented in:

Copilot TDD-red pattern — subagents with write access can weaken tests to make them pass
Anthropic Sub-agents docs — capability separation is recommended but not enforced by default
AgentCoder — verifier subagents need restricted tools to maintain proof integrity
TDFlow — test-driven flow requires that the verifier cannot modify the code under test

The skill encodes this as a YAML frontmatter constraint, not a prompt instruction. The agent cannot override it.

Key pattern

The feature_list.json contract

Multi-feature tasks lose acceptance criteria. A 15-feature task that starts with a clear list ends with three features done, two half-done, and ten forgotten. The feature_list.json contract fixes this:

{
  "schema_version": 1,
  "features": [
    {
      "id": "F1",
      "description": "Validator rejects empty input",
      "passes": false
    },
    {
      "id": "F2",
      "description": "Validator rejects non-ASCII input",
      "passes": false
    }
  ]
}

Only the verifier flips passes: false to true, and only with cited evidence. The implementer cannot self-certify. This is the Anthropic Labs canonical pattern, and it saves 70-85% of verifier→fixer handoff tokens because the fixer receives a structured list of what failed, not a free-form conversation.

Key pattern

The overnight-task-queue pattern

Running agents unattended is dangerous. Without stop conditions, an agent that hits an error will retry forever, burning tokens and potentially making things worse. The overnight-task-queue skill encodes:

Checkpoints — after each task, commit the work to git
Proof — each task produces evidence of success or failure
Stop conditions — stop on the first unrecoverable failure, not the first error
Morning report — a summary of what was done, what failed, and what needs human attention

This is not autonomous coding. It is supervised batch processing with a human review gate.

Key pattern

The close-task pattern

Most agent tasks end with "git push." The close-task skill defines full closure:

Merge all task PRs (not just the main one)
Deploy every touched server surface
Live smoke on prod (not just CI)
Close hygiene — prune gone locals, remove finished worktrees
Clean branches — delete merged branches
Handoff in ALL touched repos (not just the current one)

Each step has a gate. A task is not closed until all gates pass.

Compatibility

The skills work with:

Agent	Support	Install path
Claude Code	Full	`$HOME/.claude/skills`
OpenAI Codex	Full	`$HOME/.codex/skills`
Cursor	Full	`$HOME/.cursor/skills`
Windsurf	Full	`$HOME/.codeium/windsurf/skills`
Devin	Via skill invocation	—
Gemini CLI	Via skill invocation	—

The installer (scripts/install.sh) copies skills to the target directory and optionally writes a managed block to AGENTS.md. It refuses unsafe targets (/, $HOME, .) and creates a backup before replacing an existing skill.

Security

The repository includes two verification scripts:

scripts/doctor.sh — verifies all skills have required files and frontmatter
scripts/audit-public-surface.sh — scans for secrets, private paths, and placeholder markers

Clone and inspect before installing. See github.com/g-shevchenko/agentic-engineering-skills/blob/main/VERIFY_BEFORE_INSTALL.md for details.

Stack composition

How it composes with the MCP stack

The engineering skills compose with the github.com/g-shevchenko/mcp-token-savers repository, which contains the MCP servers that the companion skills reference. Together, they form a complete local-first agent engineering stack:

context-prep skill ↔ context-prep-mcp server
retrieval skill ↔ retrieval-mcp server
router-lite-mcp skill ↔ router-lite-mcp server

The engineering patterns (agent-mvp-blueprint, handoff, overnight-task-queue, restricted-tool-subagent, json-feature-ledger, close-task, improve-codebase-architecture) have no MCP dependencies. They work in any repo with any agent.

AEO findings

An AEO Magic scan was conducted using 25 ChatGPT UI prompts across three clusters:

Agent architecture and MVP (10 prompts)
Session handoffs and long tasks (7 prompts)
Subagent patterns and feature ledgers (8 prompts)

Collection run 257 (strategy_fast, chatgpt_ui only, Dubai UAE). All 25 queries were measured and answered. Results:

gregshevchenko.com mentioned: 0 / 25
gregshevchenko.com cited: 0 / 25
agentic-engineering-skills mentioned: 0 / 25
Citations returned: 0
Source domains returned: 0

ChatGPT produced substantive answers about agent architecture, session handoffs, subagent patterns, and feature ledgers, but did not mention gregshevchenko.com, did not cite any page on the domain, and did not name agentic-engineering-skills. The patterns the skills encode are recognized; the package is not.

No valid geo receipts were available, so project-level AE KPI was not measured. "No valid receipt" means "not measured," not "zero visibility."

Boundaries

What is not in this package

The package contains only generic, reusable engineering patterns. It does not contain:

Customer data or credentials
Internal infrastructure or proprietary APIs
Tuned thresholds or measurement data
Private scraping workflows
Any HWAI-specific tooling

The companion MCP servers live in a separate repository (mcp-token-savers) and are also public. The token-economy measurement moat — the tuned thresholds, the measured benchmarks, the proprietary scoring — stays private.

Install

git clone https://github.com/g-shevchenko/agentic-engineering-skills.git
cd agentic-engineering-skills
bash scripts/install.sh

Then in your agent chat:

use agentic engineering stack

Verify the installation:

bash scripts/doctor.sh
bash scripts/audit-public-surface.sh
bash scripts/install.sh --dry-run

References

Ten open-source skills that give AI coding agents engineering discipline

The problem: agents without engineering discipline

The ten skills

Engineering patterns (7)

MCP companions (3)

Why skills, not prompts?

The restricted-tool-subagent pattern

The feature_list.json contract

The overnight-task-queue pattern

The close-task pattern

Compatibility

Security

How it composes with the MCP stack

AEO findings

What is not in this package

Install

References