Architecting Agent Skills

A deployable skill is a bundle of: (1) a schema the orchestrator can call deterministically, (2) lifecycle hooks with defined failure semantics, (3) at least one benchmark that proves it works, and (4) provenance for every design choice. If any of the four is missing, the skill is a template, not a system.

Minimal executable unit (OpenAI function-calling schema, per OpenAI Function Calling docs):

JSON
{
  "name": "fetch_and_summarize_doc",
  "description": "Retrieves a document by URL and returns a structured summary.",
  "parameters": {
    "type": "object",
    "properties": {
      "url": {"type": "string", "format": "uri"},
      "max_tokens": {"type": "integer", "minimum": 50, "maximum": 2000, "default": 500}
    },
    "required": ["url"]
  }
}

If asked to "build a skill," produce the full 8-section document below, not a subset.

Progress:

• Section 1: Actions, tasks, mechanics — define atomic callable units
• Section 2: Cognition/architecture/workflow — define reasoning loop and pipeline graph
• Section 3: Hooks and scaffolding — define lifecycle entry points
• Section 4: Schedules and logic gates — define triggers
• Section 5: Methods and benchmarking — define metrics
• Section 6: Prompts — write literal prompt templates
• Section 7: User preferences/personalization — define adaptation state
• Section 8: Deliverables/payloads/assets — define output schemas
• Advanced Concept Matrix — Macro/Meso/Micro misalignment table
• Adversarial alternative methodology with counter-arguments
• Deterministic prompt conversion pass

Each section below is both instruction and template — copy the schema/example blocks directly.

Section 1 — Actions, Tasks, Mechanics

Definition: The atomic unit is a tool call: a named function with typed I/O that the model invokes, and the environment executes, outside the model's own weights. This is the foundational unit in Anthropic's tool use specification and OpenAI's function-calling schema — both treat the LLM as a planner that emits structured calls, not code.

Working example (Anthropic tool-use JSON schema, Messages API):

JSON
{
  "name": "search_codebase",
  "description": "Searches the indexed repository for symbol or string matches.",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": {"type": "string"},
      "file_glob": {"type": "string", "default": "**/*"},
      "max_results": {"type": "integer", "default": 20}
    },
    "required": ["query"]
  }
}

A task is a composed sequence of tool calls bound to a goal; a mechanic is the invariant contract (schema + side-effect boundary) that makes the call composable. This three-tier split (action → task → mechanic) is a design decision on my part for organizing this document — it is not a term used identically across Anthropic/OpenAI/LangChain, though all three implicitly separate "single call" from "goal-directed sequence."

Section 2 — Cognition, Architecture, Workflows/Pipelines

Definition: Reasoning-then-acting in interleaved steps is the ReAct pattern (Yao et al., 2022, "ReAct: Synergizing Reasoning and Acting in Language Models," arXiv:2210.03629): the model emits Thought → Action → Observation triples in a loop until a stopping condition.

Working example (ReAct-style trace, literal text the model produces):

Thought: I need the current file structure before I can locate the failing test.
Action: search_codebase{"query": "def test_", "file_glob": "**/test_*.py"}
Observation: 3 matches: tests/test_auth.py:12, tests/test_db.py:44, tests/test_api.py:8
Thought: test_auth.py is most likely related to the reported bug. I will open it.
Action: read_file{"path": "tests/test_auth.py"}

Pipeline architecture: For multi-step skills with branching/looping (not linear chains), model the skill as a state machine, per LangGraph's graph-based execution model — nodes are tool calls or LLM calls, edges are conditional transitions, and state is an explicit typed object threaded through the graph.

Python
from langgraph.graph import StateGraph, END
from typing import TypedDict

class SkillState(TypedDict):
    query: str
    search_results: list
    summary: str
    retry_count: int

graph = StateGraph(SkillState)
graph.add_node("search", search_node)
graph.add_node("summarize", summarize_node)
graph.add_conditional_edges(
    "search",
    lambda s: "summarize" if s["search_results"] else "search",
    {"summarize": "summarize", "search": "search"}
)
graph.add_edge("summarize", END)
graph.set_entry_point("search")

Use ReAct for single-agent tool loops; use a state graph when the skill has genuine branches, retries, or parallel fan-out — this distinction follows directly from LangGraph's stated rationale for existing (linear chains break down under cyclic/conditional control flow).

Section 3 — Hooks and Scaffolding

Definition: Lifecycle hooks are named entry points the orchestrator guarantees to call at fixed points relative to execution. Anthropic's Claude Code documents exactly this pattern in its hooks feature: PreToolUse, PostToolUse, UserPromptSubmit, Stop, each receiving a JSON payload and able to block/modify/allow execution via exit code or JSON response.

Working example (Claude Code hook config, real schema):

JSON
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "search_codebase",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/validate_query.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/log_tool_call.sh"
          }
        ]
      }
    ]
  }
}

Error-handling scaffold (exit-code contract, per the same spec): exit code 0 = allow, 2 = block and return stderr to the model as feedback, any other non-zero = non-blocking error surfaced to the user. This is the documented mechanism, not a proposal.

Section 4 — Schedules and Logic Gates

Definition — logic gates: Conditional branching on tool output or state, expressed as guard conditions on graph edges (LangGraph conditional edges, cited above) or as if-style routing in orchestration code. There is no single industry-standard DSL for this across frameworks — I present the LangGraph conditional-edge form because it is the most explicit published mechanism; treat the specific syntax as implementation-bound, not universal.

Python
def route_after_search(state: SkillState) -> str:
    if state["retry_count"] >= 3:
        return "fail_gracefully"
    if not state["search_results"]:
        return "search"          # retry
    return "summarize"           # proceed

graph.add_conditional_edges("search", route_after_search)

Definition — schedules: Time- or event-based triggers external to a single conversation turn. No LLM-provider spec standardizes agent scheduling; this is commonly implemented via external cron/queue infrastructure (e.g., a cron job invoking the API, or a message-queue consumer). Marking this explicitly as design decision, not settled practice:

YAML
# design decision — not a published standard; illustrative cron-trigger pattern
schedule:
  trigger: cron
  expression: "0 */6 * * *"     # every 6 hours
  action: invoke_skill
  skill_name: fetch_and_summarize_doc
  payload_template:
    url: "${MONITORED_URL}"

Section 5 — Methods and Benchmarking

Definition: Success is measured by task-completion rate and calibration under a held-out benchmark, not vibes. Two citable references:

1. Toolformer (Schick et al., 2023, arXiv:2302.04761) measures tool-use skill via perplexity reduction and downstream task accuracy when the model self-supervises API-call insertion.
2. ReAct (Yao et al., 2022) benchmarks on HotpotQA (exact-match, F1) and ALFWorld (success rate) — i.e., task-specific outcome metrics, not proxy metrics like fluency.

Working example (benchmark harness config):

YAML
benchmark:
  suite: internal_regression_v3
  metrics:
    - name: exact_match
      target: 0.85
    - name: tool_call_precision   # correct tool chosen / total calls
      target: 0.95
    - name: avg_latency_ms
      target: 3000
    - name: hook_block_rate       # PreToolUse rejections / total attempts
      target_max: 0.05
  eval_set: "./evals/skill_regression_v3.jsonl"
  pass_criteria: "all metrics meet target"

tool_call_precision and hook_block_rate are project-specific metrics I'm defining for this skill, not from a published paper — flagged as design decisions modeled after the outcome-metric philosophy in ReAct/Toolformer, not copies of their exact metrics.

Section 6 — Prompts

Definition: The internal prompt templates that drive the ReAct loop and hook feedback. These are literal, fillable templates, not paraphrased descriptions.

System prompt (skill entry point):

You are operating the "fetch_and_summarize_doc" skill.
You have access to exactly these tools: search_codebase, read_file, fetch_and_summarize_doc.
For every step, output in this exact format:
Thought: <one sentence reasoning>
Action: <tool_name>{<valid JSON matching the tool's input_schema>}
Do not call a tool not listed above. Do not skip the Thought line.
Stop when you have produced a final answer, prefixed with "Final Answer:".

Tool-result injection template:

Observation: {tool_output}
Continue with the next Thought/Action, or output "Final Answer:" if complete.

PreToolUse hook feedback template (on block, exit code 2):

Your last action was blocked: {stderr_message}
Revise the Action. Do not repeat the identical call.

Section 7 — User Preferences and Personalization

Definition: Persistent, user-scoped state that modifies prompt construction or gating without being re-derived each session. No cross-framework standard exists for this; the closest published analog is retrieval-augmented context injection (prepending retrieved facts to the prompt, as in standard RAG architectures, Lewis et al. 2020, arX