Agent-Skills.md

Agent Skills: Architecting Agents Protocol

Provides industry-proven design patterns for effective AI agents based on production systems like Claude Code, Manus, and Cursor. Use when designing agent architectures, optimizing context management, or implementing sub-agent patterns.

UncategorizedID: Git-Fg/thecattoolkit/architecting-agents

Repository

Git-Fg/thecattoolkit
Git-FgLicense: MIT
1

Install this agent skill to your local

pnpm dlx add-skill https://github.com/Git-Fg/thecattoolkit/tree/HEAD/plugins/sys-agents/skills/architecting-agents

Skill Files

Browse the full folder contents for architecting-agents.

Download Skill

Loading file tree…

plugins/sys-agents/skills/architecting-agents/SKILL.md

Skill Metadata

Name
architecting-agents
Description
"Provides industry-proven design patterns for effective AI agents based on production systems like Claude Code, Manus, and Cursor. Use when designing agent architectures, optimizing context management, or implementing sub-agent patterns."

Architecting Agents Protocol

Architecting Agents Protocol

Provides design patterns for agent context management.

Cost Warning (CRITICAL)

Before using sub-agents, understand the costs:

| Approach | When to Use | |:---------|:------------| | Inline | Most tasks | | Fork | Isolation needed | | Subagent | Parallelization only (High Cost) |

Default Recommendation: Use context: fork in skills for isolation. Subagents are ONLY appropriate when parallelization benefit clearly exceeds 20K token startup cost AND quota overhead.

See references/subagent-risks.md for detailed evidence.

Pattern Index

| Pattern | Purpose | When to Use | |:--------|:--------|:------------| | Computer Access | Persistent context via filesystem | Agent needs state persistence | | Multi-Layer Actions | Hierarchical tool design | Reducing tool definition overhead | | Progressive Disclosure | Reveal actions on demand | Managing large action spaces | | Context Offloading | Filesystem storage for context | Context window pressure | | Context Caching | Prompt caching strategies | Cost/latency optimization | | Context Isolation | Sub-agent separation | Long-running or parallel tasks | | Context Evolution | Continual learning | Building agent memories |

1. Computer Access

Components:

  • Filesystem: Persistent context storage, state across sessions
  • Shell: Execute utilities, CLIs, scripts, or generated code

Implementation:

Agent → Bash Tool → Shell Utilities / CLIs / Scripts
Agent → File Tools → Read / Write / Edit filesystem

2. Multi-Layer Action Space

Action Hierarchy:

Level 1: Tool Calling (agent-visible)
  ↓
Level 2: Shell Utilities / CLIs (computer-level)
  ↓
Level 3: Code Execution (generated scripts)

3. Progressive Disclosure

Strategies:

| Layer | Approach | |:------|:---------| | Tool Calling | Index definitions, retrieve on demand | | Shell Utilities | List available utilities in instructions; use --help when needed | | MCP Servers | Sync descriptions to folder; read full spec only if task requires | | Skills | YAML frontmatter indexed; full SKILL.md read on demand |

Implementation Pattern:

1. Provide short list of available capabilities
2. Agent reads detailed spec only when task matches
3. Execute with full knowledge loaded just-in-time

4. Context Offloading

Approaches:

  • Write old tool results to files
  • Store agent trajectories for later retrieval
  • Apply summarization only after offloading diminishing returns

Plan File Pattern: Write plan to file → Read periodically to reinforce objectives → Verify work against plan

5. Context Caching

Caching Requirements:

  • Stable prefix (system prompt unchanged)
  • Append-only message history
  • Deterministic serialization (sorted JSON keys)

Anti-Pattern: Mutating history in ways that break cache prefix

6. Context Isolation

Default Approach: Use context: fork

---
name: processing-batch
description: "Processes multiple files in isolated context"
context: fork
allowed-tools: [Read, Write, Bash]
---

Cost: ~3x inline, but FREE as tool call within prompt quota. Use for: Heavy operations (>10 files), parallel processing, isolation needs.

Subagent Alternatives (Use Sparingly)

ONLY when parallelization benefit > 20K token startup cost:

| Scenario | Pattern | Recommendation | |:---------|:--------|:---------------| | Parallelizable tasks | Map-reduce | Use fork unless >50 parallel units | | Long-running tasks | Ralph Loop | Use fork with persistent files | | Independent checks | Parallel reviewers | Use fork for cost efficiency |

The Ralph Loop:

1. Initializer sets up environment (plan file, tracking file)
2. Sub-agents tackle individual tasks from plan
3. Progress communicated via git history
4. Stop hooks verify work after each iteration
5. Repeat until plan satisfied

Benefits:

  • Prevents single-agent context saturation
  • Enables parallel execution
  • Clear isolation boundaries

7. Context Evolution

Evolution Patterns:

| Type | Approach | |:-----|:---------| | Task-specific prompts | Collect trajectories → Score → Reflect on failures → Propose variants | | Memory learning | Distill sessions into diary entries → Reflect → Update instructions | | Skill learning | Reflect over trajectories → Distill reusable procedures → Save as new skills |

Implementation:

Session Log → Reflection → Memory/Skill Update → Context

Quick Reference

For detailed implementations, see:

Related Skills:

  • agent-orchestration - Multi-agent patterns (Orchestrator, Swarm, Hierarchical)
  • context-engineering - Compression, degradation, KV-cache optimization
  • memory-systems - Long-term memory architectures