A practical guide for designing and implementing a two-tier skill/agent architecture that optimizes context efficiency, maintains clean separation of concerns, and enables scalable AI-assisted workflows.
- Quick Start
- Architecture Overview
- Scope of Applicability
- Design Principles
- Skills: The Discovery Layer
- Agents: The Execution Layer
- Context Efficiency Patterns
- Structured Response Contracts
- Error Handling and Validation
- Security & Safety
- State Management
- File Organization
- Best Practices
- Anti-Patterns to Avoid
- References
This section helps you align existing skills/agents to the v0.5 guidelines. For comprehensive examples, see the companion document: skills-agents-examples.md.
This document is the authoritative v0.5 spec; ignore prior version references.
Step 1: Add version to agent YAML frontmatter
---
name: sc-worktree-create
version: 1.0.0
description: Creates a git worktree for parallel development.
---Step 2: Fence all JSON output in markdown code blocks
Before (unfenced):
{ "success": true, "path": "/repo-feature-x" }
After (fenced):
```json
{
"success": true,
"data": { "path": "/repo-feature-x" },
"error": null
}
```Step 3: Use minimal response envelope
For simple agents, use this minimal envelope:
{
"success": true,
"data": { /* operation-specific results */ },
"error": null
}For complex/stateful agents, use the full envelope (see Structured Response Contracts).
Step 4: Validate versions externally
Create .claude/agents/registry.yaml:
agents:
sc-worktree-create:
version: 1.0.0
path: .claude/agents/sc-worktree-create.md
sc-worktree-scan:
version: 1.0.0
path: .claude/agents/sc-worktree-scan.mdRun validation via CI or pre-commit hook (see Version Management).
This document supports progressive adoption:
| Level | What to Implement | When to Use |
|---|---|---|
| Basic | YAML frontmatter with version, fenced JSON output, minimal envelope | Upgrading existing agents |
| Standard | Full response envelope, error contracts, registry.yaml | Production workflows |
| Advanced | State management, checkpoints, parallel execution, attestation & audit | Complex multi-agent pipelines |
This architecture separates AI assistance into two distinct tiers:
┌─────────────────────────────────────────────────────────────┐
│ Main Claude Session │
│ • Accumulates conversation history │
│ • Reasons about user intent │
│ • Discovers and invokes skills │
│ • Receives distilled results (not tool traces) │
└─────────────────────────────────────────────────────────────┘
│
▼ delegates via skill
┌─────────────────────────────────────────────────────────────┐
│ Skill │
│ • Discoverable by main session │
│ • Translates intent to agent invocation │
│ • Orchestrates multiple agents if needed │
│ • Formats output for user consumption │
└─────────────────────────────────────────────────────────────┘
│
▼ invokes via Task tool (prefer Agent Runner)
┌─────────────────────────────────────────────────────────────┐
│ Agent │
│ • Loads specific instructions │
│ • Performs tool-heavy work │
│ • Returns structured JSON outputs │
│ • Context isolated from main session │
└─────────────────────────────────────────────────────────────┘
- Context quarantine: Tool calls, errors, and retries stay in agent context
- Distilled results: Main session sees summaries, not mechanics
- Preserved reasoning space: Conversation stays focused on intent and decisions
- Granular agents without discovery overhead: Dozens of agents don't clutter decision space
- Cost efficiency: Smaller, focused contexts reduce token consumption
- Reduced correction cycles: Narrow agent scope minimizes errors and corrective iterations
Skills invoke agents using Claude's Task tool, which starts a new Claude instance with isolated context. Prefer invoking via an Agent Runner wrapper that enforces registry policy (path + version) and records an audit entry.
When a skill's SKILL.md instructs to invoke an agent, Claude uses the Task tool (or Agent Runner) to:
- Load the agent's instructions (
.claude/agents/<agent-name>.md) - Execute in a fresh, isolated context
- Return the structured (fenced) JSON result to the skill
Invocation syntax in SKILL.md (safe):
## Agent Delegation
To create a worktree:
1. Use the Agent Runner tool to invoke the `sc-worktree-create` agent.
2. Provide parameters: branch name, base branch.
3. The agent returns JSON; format the result for the user.
Runner prompt example:
"Invoke agent 'sc-worktree-create' as defined in .claude/agents/registry.yaml
with params:
- branch: feature-x
- base: main"What happens:
Skill instructs: "Use Agent Runner to invoke sc-worktree-create agent"
↓
Agent Runner: Resolves path+version from registry, computes file hash, launches Task tool
↓
Agent context (isolated):
- Loads sc-worktree-create.md instructions
- Runs git commands
- Handles errors/retries internally
- Returns fenced JSON result
↓
Agent Runner: Writes redacted audit record (.claude/state/logs/) and forwards JSON
↓
Skill formats for user: "✓ Worktree created at /repo-feature-x"
Inputs to Runner:
agent(string, required): name in.claude/agents/registry.yaml.params(object, required): arguments passed to the agent.version_constraint(string, optional): semver range; default is exact registry version.timeout_s(int, optional): per-agent timeout; default 120s.correlation_id(string, optional): used for aggregation in parallel flows.
Runner behaviors:
- Resolve path and version from
registry.yaml; fail closed on mismatch. - Compute file SHA-256 and include in audit record (stored under
.claude/state/logs/). - Launch Task tool with isolated context; do not stream tool traces to the skill.
- On timeout, return fenced JSON with
success: false,canceled: true,aborted_by: "timeout", anderror.code: "EXECUTION.TIMEOUT". - On registry/path error, return
success: false,error.code: "REGISTRY.RESOLUTION".
Runner output to skill: fenced JSON matching the agent’s envelope. Skills MUST treat unfenced or malformed JSON as failure and surface a concise error.
Some agents run as named, persistent teammates rather than one-shot Task-tool agents. A named teammate is launched with a name parameter (e.g., quality-mgr, scrum-master) and persists as a full process across the session, receiving assignments via team messaging (ATM) and spawning background sub-agents independently.
This is a distinct pattern from the two-tier skill/agent architecture and has different rules:
┌──────────────────────────────────────────────────────────────┐
│ Team Lead Session │
│ • Sends assignments via ATM CLI / SendMessage │
│ • Receives structured status reports from teammate │
└──────────────────────────────────────────────────────────────┘
│
▼ ATM message / SendMessage
┌──────────────────────────────────────────────────────────────┐
│ Named Teammate (e.g., quality-mgr) │
│ • Persistent process, receives messages on arrival │
│ • Loads skill as required reading (behavioral spec) │
│ • Orchestrates background sub-agents directly │
│ • Sends structured status to team lead via ATM │
└──────────────────────────────────────────────────────────────┘
│
▼ Task tool (run_in_background: true)
┌──────────────────────────────────────────────────────────────┐
│ Background Sub-Agents (e.g., rust-qa-agent) │
│ • Invoked by teammate, not by a skill │
│ • Return fenced JSON to the teammate │
│ • Context isolated from teammate session │
└──────────────────────────────────────────────────────────────┘
| Aspect | Background Agent (Task tool) | Named Teammate |
|---|---|---|
| Launch | Task tool, no name param |
Task tool WITH name param (tmux pane) |
| Lifetime | Single invocation, disposable | Persistent across session |
| Communication | Returns fenced JSON to skill | Sends ATM messages to team lead |
| Skill relationship | Skill invokes agent via Agent Runner | Teammate loads skill as required reading |
| Agent Delegation section | Required in SKILL.md | Not applicable — teammate orchestrates directly |
| Output contract | Fenced JSON | Structured ATM message (may include fenced JSON block) |
| Sub-agent spawning | Not typical | Core pattern — spawns background agents with run_in_background: true |
When a skill is designed for use by a named teammate (loaded as required reading into the teammate's prompt), do not include an Agent Delegation section. Instead, describe:
- The workflow the teammate should follow
- Which sub-agents to spawn (with
run_in_background: true) - The structured status format to report back to team lead
- Multi-pass lifecycle (if applicable)
The skill functions as a behavioral spec, not an invocation table. The teammate is the orchestrator.
Example SKILL.md structure for named-teammate skills:
---
name: managing-quality-gh
description: QA orchestration workflow for named quality-mgr teammate. Loaded as
required reading. Defines multi-pass QA lifecycle, sub-agent spawning, and
structured status reporting contract.
---
# Managing Quality (GitHub)
## Scope
[When to use this skill]
## QA Lifecycle
[Multi-pass workflow: IN-FLIGHT → FAIL → PASS]
## Sub-Agent Orchestration
[Which agents to spawn, with run_in_background: true]
## Structured Status Contract
[What to report back to team lead — fenced JSON block format]Named teammate agents (e.g., quality-mgr.md) follow a relaxed version of the Agent Template. The ## Output Format section describes the ATM message format sent to team lead, not a fenced JSON return value. The ## Inputs section describes incoming ATM message fields rather than Task-tool parameters.
The four required sections still apply (## Inputs, ## Output Format, ## Error Handling, ## Constraints), but their content reflects the messaging-based interaction model.
The two-tier skill/agent architecture is most valuable when:
✓ Routine operations with predictable outputs
- Package publishing, code formatting, file organization
- Operations where you want minimal verbosity in the main session
✓ Tool-heavy workflows
- Operations requiring 10+ tool calls to complete
- Complex git operations, database migrations, build orchestration
✓ Repeatable automation
- Tasks performed frequently with similar parameters
- Workflows that benefit from standardized execution
✓ Context isolation is beneficial
- Experimental operations that might fail and retry multiple times
- Operations where failure traces would clutter the main conversation
This architecture can be counterproductive for:
✗ Exploratory or investigative work
- Debugging unknown issues where tool traces provide valuable insight
- Research tasks where you want to see the discovery process
✗ Interactive decision-making
- Workflows requiring frequent human input or approval
- Tasks where intermediate results influence next steps
✗ One-off simple operations
- Single tool calls or straightforward tasks
- Operations that don't justify the overhead of agent orchestration
✗ Debugging and troubleshooting
- When you need full visibility into what tools were called and why
- Error investigation where hiding details makes diagnosis harder
The two-tier pattern hides details and verbosity to keep the main session focused. This is excellent for routine tasks but problematic when those details contain valuable information. Choose this pattern when efficiency and predictability matter more than transparency and exploration.
Skills are the public interface—what Claude discovers and reasons about. Agents are private implementation details that skills invoke via the Task tool (prefer Agent Runner).
User thinks: "I need to manage my git worktrees"
↓
Skill: "manage-worktrees" (orchestrates workflow)
↓
Agents: sc-worktree-create, sc-worktree-scan, sc-worktree-cleanup
(invoked via Agent Runner from the skill)
Tool calls are context-expensive. A single file search generates substantial tokens. By pushing tool-heavy work into agents:
- Tool call traces stay in agent's isolated context
- Main session receives: "worktree created at
/path" - Not: the 15 tool calls it took to get there
Before implementing a skill or agent:
- Define the contract (inputs, outputs, error cases)
- Identify what context the agent actually needs
- Determine the minimal output the skill requires
- Plan error handling across the boundary
Very clear, concise prompts with minimal logic and branching are significantly more likely to succeed. Agents should:
- Focus on a single responsibility
- Have straightforward execution paths
- Avoid complex conditional logic
- Minimize decision points
When an agent grows complex, split it into multiple focused agents rather than adding branching logic.
Skills and agents should reveal complexity only as needed:
- SKILL.md serves as table of contents, pointing to details
- Reference files load on demand
- Scripts execute without loading into context
.claude/skills/
├── manage-worktrees/
│ ├── SKILL.md # Entry point with YAML frontmatter
│ ├── workflows.md # Detailed workflow documentation
│ └── troubleshooting.md # Error handling guide
---
name: manage-worktrees
description: Create, manage, and clean up git worktrees for parallel development.
Use when working on multiple features simultaneously or when isolating
experimental changes.
---
# Managing Git Worktrees
This skill orchestrates git worktree operations for parallel development workflows.
## Capabilities
- Create isolated worktrees for feature development
- Scan existing worktrees and their status
- Clean up completed or abandoned worktrees
## Agent Delegation
This skill delegates to specialized agents via the Agent Runner (Task tool under the hood):
| Operation | Agent | Returns |
|-----------|-------|---------|
| Create | `sc-worktree-create` | JSON: path, branch, success |
| Scan | `sc-worktree-scan` | JSON: list of worktrees |
| Cleanup | `sc-worktree-cleanup` | JSON: cleanup summary |
To invoke an agent, instruct:
"Use the Agent Runner to invoke `<agent-name>` as defined in `.claude/agents/registry.yaml` with parameters: ..."
## Usage
When the user requests worktree operations:
1. Use Agent Runner to invoke the appropriate agent
2. Receive fenced JSON response from agent
3. Format and present results to the userUse gerund form (verb + -ing) for clarity:
- ✓
processing-pdfs,sc-managing-worktrees,publishing-nuget - ✗
pdf-processor,worktree-manager,nuget-publisher
The description field is critical—Claude uses it to select from potentially 100+ skills.
# Good: Specific, includes triggers
description: Create, manage, and clean up git worktrees for parallel development.
Use when working on multiple features simultaneously, isolating experiments,
or when user mentions "worktree", "parallel branches", or "feature isolation".
# Bad: Vague
description: Helps with git operations.Any skill that depends on an external CLI application MUST verify the dependency as its first executable step — before any agent delegation or workflow logic. This prevents opaque agent failures and gives the user actionable remediation.
## Step 1 — Verify [CLI] Installation
\`\`\`bash
which <cli> && <cli> --version
\`\`\`
If not found on PATH, also check common install locations — Claude Code's bash
environment may not share PATH with the interactive shell:
\`\`\`bash
for p in "$HOME/.local/bin/<cli>" "$HOME/.venvs/<cli>/bin/<cli>" \
"$(python3 -m site --user-base 2>/dev/null)/bin/<cli>" \
"/opt/homebrew/bin/<cli>"; do
[ -x "$p" ] && echo "Found at: $p" && break
done
\`\`\`
If found at a non-PATH location, use the full path for all commands, or export
the directory to PATH for this session:
\`\`\`bash
export PATH="$HOME/.local/bin:$PATH" # adjust to actual location
\`\`\`
If not installed: **read `references/installation-and-troubleshooting.md` before proceeding.**Add a minimum version check when the skill has version requirements:
<cli> --version # capture output; halt and direct to installation doc if < X.Y.Z- Verification MUST appear as the first step in SKILL.md, not buried after agent delegation.
- Skills MUST reference
references/installation-and-troubleshooting.mdwhen the CLI is absent (see File Organization). - Do NOT silently proceed with degraded behavior when a CLI is missing; surface the gap and stop.
- If
manifest.yamldeclaresrequires.clientries, the SKILL.md MUST include this Step 1 block — this gives the validation script (validate-agents.py) a checkable invariant.
Claude Code's bash environment inherits a minimal PATH that may omit directories populated by shell init files (.zshrc, .bashrc, pyenv shims, Homebrew, etc.). A CLI that works interactively can silently be absent from the agent's PATH. The two-stage check (which + fallback loop) is the reliable pattern for this environment.
.claude/agents/
├── sc-worktree-create.md
├── sc-worktree-scan.md
├── sc-worktree-cleanup.md
├── nuget-publish.md
└── nuget-validation.md
Each agent does ONE thing well.
Agents should be as small as possible while remaining effective:
- 1–3KB is ideal for focused operations
- 4–8KB acceptable for complex workflows
- 10KB+ consider splitting into planning/execution phases
Every agent MUST declare version in YAML frontmatter:
---
name: sc-worktree-create
version: 1.0.0
description: Creates a git worktree for parallel development.
---Agents ALWAYS return JSON wrapped in markdown code fences. Skills are responsible for user presentation.
```json
{
"success": true,
"data": { ... },
"error": null
}
```---
name: [agent-name]
version: X.Y.Z
description: [One sentence describing what this agent does]
---
# [Agent Name]
## Purpose
[One sentence describing what this agent does]
## Inputs
- `param1`: [description, type, constraints]
- `param2`: [description, type, constraints]
## Execution Steps
1. [Validate inputs]
2. [Perform operation]
3. [Handle errors]
4. [Return structured result]
## Output Format
Return fenced JSON:
```json
{
"success": boolean,
"data": { ... },
"error": null
}- [Error type]: [Recovery strategy]
- [Error type]: [Why it can't be handled]
- [What this agent should NOT do]
- [Boundaries of responsibility]
---
## Context Efficiency Patterns
### Pattern 1: Agent as Disposable Context
Each agent invocation via Agent Runner (Task tool under the hood) is a disposable execution context:
Main Session: "Create a worktree for feature-x" ↓ Skill: Use Agent Runner to invoke sc-worktree-create agent ↓ Agent Context (temporary, isolated): - Loads sc-worktree-create.md instructions - Runs git commands - Handles errors/retries - Returns fenced JSON ↓ Agent Runner: Audit → forwards JSON ↓ Skill: "✓ Worktree created at /repo-feature-x"
### Pattern 2: Planning/Execution Split
For complex operations, split into phases.
### Pattern 3: Validation Gates
Enforce quality gates before expensive operations.
### Pattern 4: Multi-Step Workflows
Orchestrate complex workflows across multiple agents.
### Pattern 5: Parallel Agent Execution (with guardrails)
When operations are independent, invoke agents in parallel using background executions:
- Set per-task timeouts (e.g., 120s default)
- Cap concurrency to 3–4 by default (override only when safe)
- Attach a `correlation_id` per invocation; aggregate results deterministically
- On timeout, return a synthetic failure:
```json
{
"success": false,
"canceled": true,
"aborted_by": "timeout",
"error": {
"code": "EXECUTION.TIMEOUT",
"message": "Agent exceeded per-task timeout",
"recoverable": false,
"suggested_action": "Increase timeout parameter or split agent into smaller tasks"
}
}
Aggregation contract (normative):
{
"parallel": true,
"concurrency": 4,
"per_task_timeout_s": 120,
"results": [
{ "correlation_id": "style", "success": true, "data": { /* ... */ }, "error": null },
{ "correlation_id": "security", "success": false, "canceled": true, "aborted_by": "timeout", "error": { "code": "EXECUTION.TIMEOUT", "message": "Agent exceeded per-task timeout", "recoverable": false, "suggested_action": "Increase timeout parameter or split agent into smaller tasks" } }
],
"summary": {
"all_successful": false,
"failed": ["security"],
"succeeded": ["style"]
}
}Rules:
- Results MUST be ordered by
correlation_idfor determinism. - Skills SHOULD surface partial failures with the
summaryobject; do not silently drop failing branches. - No automatic retries unless
error.recoverableis true; cap retries at 1 by default.
Structured outputs (fenced JSON) provide predictable error handling, version compatibility (via frontmatter), interface contracts, and composability. The formats below are normative for v0.5.
| Level | Required fields | Optional fields | Notes |
|---|---|---|---|
| Basic | success (bool), data (object|null), error (object|null) |
none | Use for single-step agents; omit extra metadata. |
| Standard | success, canceled (bool), aborted_by (string|null), data, error, metadata.duration_ms, metadata.tool_calls, metadata.retry_count |
metadata.correlation_id |
Use for multi-step or tool-heavy agents. |
| Advanced | Standard + metadata.timestamp, metadata.idempotency_key, metadata.max_tool_calls |
Additional per-domain metadata fields | Use only when consumers rely on enriched telemetry. |
success: true→ operation completed;errorMUST benull.success: false, canceled: false→ fatal error;errorMUST be populated.canceled: true→ deliberate abort (user/policy/timeout); setaborted_byto"user","policy", or"timeout".dataMAY benullon failure.
{
"code": "NAMESPACE.CODE",
"message": "Human-friendly summary",
"recoverable": false,
"suggested_action": "Next step for user/skill"
}Code namespace guidance:
- Use uppercase, dotted namespaces scoped to domain (e.g.,
EXECUTION.TIMEOUT,VALIDATION.INPUT,AUTH.CREDENTIALS). - For retries, set
recoverable: trueand include a concretesuggested_action.
Strategy: External registry validation (zero runtime tokens)
Agents declare version in YAML frontmatter only. Version checking happens outside agent execution via registry and tooling.
- Registry with skill constraints (source of truth)
# .claude/agents/registry.yaml
agents:
sc-worktree-create:
version: 1.0.0
path: .claude/agents/sc-worktree-create.md
sc-worktree-scan:
version: 1.0.0
path: .claude/agents/sc-worktree-scan.md
nuget-validation:
version: 1.2.0
path: .claude/agents/nuget-validation.md
skills:
sc-managing-worktrees:
depends_on:
sc-worktree-create: "1.x"
sc-worktree-scan: "1.x"
sc-worktree-cleanup: "1.x"Path format: Registry paths are relative to the project root (e.g., .claude/agents/sc-worktree-create.md).
Supported formats (v0.5):
- Exact version:
1.2.0 - Major range:
1.x(equivalent to>=1.0.0 <2.0.0)
Validation:
- CI script checks that referenced agents and skills exist in registry.
- Agent Runner resolves constraints at invocation time.
- Constraint mismatches fail fast before Task tool execution.
- Robust validation script (frontmatter-aware)
#!/usr/bin/env bash
# scripts/validate-agents.py
set -euo pipefail
REG=".claude/agents/registry.yaml"
frontmatter() {
awk 'f{print} /^---/{f=1;c++} c==2{exit}' "$1" | sed '1d'
}
fail=0
for agent in .claude/agents/*.md; do
name=$(basename "$agent" .md)
file_ver=$(frontmatter "$agent" | yq -r '.version' || echo "")
reg_ver=$(yq -r ".agents.\"$name\".version" "$REG" || echo "")
if [[ -z "$file_ver" || -z "$reg_ver" ]]; then
echo "ERROR: $name missing version (file='$file_ver' registry='$reg_ver')"
fail=1; continue
fi
if [[ "$file_ver" != "$reg_ver" ]]; then
echo "ERROR: $name version mismatch: file=$file_ver registry=$reg_ver"
fail=1
fi
done
[[ $fail -eq 0 ]] && echo "All agent versions validated"
exit $failSkill validation (extend script or add companion):
- Ensure every skill listed under
skillshas declareddepends_onentries that exist inagents. - Fail if a skill references an agent without a compatible version constraint.
- Optional: ensure every
SKILL.mdfrontmatter name matches its directory.
- Runtime attestation (optional, zero tokens)
Use an Agent Runner wrapper (CLI or tool) that:
- Resolves path and allowed version from registry.yaml
- Computes the agent file hash (e.g., SHA-256)
- Launches the Task tool with that path
- Writes a redacted audit record to
.claude/state/logs/ - Returns only the agent’s JSON to the skill
Audit record example:
{
"timestamp": "2025-11-29T23:58:00Z",
"agent": "sc-worktree-create",
"version_frontmatter": "1.0.0",
"file_sha256": "1f3a...c9",
"invoker": "agent-runner",
"outcome": "success",
"duration_ms": 3280
}Why: Ensures the invoked artifact matched policy at runtime without adding tokens to the agent’s prompt.
Implementation reference: See docs/agent-runner-comprehensive.md in this repository for a working Python implementation of the Agent Runner pattern.
canceled: trueindicates deliberate abort (user request, timeout, policy)- Populate
aborted_bywith:"user","timeout", or"policy" - Fatal errors use
success: false,canceled: falsewith error object
{
"success": false,
"canceled": false,
"data": null,
"error": {
"code": "AUTHENTICATION_FAILED",
"message": "NuGet API key is invalid or expired",
"recoverable": false,
"suggested_action": "Provide a valid API key via environment variable NUGET_API_KEY"
}
}Agents should support flag-style parameters for different execution modes.
Perform validation without executing actual changes.
Apply safe, bounded fixes automatically. Never bypass confirmations for destructive operations.
Do NOT auto-fix authentication failures, data loss scenarios, or security violations.
This section covers baseline security requirements. Complex scenarios (input sanitization, command injection prevention, sandboxing) are implementation-specific and outside the scope of this architecture document.
- Retrieve credentials from environment variables (e.g.,
NUGET_API_KEY) - Never hardcode or echo secrets
- Agents must not include secrets in JSON outputs
- Default to validation/dry-run mode
- Require explicit confirmation for publish, delete, or mutate operations
- Support
--validateand--auto-fixflags appropriately
- Restrict file operations to repository root unless explicitly allowed
- Fail closed on missing credentials
- Respect
max_tool_callsbudgets when specified; on breach, returncanceled: truewithaborted_by: "policy"
- Prefer Agent Runner to record a redacted audit record per invocation (timestamp, agent, frontmatter version, hash, outcome, duration)
- Enforce path allowlists rooted at repo; reject absolute paths outside workspace.
- Validate command arguments; do not pass unsanitized user input to shell commands.
- Maintain an env var allowlist; strip unneeded variables before invocation.
- Reject agents that attempt to run unknown binaries or edit outside declared scope.
This section covers architectural patterns for state. Complex scenarios (concurrency, locking, corruption recovery) are implementation-specific and outside the scope of this document.
- Skill-managed (simple): Single conversation, no resume needed
- File-based (durable):
.claude/state/for resume capability - Git-based (versioned): state tracked alongside code
- Cleanup: TTL-based expiration, explicit cleanup agent, or user command
Guardrails:
- PII and secrets must not be written to
.claude/state/; prefer ephemeral in-memory state. - Default TTL for temporary state: 24h; include
expires_atin state files when persisted. - Use deterministic filenames:
<skill>-<operation>-<correlation_id>.json. - For shared state, use file locks or atomic writes; avoid partial writes that can corrupt JSON.
- Document resume semantics in the skill so consumers know what can be safely retried.
.claude/
├── skills/
│ ├── sc-managing-worktrees/
│ │ ├── SKILL.md
│ │ └── workflows.md
│ └── publishing-nuget/
│ ├── SKILL.md
│ ├── registry-config.md
│ └── references/
│ └── installation-and-troubleshooting.md # Required for CLI-dependent skills
├── agents/
│ ├── registry.yaml # Version registry + skill constraints
│ ├── sc-worktree-create.md
│ ├── sc-worktree-scan.md
│ ├── nuget-publish.md
│ └── nuget-validation.md
├── state/ # Optional: for file-based state
│ └── .gitignore
└── scripts/
└── validate-agents.py # Version validation script
- Skills:
<verb-ing>-<noun>/e.g.,sc-managing-worktrees/ - Agents:
<noun>-<verb>.mde.g.,sc-worktree-create.md - State files:
<operation>-<identifier>.json
Rationale:
- Skills use gerunds to signal orchestrations (discovery surface).
- Agents use noun-verb to signal concrete actions (execution surface).
- Keep prefixes aligned (e.g.,
sc-) so filtering by namespace is predictable.
Any skill with CLI dependencies MUST ship a references/installation-and-troubleshooting.md. Normative content:
| Section | Content |
|---|---|
| Check First | which <cli> && <cli> --version; skip install if found |
| Find Existing Install | Full-path fallback search across common locations |
| Install | Platform-specific steps (macOS, Linux, Windows) |
| Minimum Version | Required version and upgrade path |
| PATH Troubleshooting | How to add install dir to PATH; Claude Code bash note |
| Validation | Command to confirm working install post-setup |
| Known Issues | Common gotchas (venv isolation, pip vs. pipx, Homebrew caveats) |
- Start with the Contract: Define inputs, outputs, error handling before implementing
- Version in Frontmatter: Every agent declares version in YAML frontmatter
- Fence All JSON: Always wrap JSON output in markdown code fences
- Use Minimal Envelope: Start with minimal response schema, add fields as needed
- Validate Externally: Use registry.yaml + CI for version validation
- Prefer Agent Runner: Enforce registry policy and capture audit logs; do not load arbitrary paths
- Single Responsibility: One agent, one task
- Document Error Boundaries: Clear separation of agent vs. skill error handling
- Parallel Guardrails: Cap concurrency, set timeouts, use correlation_ids
- Verify CLI Dependencies Early: Skills depending on external CLIs MUST check installation and PATH as Step 1, before any agent delegation. Direct to
references/installation-and-troubleshooting.mdon failure. Never proceed silently with a missing CLI.
- Monolithic Agents: Split into focused agents
- Leaky Abstractions: Don't return raw tool output; structure and interpret
- Unfenced JSON: Always wrap JSON in markdown code fences
- In-Agent Version Checks: Version validation belongs in external tooling
- Over-Communication: Keep agent output minimal and structured
- Agents Returning Markdown for Users: Agents return JSON; skills present to users
- Complex Branching: When an agent grows complex, split it
- Windows-Style Paths: Use forward slashes
- Silent CLI Dependency Failures: A skill that delegates to an agent when the required CLI is missing wastes agent context and produces an opaque error. Always gate on CLI presence in the skill before invocation — surface the gap and stop.
Document version: 0.7 Last updated: 2026-05-05
| Version | Date | Notes |
|---|---|---|
| 0.7 | 2026-05-05 | Added CLI Dependency Verification: normative Step 1 template, PATH fallback pattern, references/installation-and-troubleshooting.md spec, Best Practice #10, Anti-Pattern #9. |
| 0.6 | 2026-03-09 | Added Named Teammate Pattern section: persistent tmux teammate vs background agent distinction, SKILL.md guidance for named-teammate skills (no Agent Delegation section required), and relaxed Agent Template rules for messaging-based interaction model. |
| 0.5 | 2025-12-11 | Normalized versioning, tightened response contracts, added Agent Runner invocation contract, parallel aggregation policy, and safety/state guardrails. |
| 0.4 | 2025-11-01 | Prior baseline for two-tier skills/agents architecture. |