# Agents

## 1. Purpose

This directory stores finalized or near-final Agent artifacts.

Agents are reusable AI work roles.

Some are lightweight Prompt Cards.

Some are durable Agent Specs.

Some are committees or multi-agent systems.

## 2. Directory Structure

Recommended subdirectories:

```text
agents/
├── lite/
├── agent-specs/
└── committees/
```

## 3. Subdirectory Usage

### 3.1 lite/

Use for portable prompt cards.

These are suitable for:

```text
Custom GPT
Gemini Gem
Claude Project instructions
Simple expert assistant prompts
Manual chat use
```

Examples:

```text
zhangliao-red-team.prompt.md
cognitive-imaging-specialist.prompt.md
socratic-questioner.prompt.md
```

### 3.2 agent-specs/

Use for durable Agent Specs.

These are suitable for:

```text
Codex
Claude Code
OpenClaw
Multi-agent workflows
Long-term reusable work roles
Agents that call Skills
Agents with authority and evaluation rules
```

Examples:

```text
cognitive-imaging-specialist.agent.md
knowledge-archivist.agent.md
review-committee-chair.agent.md
```

### 3.3 committees/

Use for groups of agents defined together.

This folder may include:

```text
Committee descriptions
Member lists
Role differentiation maps
Committee-level prompts
Links to Runtime Specs
```

Examples:

```text
modeling-committee.md
review-committee.md
writing-committee.md
```

The actual workflow should usually live in:

```text
runtimes/
```

## 4. Agent vs Prompt Card

Use `lite/` when the artifact is:

```text
Portable
Single-role
Directly human-facing
Easy to paste into chat tools
Not tool-heavy
Not state-heavy
```

Use `agent-specs/` when the artifact is:

```text
Durable
Reusable
Workflow-ready
Skill-calling
Authority-aware
Evaluation-aware
```

## 5. Agent vs Skill

An Agent has a role and responsibility.

A Skill is a reusable capability.

If an Agent contains a repeatable method that other Agents can use, consider extracting that method into:

```text
skills/
```

## 6. Agent vs Model Card

An Agent may use a cognitive model.

The model itself should live in:

```text
model-cards/
```

when it is reusable or intellectually important.

Example:

```text
cognitive-imaging-specialist.agent.md
uses:
model-cards/intermediate/cognitive-imaging-model.md
skills/cognitive/cognitive-imaging.skill.md
```

## 7. Naming Convention

Use lowercase kebab-case.

Recommended patterns:

```text
{name}.prompt.md
{name}.agent.md
{name}-committee.md
```

Examples:

```text
zhangliao-red-team.prompt.md
cognitive-imaging-specialist.agent.md
modeling-committee.md
```

## 8. Agent Metadata

Recommended front matter:

```yaml
---
artifact_type:
name:
agent_id:
author:
version:
created:
updated:
status:
target_platform:
related_models:
related_skills:
related_runtimes:
based_on: CCPE System
---
```

## 9. Status Values

Use:

```text
draft
experimental
active
deprecated
archived
```

## 10. Final Rule

Agents are not just personalities.

A good Agent has a role, objective, boundary, workflow, output standard, and relationship to models and skills.