From ucai
Provides best practices for Claude Code: context management via hooks and skills, agent patterns for parallel spawning and tool restriction, plus red flags for anti-patterns.
How this skill is triggered — by the user, by Claude, or both
Slash command
/ucai:ucai-patternsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Best practices for working with Claude Code's native architecture. These patterns are derived from how Anthropic builds their own plugins.
Best practices for working with Claude Code's native architecture. These patterns are derived from how Anthropic builds their own plugins.
The context window is a shared resource. Protect it.
Native tools for context:
tasks/todo.md so hooks can inject state and context compaction doesn't lose your placeAnti-patterns:
For detailed patterns, see: references/context-management.md
Red Flags — Context Management
Pathological Honesty applies to every Red Flags table in this skill: the "Reality" column states what's wrong with the thought. When you catch yourself in one of these thoughts, name a concrete failure mode you've already seen or can see — a real session that overflowed, a real agent that hung, a real CLAUDE.md that drifted. Abstract realism doesn't change behavior; concrete failure modes do.
| Thought | Reality |
|---|---|
| "CLAUDE.md is the right place for this framework pattern" | CLAUDE.md is for project facts only. Framework conventions belong in skills. |
| "I'll load all context upfront to be safe" | Upfront loading burns context before it's needed. Load on demand. |
| "The context window is large enough" | Large ≠ infinite. Shared resource. Protect it. |
Agents are focused workers, not personas.
Native agent format: Markdown files with YAML frontmatter declaring name, description, tools, model, and color. Each agent has a specific mission.
Key patterns:
For detailed patterns, see: references/agent-patterns.md
Red Flags — Agent Patterns
| Thought | Reality |
|---|---|
| "I'll spawn agents one at a time for clarity" | Serial spawning wastes 2-3 seconds per round-trip. Batch in one message. |
| "This agent needs all tools available" | Restrict tools to what the agent actually needs. Scope matters. |
| "I'll have one agent do everything" | Focused agents outperform generalist agents on complex tasks. |
The golden rule: 1 message = ALL related operations. Every round-trip to Claude adds latency. Batch everything that can go together.
Good patterns:
tasks/todo.md updates in a single Write call, not one per itemAnti-patterns:
tasks/todo.md once per todo item across separate turnsWhy it matters: In a 5-agent parallel analysis, serial spawning adds 4 unnecessary round-trips. At 2-3 seconds per round-trip, that is 8-12 seconds of pure latency before any work begins. Batching collapses this to a single round-trip.
For detailed patterns, see: references/agent-patterns.md
Red Flags — Batch Operations
| Thought | Reality |
|---|---|
| "I'll read this file, then decide what to read next" | Speculatively read everything potentially useful in one message. |
| "I'll update todos one at a time as I finish each" | Batch all tasks/todo.md updates in a single Write call. |
| "Let me spawn this agent first, then spawn the next" | All parallel agents go in one message. Always. |
| "Sequential is safer" | Sequential adds latency with zero safety benefit for independent tasks. |
Gate — before spawning any agent:
Am I about to launch this agent alone, wait for it, then spawn the next?
→ Yes → STOP. Bundle all agents into one message first.
→ No → Proceed.
Gate — before any file read:
Do I know other files I'll need in this session?
→ Yes → Read all of them now in this same message.
→ No → Proceed with current read.
Hooks are lifecycle event handlers. They are the primary extension point.
Hook events: SessionStart, PreToolUse, PostToolUse, PostToolUseFailure, Stop, UserPromptSubmit, SubagentStop, SubagentStart, PreCompact, SessionEnd, PermissionRequest
Key patterns:
For detailed patterns, see: references/hook-patterns.md
Red Flags — Hook Patterns
| Thought | Reality |
|---|---|
| "The hook will handle this automatically" | Hooks run on lifecycle events. Read the handler to confirm scope. |
| "Exit code 2 might be too aggressive" | Exit code 2 is the designed block mechanism. Use it when blocking is correct. |
| "I'll skip the Stop hook iteration check" | The iterate loop depends on the Stop hook. Skipping breaks the loop. |
Named mistakes to avoid. Each has a symptom and a fix.
For the full catalogue, see: references/anti-patterns.md
Red Flags — Anti-Patterns
| Thought | Reality |
|---|---|
| "This agent needs Write + Edit for safety" | Read-only agents can't accidentally break things. Restrict tools. |
| "I'll use console.log to debug my hook" | console.log corrupts hook JSON output. Use console.error for debug. |
| "The command will implement this directly" | Commands coordinate. Agents execute. Keep the separation. |
| "I'll build the path with string concatenation" | Use path.resolve() or path.join(). String concat breaks on Windows. |
For skill and command authoring principles (persuasion techniques, gate functions, enforcement language), see: references/skill-design-principles.md
npx claudepluginhub joncik91/ucai --plugin ucaiKnowledge base on Claude Code formats, patterns, and configurations for commands, agents, skills, hooks, memory, plugins, settings. Use for creating, improving, auditing components.
Designs Claude Code agents using patterns like single-purpose specialists, workflow orchestrators, context adapters, and resource processors; guides tool selection, model choice, and extended context integration.
Provides Claude Code templates for agentic design patterns like prompt chaining, routing, reflection, tool use, planning, and multi-agent workflows using 4-layer stack. For LLM task decomposition.