AI Agent Skill Architecture & Development Cheat Sheet

In the domain of Agent Engineering, a Skill represents a highly encapsulated, reusable software capability unit that packages domain-specific role personas, tool bindings, standard operating procedures (SOP), and structured output schemas.

💡 Core Positioning: If a Large Language Model (LLM) is a general knowledge brain, and the Harness is the operating system chassis, then Skills are the specialized professional toolkits equipped by the AI. By formalizing ad-hoc prompts and multi-step tool calls into versioned Skills, agents move beyond unpredictable improvisation to achieve deterministic, enterprise-grade task completion.

Capability Abstraction Ladder:
Prompt (Intent) ➔ Tool (Atomic API) ➔ Skill (Packaged Capability) ➔ Workflow (DAG Flow) ➔ Agent (Autonomous Entity)

$$\text{Production Skill} = \text{Role (Persona)} + \text{Tools (Bindings)} + \text{Workflow (SOP Flow)} + \text{Schema (Output Contracts)}$$

🔗 Related Cheat Sheets: AI Agent Harness Engineering Architecture Cheat Sheet · LLM & Agent Technical Concepts Cheat Sheet · 4 Leading Always-on Agents Comparison Cheat Sheet · Claude Code CLI Cheat Sheet

1. Casual Chat vs. Skill-Based Agent Execution Paradigm

flowchart LR
  subgraph Chat ["Ad-hoc Prompt Chat (No Skill)"]
    direction TB
    U1(["User Question"]) --> A1["Raw LLM Direct Inference"]
    A1 --> R1(["Ephemeral Response\n(Hallucination-prone, One-off)"])
  end

  subgraph SkillMode ["Skill Structured Execution Mode"]
    direction TB
    U2(["User Goal / Objective"]) --> S1["1. Intent Matching & Skill Selection"]
    S1 --> S2["2. Inject Persona, Tools & Constraints"]
    S2 --> S3["3. Step-by-Step SOP & Branch Execution"]
    S3 --> S4["4. Schema Validation & Guardrail Filter"]
    S4 --> R2(["Deterministic Delivery\n(High Stability, Reusable)"])
  end

  style Chat fill:#f8fafc,stroke:#94a3b8,stroke-width:1px;
  style SkillMode fill:#eff6ff,stroke:#2563eb,stroke-width:2px;
  style R1 fill:#fef2f2,stroke:#ef4444;
  style R2 fill:#ecfdf5,stroke:#059669;

Comparative Analysis

Dimension	Ad-hoc Prompt Chat	Skill-Based Agent
Interaction Flow	Single-turn reactive: User inputs prompt, LLM samples next-token probabilities	Task closure loop: Intent recognition ➔ Skill arousal ➔ Stepwise execution ➔ Result verification
Reusability	Ephemeral consumption: System prompts, rules, and formats must be re-typed each time	Plug-and-play: Packaged once as a standard Skill, executable on-demand across teams
Tool Orchestration	None / Static: Confined to internal model weights and knowledge cutoffs	Dynamic tooling: Can invoke CLIs, SQL databases, RESTful APIs, and MCP protocols
Execution Depth	Shallow single-step: Struggles with branching logic, rollbacks, and multi-tool pipelines	Multi-step SOP: Supports conditional branches, retry strategies, exception handlers, and state machines
Determinism	High stochasticity: Susceptible to conversational drift, schema degradation, or subtle hallucinations	Strict contracts: Strictly bound to JSON/Markdown schemas and automated guardrail validation
Maintainability	Transient session state: Context drifts over extended conversations	Version-controlled asset: Managed as code in Git repositories with semantic versioning

2. Four Core Pillars of a Production Skill

1. Role & Intent Trigger (Persona & Activation)

Defines the specialized persona, responsibility boundary, and invocation triggers for the Skill.

Identity Persona Statement: Establishes domain seniority (e.g., Staff Security Engineer, Database Optimization Specialist) to anchor token attention.
Trigger Pattern: Configures keywords, intent classifications, or file-type hooks (e.g., automatically triggers when touching *.sql files).
Competency Boundary: Explicitly defines out-of-scope boundaries to prevent mission creep.

2. Tool Bindings & Permissions (Environment Interface)

Declares the concrete APIs, binaries, and sandboxed access rights required by the Skill.

Atomic Tool Whitelist: Declares required tools (e.g., run_command, read_file, git_diff).
Least-Privilege Enforcement: Constrains write, network, and execution access to prevent catastrophic side-effects.
Schema Contracts: Strict JSON Schema specifications for all inputs and returned payloads.

3. Standard Operating Procedure (SOP Execution Flow)

A structured, phased instruction set governing how the model processes information and handles branches.

Pre-Flight Checks: Verifies environment assumptions (e.g., checking git branch status before applying refactors).
Phased Milestones: Divides execution into discrete phases (Discovery ➔ Staging ➔ Execution ➔ Verification).
Rollback & Retry Strategies: Defines deterministic recovery steps if an execution tool returns a non-zero exit code.

4. Guardrails & Output Schema (Quality & Delivery Contracts)

Establishes the final output format and non-negotiable negative constraints.

Schema Enforcers: Enforces strict JSON, Pydantic, or GitHub Flavored Markdown formats.
Negative Constraints: Outlines forbidden actions (e.g., never expose raw API secrets, never drop production tables).
Self-Correction Criteria: Prompts the agent to run unit tests or linters to verify its own deliverables prior to user hand-off.

3. The Five-Tier Agent Capability Hierarchy

Tier	Core Definition	Typical Form	Autonomous Authority	Intuitive Analogy
1. Prompt (Prompt Text)	Unstructured natural language instruction sent directly to LLM	Plain prompt strings, System Prompts	Zero (No autonomy) Subject entirely to sampling temperature	"A verbal instruction whispered to a worker"
2. Tool (Atomic API)	A single atomic interface that executes a discrete action	A single Python function, CLI utility, REST API	Zero (No autonomy) Executes input parameters and returns payloads	"A wrench inside the toolbox"
3. Skill (Capability Module)	A reusable bundle addressing a specific domain goal (Prompt + Tools + SOP)	Standardized `SKILL.md`, modular Python package	Moderate (Scoped autonomy) Autonomously orchestrates tools per SOP guidelines	"A certified plumber who knows how to fix broken pipes"
4. Workflow (Orchestrated Flow)	A deterministic execution pipeline governed by a strict DAG	Dify / LangGraph / n8n canvas nodes	Low (Deterministic flow) Follows fixed transitions, cannot skip arbitrary nodes	"An automated factory assembly line"
5. Agent (Autonomous Entity)	An autonomous entity with environmental sensing, memory, planning, and self-healing	Claude Code, Devin, Google Antigravity	High (Full autonomy) Breaks down goals, selects Skills, executes, and self-corrects	"A general contractor who delivers a turnkey renovation project"

4. Production `SKILL.md` Specification Template

Modern agentic systems (such as Antigravity, Claude Code, and OpenHands) standardize Skill definitions as repository-level SKILL.md documents:

---
name: code-refactor-expert
description: >-
  Specialized skill for performing automated code quality audits, refactoring,
  and regression test validation. Activates when users request code optimization,
  code smell removal, or architectural cleanups.
version: 1.2.0
tools:
  - run_command
  - read_file
  - edit_file
---

# Code Refactor Expert Skill

## 1. Role & Objective
You are a Staff Software Engineer specializing in codebase refactoring. Your primary
mandate is to eliminate code smells and improve maintainability while strictly preserving
existing behavioral semantics.

## 2. Pre-Flight Checks
Before modifying any files:
1. Run existing test suites via `run_command` to ensure the branch is in an all-green baseline;
2. If tests fail initially, halt and instruct the user to fix existing defects before refactoring.

## 3. Standard Operating Procedure (SOP)
- **Step 1: Code Smell Identification**: Use `read_file` to audit target modules for excessive complexity;
- **Step 2: Incremental Modification**: Apply atomic refactoring steps (e.g., extract function, rename symbol);
- **Step 3: Immediate Verification**: Re-run automated tests after each edit to confirm zero regressions;
- **Step 4: Diff Audit**: Inspect git diffs to ensure no dead code or stylistic disruptions were introduced.

## 4. Guardrails & Negative Constraints
- Never introduce new functional business features during a refactoring pass;
- Never delete or bypass existing unit test assertions;
- Never bump major dependency versions without explicit operator approval.

## 5. Output Delivery Schema
Upon completion, provide a structured summary:
- **Refactoring Type**: [Extract Function / Polymorphic Substitution / Parameter Objectification]
- **Modified Files**: List of affected file paths and line ranges
- **Verification Evidence**: Test pass count and execution timing

5. Five Golden Rules of Production Skill Design

Rule 1: Single Responsibility & High Cohesion
        Each Skill must address a distinct, cohesive domain problem. Avoid bloated
        "god-skills" that attempt to combine disparate, unrelated capabilities.

Rule 2: Idempotency & Reversibility
        Skill execution flows should be idempotent whenever possible. Critical write
        operations must provide backup or rollback mechanisms so retries never corrupt state.

Rule 3: Context Budget Optimization
        Skill instructions must be concise and actionable. Strip verbose textbook essays;
        truncate and summarize large tool logs to prevent context window saturation.

Rule 4: Strict Schema Validation
        Never rely on unvalidated free-form strings for tool inputs. Enforce strict JSON
        Schema or Pydantic validation before tool parameters reach execution layers.

Rule 5: Defensive Graceful Degradation
        Every external tool call must anticipate network timeouts and non-zero exit codes.
        Provide informative remediation suggestions rather than unhandled fatal crashes.