UDS Agents

UDS Agents

Language: English | 繁體中文

Version: 1.1.0 Last Updated: 2026-01-21 Status: Stable

---

Overview

UDS Agents are specialized AI subagents that can be orchestrated to handle complex development workflows. Unlike Skills (which provide context/knowledge), Agents are autonomous entities that can execute multi-step tasks.

AGENT.md Format Specification

Frontmatter Schema

---
# === REQUIRED FIELDS ===
name: agent-name              # Unique identifier (kebab-case)
version: 1.0.0                # Semantic version
description: |                # Multi-line description for AI matching
  Brief description of the agent's purpose.
  Keywords: keyword1, keyword2, keyword3.

# === ROLE CONFIGURATION ===
role: specialist              # orchestrator | specialist | reviewer
expertise:                    # Domain expertise areas
  - system-design
  - api-design
  - database-modeling

# === TOOL PERMISSIONS (Claude Code Task tool) ===
# Specify which tools this agent can use
allowed-tools:
  - Read                      # File reading
  - Glob                      # Pattern matching
  - Grep                      # Content search
  - Bash(git:*)               # Git commands only
  - WebFetch                  # Web fetching
  - WebSearch                 # Web search
disallowed-tools:             # Explicitly blocked tools
  - Write                     # No file writing
  - Edit                      # No file editing

# === SKILL DEPENDENCIES ===
# Skills that provide context/knowledge to this agent
skills:
  - spec-driven-dev           # Skill name reference
  - testing-guide

# === MODEL PREFERENCES (Claude Code only) ===
model: claude-sonnet-4-20250514  # Preferred model
temperature: 0.3              # Response creativity (0.0-1.0)

# === CONTEXT STRATEGY (RLM-inspired) ===
# Configuration for handling large codebases and long contexts
context-strategy:
  mode: adaptive              # full | chunked | adaptive
  max-chunk-size: 50000       # Maximum tokens per chunk
  overlap: 500                # Token overlap between chunks
  analysis-pattern: hierarchical  # hierarchical | parallel | sequential

# === TRIGGER CONDITIONS ===
triggers:
  keywords:                   # Auto-activate on these keywords
    - architecture
    - system design
    - 架構設計
  commands:                   # Slash commands that invoke this agent
    - /architect
---

Role Types

Role	Description	Use Case
orchestrator	Coordinates multiple agents	Complex workflows, feature development
specialist	Deep expertise in specific domain	Architecture, testing, documentation
reviewer	Evaluates and provides feedback	Code review, spec review, PR review

Tool Permission Patterns

# Full tool access (default if not specified)
allowed-tools: [*]

# Read-only agent
allowed-tools: [Read, Glob, Grep]
disallowed-tools: [Write, Edit, Bash]

# Git-only bash access
allowed-tools:
  - Bash(git:*)     # Only git commands
  - Bash(npm:test)  # Only npm test

# Specific file patterns
allowed-tools:
  - Write(*.md)     # Only markdown files
  - Edit(src/**)    # Only src directory

Context Strategy Configuration (RLM-inspired)

The context-strategy section enables intelligent handling of large codebases and long contexts using RLM (Recursive Language Model) principles.

Mode Options

Mode	Description	Use Case
full	Load complete context at once	Small projects, documentation tasks
chunked	Divide context into fixed-size chunks	Sequential code review, large file analysis
adaptive	Dynamically adjust based on content structure	Complex analysis, architecture exploration

Analysis Patterns

Pattern	Description	Best For
hierarchical	Analyze high-level structure first, then drill down	Architecture analysis, system design
parallel	Process multiple sections simultaneously	Independent module analysis, spec review
sequential	Process sections in order, preserving context	Code review, step-by-step analysis

Configuration Examples

# For architecture analysis (need overview first)
context-strategy:
  mode: adaptive
  max-chunk-size: 50000
  overlap: 500
  analysis-pattern: hierarchical

# For code review (sequential processing)
context-strategy:
  mode: chunked
  max-chunk-size: 30000
  overlap: 200
  analysis-pattern: sequential

# For documentation (need full context)
context-strategy:
  mode: full
  analysis-pattern: hierarchical

Agent Signatures (v1.2.0, DSPy-inspired)

The optional signatures field defines structured input/output contracts for agent operations. This enables validation of agent outputs and clearer composition in workflows.

---
name: spec-analyst
# ... other fields ...

signatures:
  forward-analysis:
    description: Transform requirements into a specification document
    inputs:
      - name: feature_request
        type: text
        required: true
        description: User's feature request or requirement description
      - name: codebase_context
        type: file_list
        required: false
        description: Relevant source files for context
    outputs:
      - name: spec_document
        type: markdown
        validation: "Contains Summary, Motivation, Acceptance Criteria sections"
      - name: read_first_list
        type: yaml_list
        validation: "Each entry has path and reason fields"

  reverse-analysis:
    description: Extract specification from existing code
    inputs:
      - name: source_files
        type: file_list
        required: true
    outputs:
      - name: reverse_spec
        type: markdown
        validation: "Contains Discovered Behaviors, Business Rules, Gaps sections"
      - name: certainty_report
        type: table
        validation: "Each item tagged [Confirmed], [Inferred], [Assumption], or [Unknown]"
---

Signature Fields

Field	Type	Description
inputs[].name	string	Input parameter name
inputs[].type	string	text, markdown, file_list, yaml_list, json
inputs[].required	boolean	Whether this input is mandatory
outputs[].name	string	Output artifact name
outputs[].type	string	Output format type
outputs[].validation	string	Human-readable validation criteria

Benefits

• Composability: Workflows can validate that step outputs match next step's expected inputs
• Documentation: Signatures serve as API contracts for agent capabilities
• Validation: Output validation criteria enable deterministic quality checks

---

Cross-Tool Execution Modes

AI Tool	Execution Mode	How It Works
Claude Code	task	Uses Task tool to spawn independent subagent
OpenCode	task	Similar Task tool support
Cursor / Windsurf	inline	Injects AGENT.md as context prefix
Copilot / Gemini	inline	Converts to prompt snippets

Built-in Agents

Agent	Role	Description
code-architect	specialist	Software architecture and system design
test-specialist	specialist	Testing strategy and test implementation
reviewer	reviewer	Code review and quality assessment
doc-writer	specialist	Documentation and technical writing
spec-analyst	specialist	Specification analysis and requirement extraction

Usage

CLI Installation

# List available agents
uds agent list

# Install specific agent to project
uds agent install code-architect

# Install all agents
uds agent install --all

# Install to user directory (global)
uds agent install code-architect --global

Direct Invocation in Claude Code

/architect [task description]

Or through natural language triggers:

Please help me design the architecture for a new authentication system.

Creating Custom Agents

1. Create AGENT.md File

# In your project
mkdir -p .claude/agents
touch .claude/agents/my-agent.md

2. Define Frontmatter

---
name: my-custom-agent
version: 1.0.0
description: |
  Custom agent for specific project needs.
  Keywords: custom, specific, project.

role: specialist
expertise: [domain-specific]

allowed-tools: [Read, Glob, Grep, Edit]
skills: [relevant-skill]

triggers:
  commands: [/myagent]
---

3. Write Agent Instructions

# My Custom Agent

## Purpose

Describe what this agent does.

## Workflow

1. Step one
2. Step two
3. Step three

## Guidelines

- Guideline 1
- Guideline 2

Agent vs Skill Comparison

Aspect	Skill	Agent
Purpose	Provide knowledge/context	Execute autonomous tasks
Execution	Loaded as context	Spawned as subagent (or inline)
State	Stateless	Can maintain task state
Tool Access	None (context only)	Configurable permissions
Triggers	Manual loading	Keywords, commands, workflows
Composition	Referenced by agents	Can use skills as context

Integration with Workflows

Agents can be orchestrated through workflow definitions:

# workflows/feature-dev.workflow.yaml
name: feature-development
steps:
  - agent: spec-analyst
    task: Analyze requirements
  - agent: code-architect
    task: Design solution
  - agent: test-specialist
    task: Define test strategy
  - manual: Implementation
  - agent: reviewer
    task: Code review

See workflows/README.md for workflow documentation.

---

Related Resources

• Skills Documentation
• Workflows Documentation
• AI Agent Paths Configuration

---

Version History

Version	Date	Changes
1.2.0	2026-03-17	Added agent signatures (DSPy-inspired structured I/O contracts)
1.1.0	2026-01-21	Added RLM-inspired context-strategy configuration
1.0.0	2026-01-20	Initial release

---

License

This documentation is released under CC BY 4.0.

Source: universal-dev-standards