AI Agent Skills Workflow Framework Development
vigneshwar L
The Problem
AI coding agents are powerful. They can write code faster than any human.
But left to their own judgment, they also:
Skip writing specs because "the task is obvious"
Skip tests because "I'll add them later"
Deploy without a rollback plan because "it's a small change"
Ship ML models without safety evaluation because "the numbers look good"
Build data pipelines without quality gates because "the source is reliable"
Ignore accessibility because "we'll fix that before launch"
The result is fast code that fails slowly.
AI Agent Skills solves this by giving agents the same disciplined workflows senior engineers use — with explicit steps, anti-shortcut enforcement, and evidence-based verification gates that cannot be bypassed.
What Is This?
AI Agent Skills is a framework of 40+ structured workflow files — called skills — that AI coding agents load before doing work.
Each skill encodes how a senior engineer approaches a specific task: not just what to do, but in what order, what to verify at each step, what shortcuts to refuse, and what evidence to produce before calling the work done.
The framework covers every phase of software development — and uniquely extends into AI/ML engineering, data pipelines, agent orchestration, mobile development, and incident response — domains that no other skill framework addresses.
⚡ 60-Second Setup
Other platforms: Claude Code · Cursor · Gemini CLI · GitHub Copilot · Windsurf · Kiro · OpenCode · Any Agent
🏗️ Framework Architecture
🎯 The 8 Core Commands
Click to expand command reference
Command Phase Skill Loaded What It Enforces
/spec Define spec-driven-development Spec written before any code /plan Plan planning-and-task-breakdown Atomic tasks, critical path, 20% buffer /build Build incremental-implementation Vertical slices, walking skeleton first /test Verify test-driven-development Failing test before implementation /review Review code-reviewer agent Correctness · Security · Performance · Readability · Architecture /simplify Review code-simplification Chesterton's Fence before every removal /ship Ship deployment-strategy Rollback procedure written before deploy starts /incident Respond incident-response Mitigate first · Diagnose second · Post-mortem required📚 Complete Skill Library
🎯 Define Phase — 3 Skills
Sharpens a vague idea into a buildable, scoped proposal before writing a spec or a line of code.
Key steps: State the problem (not the solution) → Identify who has the problem → Measure the pain → List 3 candidate solutions → Score and select → Define out-of-scope → Define the success metric
Anti-rationalization it prevents:
"We know what we want to build — let's just build it"
Forces a written specification before any implementation code. A spec reveals ambiguities that would otherwise become bugs.
Key steps: Capture raw requirement → Stakeholders and success criteria → Functional requirements → Non-functional requirements → Data model → Interface contract → Open questions → Get sign-off
Anti-rationalization it prevents:
"This feature is obvious — I don't need to write it down"
Converts stakeholder requests into verified, unambiguous, testable requirements. Identifies conflicts and gaps before they become expensive bugs.
Key steps: Collect all sources → Categorize (functional/non-functional/constraints/assumptions) → Eliminate ambiguity → Resolve conflicts → Validate completeness → MoSCoW prioritization → Traceability matrix
Anti-rationalization it prevents:
"We can figure out edge cases as we go"
📋 Plan Phase — 3 Skills
Decomposes work into atomic, independently verifiable tasks. Prevents the "everything at once" trap that leads to big-bang, unshippable branches.
Key steps: Vertical slices →
[Verb] [Object] [Constraint] format → 2-day rule → Define done → Map dependencies → Identify critical path → Add 20% buffer → Sequence risky tasks firstAnti-rationalization it prevents:
"These tasks are too small to track"
Makes decisions that are hard to reverse — explicit, documented, and traceable to requirements. Every decision has an ADR.
Key steps: Establish constraints → Rank quality attributes → Define component boundaries → Map data flow → Choose sync vs async → Design for failure → Write ADRs → Map to requirements
Anti-rationalization it prevents:
"Microservices are more scalable" · "We don't need an ADR for this"
Makes technical and delivery risk explicit before it becomes an incident. Includes a pre-mortem to surface unknown unknowns.
Key steps: List all risks → Score (likelihood × impact) → Classify (known/known, known/unknown, unknown/unknown) → Design mitigations → Run a pre-mortem → Define go/no-go criteria
🔨 Build Phase — 16 Skills
Ships working vertical slices instead of big-bang implementations. Every commit leaves the system deployable.
Write tests before code. TDD is not about testing — it's about design. The test suite is proof of correctness, not evidence of effort.
APIs are promises. Design them for the caller, not the implementation. Version from day one. Respect Hyrum's Law.
Build UIs that implement all states (loading, empty, error, populated), are accessible, perform within budget, and have error boundaries.
Design services with explicit contracts, failure handling on all outbound calls, input validation at the boundary, and graceful shutdown.
Design schemas for the queries, not just the data. Backward-compatible migrations. Indexes verified with EXPLAIN. Migrations tested at production scale.
The most comprehensive ML engineering skill in any framework. Covers the full lifecycle with safety baked in.
What makes it unique: Data leakage detection · Reproducible training pipelines · Evaluation harness built before training · Safety evaluation (prompt injection, jailbreak, hallucination) · Staged rollout with distribution shift monitoring
Anti-rationalization it prevents:
"The eval numbers look good" · "We'll add safety checks after launch"
Data pipelines fail silently. This skill adds quality gates, data contracts, lineage tracking, and idempotency to every pipeline.
What makes it unique: Contract validation at ingestion · Quality gates before writes · Dead letter queue for bad data · Lineage for GDPR compliance · Late-arriving data strategy
Anti-rationalization it prevents:
"The source is reliable — we don't need contract validation"
Mobile-specific constraints: offline-first design, main thread discipline, battery efficiency, crash rate targets, app store compliance.
All infrastructure is version-controlled code with the same discipline as application code: plan review, blast radius analysis, staged apply, drift detection.
Anti-rationalization it prevents:
"It's a small change — I'll do it in the console"
Justifies the split before making it. Service boundaries by business capability. Async-first communication. No shared databases.
Prompts are code. Version them. Test them. Validate their output format. Run regression tests in CI. Test for prompt injection.
Anti-rationalization it prevents:
"Prompt engineering is just natural language — I don't need to test it"
Build RAG systems with rigorous evaluation at every layer: retrieval accuracy, faithfulness, answer relevance, and production staleness monitoring.
Key metrics: Recall@5 > 0.80 before moving to generation · Faithfulness scoring · Context relevance evaluation
Multi-agent systems need typed tool interfaces, audit logs, maximum step limits, structured inter-agent communication, and human approval for irreversible actions.
Anti-rationalization it prevents:
"The agent is smart enough to handle edge cases" · "We don't need a maximum step limit"
Manage the context window deliberately: budget, priority order, compression, and quality monitoring.
Every non-obvious implementation decision must be traceable to an authoritative source (RFC, official docs, spec). No assumptions without sources.
🔍 Verify Phase — 7 Skills
Staff-engineer-level review across five dimensions: Correctness · Security · Performance · Readability · Architecture.
Blocking criteria: security vulnerabilities, correctness failures in the happy path, missing tests for new behavior.
STRIDE threat modeling · Input validation · Auth/authz · Secrets management · Dependency audit · Data protection · Security headers.
Key rule: No secrets in code, commits, or logs. Verify with
git log --all -p | grep -i "secret\|password\|token\|key" — if anything shows, rotate immediately.Profile before optimizing. Optimize the bottleneck. Measure the improvement. Verify correctness. Document why the code looks unusual.
Anti-rationalization it prevents:
"I know this is slow — I don't need to profile"
WCAG 2.2 AA compliance: semantic HTML, keyboard navigation, screen reader testing, color contrast, dynamic content announcements, motion preferences.
1 in 4 adults has a disability. Inaccessible software is defective software.
Structured logging · Four golden signals · Distributed tracing · SLIs and SLOs · Alerting on symptoms (not causes) · Runbooks for every alert.
Reproduce reliably → form a hypothesis → isolate the smallest reproduction → test the hypothesis → fix the root cause → write a regression test.
Anti-rationalization it prevents:
"I'll try changing this and see if it works"
Systematically evaluate LLM outputs across correctness, relevance, groundedness, safety, format, and latency. Prevent regressions in CI.
Key rule: 100+ example evaluation dataset · LLM-as-judge calibrated against humans · Adversarial eval (injection, jailbreak, hallucination) · Blocking threshold in CI
🚀 Ship Phase — 5 Skills
Conventional commits · PRs reviewable in under 30 minutes · Semantic versioning · No secrets committed (pre-commit hooks enforced).
Pipeline stages with time budgets · Required gates (tests, security, linting) · Branch protection · Flaky test rate < 1% · Full pipeline under 15 minutes.
Write the rollback procedure before deploying. Staged rollout (1% → 10% → 50% → 100%). Bake time at each stage. Backward-compatible database migrations. Automated success criteria.
Anti-rationalization it prevents:
"It's a small change — we can deploy to 100%"
Five-phase structured response: Detect → Communicate → Mitigate → Resolve → Learn. Blameless post-mortems required. Status page updated within 15 minutes of detection.
Key rule: Mitigate before you diagnose. Rollback first, investigate second.
Documentation that stays accurate: audience-first, why not what, close to the code. ADRs for decisions that are hard to reverse.
⚙️ Meta Skills — 3 Skills
The entry point. Load at session start to discover and compose all other skills.
Applies Chesterton's Fence: understand why every piece exists before removing it. Targets: dead code, premature abstraction, unnecessary indirection, magic numbers, duplicate logic.
Lists all implicit assumptions, classifies them by cost-if-wrong, and verifies high-cost assumptions before shipping.
🤖 Agent Personas
Specialist agents for focused review work. Load one to get dedicated expertise on a specific dimension.
View all 8 personas
Code Reviewer — Staff Engineer
Reviews PRs across five dimensions: Correctness, Security, Performance, Readability, Architecture. Produces severity-ranked findings (Blocking / Major / Minor / Nit) with specific, actionable suggestions.
Security Auditor — Security Engineer
STRIDE threat modeling, OWASP top 10, supply chain risk. Produces findings with attack scenarios and remediation steps. Critical findings block the PR.
Test Engineer — QA Specialist
Reviews test coverage quality across strategy, completeness, design, and maintainability. Flags missing tests, brittle tests, and tests that give false confidence.
Performance Engineer — Performance Specialist
Profile-first analysis across latency, throughput, memory, database, and frontend. Produces quantified findings: current numbers, root cause, expected improvement.
⭐ ML Engineer — Machine Learning Specialist
Reviews ML systems across data quality, modeling rigor, evaluation harness, safety/fairness, and production readiness. Flags silent failure modes before they reach users.
⭐ Data Engineer — Data Infrastructure Specialist
Reviews pipelines across data contracts, reliability, quality, lineage, and performance. Evaluates downstream impact of every finding.
⭐ DevOps Engineer — Infrastructure & Reliability Specialist
Reviews infrastructure changes across IaC quality, CI/CD design, reliability patterns, security controls, and observability completeness.
⭐ Tech Writer — Documentation Specialist
Reviews documentation for audience clarity, structure, accuracy, and maintainability. Catches docs that are wrong, missing, or that nobody will actually read.
⭐ = New personas not available in any other agent skills framework
📦 Skill Packs
Skill packs are curated bundles for specific contexts. Instead of figuring out which skills to load, pick the pack that matches your work.
View all 6 packs
For LLM-powered features, ML training pipelines, RAG systems, and AI agents.
Includes: ai-ml-engineering · prompt-engineering · rag-system-design · agent-orchestration · llm-evaluation · security-and-hardening · deployment-strategy
Key personas: ML Engineer · Security Auditor
For ETL/ELT pipelines, data warehouses, and data-driven systems.
Includes: data-pipeline-engineering · database-design · test-driven-development · observability-and-monitoring · security-and-hardening
Key personas: Data Engineer · Security Auditor
For end-to-end feature development across database, API, and UI.
Includes: All 8 phases in order — from idea-refine through deployment-strategy
For web UIs, component libraries, and design systems.
Includes: frontend-engineering · accessibility-engineering · performance-optimization · security-and-hardening (XSS) · test-driven-development
Move fast without breaking production. The minimum viable engineering discipline.
Includes: spec-driven-development · incremental-implementation · security-and-hardening · deployment-strategy · observability-and-monitoring
Non-negotiables even at early stage: Auth. Input validation. No secrets in code. Rollback plan. Error alerting.
For teams with compliance requirements, audit trails, and formal change management.
Includes: All skills with formal gates — requirements traceability, ADRs for all decisions, two-approval PRs, change records for deployments, blameless post-mortems for incidents.
📐 Reference Checklists
Copy these into your PR templates or review workflows.
Checklist What it covers Security Checklist Input validation · Auth/authz · Secrets · Data protection · Dependencies · Headers AI/LLM Safety Checklist Prompt injection · Output safety · Data privacy · Reliability · Agent safeguards Performance Checklist Database · Application · Network · Frontend Core Web Vitals Accessibility Checklist WCAG 2.2 AA · Semantic HTML · Keyboard · Screen reader · Color · Motion Testing Patterns Testing pyramid · Unit/Integration/E2E patterns · Mocks vs fakes · Contract testing
🧠 The Philosophy
Three commitments every skill makes
1. Process over prose Skills are executable workflows with checkpoints — not reference material you read once and forget. Every skill tells you exactly what to do at each step.
2. Anti-rationalization built in Every skill documents the exact excuses agents (and humans) use to skip steps — and rebuts them directly. For example:
"This is too small to need a spec" If it's obvious, the spec takes 10 minutes. If it's not obvious, the spec saves days. Either way: write it.
"We'll add monitoring after we know what to monitor" By the time you know what to monitor, you've already had the incident that taught you.
"The agent is smart enough to handle edge cases" The agent has never seen your edge cases. Write tests for them.
3. Evidence over confidence "I think it works" is not a verification. Every skill's Verification Requirements section specifies the evidence required — logs, test output, metrics, reviewer sign-off — before work can be marked complete. Subjective approval is not acceptable.
Engineering principles encoded in the framework
The framework embeds hard-won engineering knowledge including:
Hyrum's Law — all observable behaviors of a system will be depended on by somebody; design and change carefully
Chesterton's Fence — understand why something exists before removing it
Beyoncé Rule — if you liked it, you should have put a test on it
The Beyoncé Corollary — if a test doesn't fail when the behavior breaks, it provides no value
Walking Skeleton — get end-to-end working first; flesh it out incrementally
Vertical Slices — ship thin, complete features rather than horizontal layers
Blameless Post-Mortems — systems fail, not people; fix the system
🏗️ How Skills Work
Every skill follows the same structure:
Difficulty levels:
junior — Any engineer can apply without domain expertisesenior — Requires understanding of engineering trade-offsstaff — Requires system-level thinking and knowledge of failure modes at scale🌍 Platform Support
Platform Setup Notes 🤖 Claude Code Setup Guide Full slash commands + hooks auto-load 🖱️ Cursor Setup Guide Via
.cursorrules 🔷 Gemini CLI Setup Guide TOML or markdown format 🐙 GitHub Copilot Setup Guide Via .github/copilot-instructions.md 🌊 Windsurf Setup Guide Via .windsurf/rules.md ⚡ Kiro Setup Guide Via project instructions 💻 OpenCode Setup Guide Symlink-based integration 🔧 Any Agent Setup Guide System prompt injection🛠️ Session Hooks
Auto-load the framework at the start of every Claude Code session:
On every new session, the agent will see:
✅ Always Active Rules
These rules apply in every session, regardless of which skill is loaded:
Rule Why Spec before code Unspecced features solve the wrong problem correctly Tests before merging "I'll add tests later" never happens Security is not optional Every auth/data/input change needs a security pass Rollback before deploy If you can't write the rollback, you're not ready to deploy Evidence over confidence "I think it works" is not a verification Smallest safe change Make it smaller and ship it sooner
🤝 Contributing
Skills must be:
Specific — Actionable steps an agent can execute, not vague principles
Verifiable — Clear exit criteria with measurable evidence
Grounded — Based on real production engineering practice
Minimal — No duplication; reference other skills instead
Anti-shortcut — Include documented rebuttals to common rationalizations
How to contribute:
Create
skills/<name>/SKILL.md using the skill anatomy templateAdd to the table in README.md
Run
bash hooks/session-start-test.sh (must pass)Open a PR with title:
feat(skill): add <skill-name>Looking for contribution ideas? Check the open issues — issues labeled
good first issue are the best starting point.See CONTRIBUTING.md for the full guidelines.
📊 Repository Stats
⭐ Support This Project
If AI Agent Skills helped you ship better software, give it a star — it helps the project reach more engineers who need it.
Share it with your team. Share it with anyone who uses AI coding tools. The more engineers who use disciplined AI workflows, the better software gets shipped.
Built by Vignesh · MIT License · Made to make AI agents as disciplined as your best engineers
Like this project
Posted Jul 26, 2026
Developed AI Agent Skills, a disciplined workflow framework for AI coding agents.
Likes
0
Views
1
