Agent Development Guide

This guide provides comprehensive instructions for creating cs- prefixed agents* that seamlessly integrate with the 346 production skills in this repository (count derived via scripts/derive_counters.py).

Agent Architecture

What are cs-* Agents?

cs- agents* are specialized Claude Code agents that orchestrate the repository's 346 skills. Each agent:

• References skills via relative paths (../marketing-skill/)
• Executes Python automation tools from skill packages
• Follows established workflows and templates
• Maintains skill portability and independence

Key Principle: Agents ORCHESTRATE skills, they don't replace them. Skills remain self-contained and portable.

ClawHub Publishing Constraints

When skills are published to ClawHub (clawhub.com):

• cs- prefix for slug conflicts only — applies only on the ClawHub registry when another publisher already owns the slug. Repo folder names and local skill names are never renamed.
• No paid/commercial service dependencies — skills must not require paid third-party API keys or commercial services unless provided by the project itself.
• plugin.json — ONLY fields: name, description, version, author, homepage, repository, license, skills: "./".
• Rate limit: 5 new skills/hour on ClawHub. Use drip publishing for bulk operations.

Production Agents

33 agents live in this folder (93 agent files repo-wide, including plugin-bundled agents). A representative selection:

Agent	Domain	Description
cs-content-creator	Marketing	AI-powered content creation with brand voice consistency and SEO optimization
cs-demand-gen-specialist	Marketing	Demand generation and customer acquisition specialist
cs-ceo-advisor	C-Level	Strategic leadership advisor for CEOs
cs-cto-advisor	C-Level	Technical leadership advisor for CTOs
cs-product-manager	Product	RICE prioritization and customer discovery
cs-product-strategist	Product	Product strategy, OKR cascades, market positioning
cs-agile-product-owner	Product	Agile product ownership and backlog management
cs-ux-researcher	Product	UX research, usability testing, design insights
cs-product-analyst	Product	Product analytics, KPI design, experiment design
cs-engineering-lead	Engineering	Engineering team coordination and incident management
cs-workspace-admin	Engineering	Google Workspace administration via gws CLI
cs-senior-engineer	Engineering	Architecture decisions, code review, CI/CD setup
cs-fullstack-engineer	Engineering	Fullstack orchestrator (v2.8.1): walks 7 Matt Pocock forcing questions, picks profile via deterministic engine, forks (context: fork) into api-design-reviewer / database-designer / slo-architect / ci-cd-pipeline-builder. Invokable via /cs:fullstack-review or Agent({subagent_type:"cs-fullstack-engineer"}).
cs-frontend-engineer	Engineering	Frontend orchestrator (v2.8.1): walks 7 forcing questions (device, LCP target, rendering, bundle, SEO, design system, WCAG), picks framework profile, forks into a11y-audit / performance-profiler / epic-design / apple-hig-expert. Invokable via /cs:frontend-review.
cs-backend-engineer	Engineering	Backend orchestrator (v2.8.1): walks 7 forcing questions (read/write + QPS, tenancy, sync vs async, sensitivity, pattern, RPO/RTO, SLO), picks language + pattern profile, forks into api-design-reviewer / database-designer / migration-architect / slo-architect / observability-designer. Invokable via /cs:backend-review.
cs-growth-strategist	Business	Growth strategy and revenue optimization
cs-financial-analyst	Finance	Financial analysis, DCF valuation, SaaS metrics
cs-project-manager	PM	Project management with Atlassian integration
cs-quality-regulatory	RA/QM	Regulatory affairs and quality management

Template Available: templates/agent-template.md (318 lines) - Use this to create new agents

Agent vs Skill

Aspect	Agent (cs-*)	Skill
Purpose	Orchestrate and execute workflows	Provide tools, knowledge, templates
Location	agents/domain/	domain-skill/skill-name/
Structure	Single .md file with YAML frontmatter	SKILL.md + scripts/ + references/ + assets/
Integration	References skills via ../../	Self-contained, no dependencies
Naming	cs-content-creator, cs-ceo-advisor	content-creator, ceo-advisor

Agent File Structure

Required YAML Frontmatter

Every agent file must start with valid YAML frontmatter:

---
name: cs-agent-name
description: One-line description of what this agent does
skills: skill-folder-name
domain: domain-name
model: sonnet
tools: [Read, Write, Bash, Grep, Glob]
---

Field Definitions:

• name: Agent identifier with cs- prefix (e.g., cs-content-creator)
• description: Single sentence describing agent's purpose
• skills: Skill folder this agent references (e.g., marketing-skill/content-creator)
• domain: Domain category (marketing, product, engineering, c-level, pm, ra-qm)
• model: Claude model to use (sonnet, opus, haiku)
• tools: Array of Claude Code tools agent can use

Required Markdown Sections

After YAML frontmatter, include these sections:

1. Purpose (2-3 paragraphs)
2. Skill Integration (with subsections)
   • Skill Location
   • Python Tools
   • Knowledge Bases
   • Templates
3. Workflows (minimum 3 workflows)
4. Integration Examples (concrete code/command examples)
5. Success Metrics (how to measure effectiveness)
6. Related Agents (cross-references)
7. References (links to documentation)

Relative Path Resolution

Path Pattern

All skill references use the ../../ pattern:

**Skill Location:** `../marketing-skill/skills/content-creator/`

### Python Tools

1. **Brand Voice Analyzer**
   - **Path:** `../marketing-skill/skills/content-production/scripts/brand_voice_analyzer.py`
   - **Usage:** `python ../marketing-skill/skills/content-production/scripts/brand_voice_analyzer.py content.txt`

2. **SEO Optimizer**
   - **Path:** `../marketing-skill/skills/content-production/scripts/seo_optimizer.py`
   - **Usage:** `python ../marketing-skill/skills/content-production/scripts/seo_optimizer.py article.md "keyword"`

Why ../../?

From agent location: agents/marketing/cs-content-creator.md To skill location: marketing-skill/content-creator/

Navigation: agents/marketing/ → ../../ (up to root) → marketing-skill/content-creator/

Always test paths resolve correctly!

Python Tool Integration

Execution Pattern

Agents execute Python tools from skill packages:

# From agent context
python ../marketing-skill/skills/content-production/scripts/brand_voice_analyzer.py input.txt

# With JSON output
python ../marketing-skill/skills/content-production/scripts/brand_voice_analyzer.py input.txt json

# With arguments
python ../product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py features.csv --capacity 20

Tool Requirements

All Python tools must:

• Use standard library only (or minimal dependencies documented in SKILL.md)
• Support both JSON and human-readable output
• Provide --help flag with usage information
• Return appropriate exit codes (0 = success, 1 = error)
• Handle missing arguments gracefully

Error Handling

When Python tools fail:

1. Check file path resolution
2. Verify input file exists
3. Check Python version compatibility (3.8+)
4. Review tool's --help output
5. Inspect error messages in stderr

Workflow Documentation

Workflow Structure

Each workflow must include:

### Workflow 1: [Clear Descriptive Name]

**Goal:** One-sentence description

**Steps:**
1. **[Action]** - Description with specific commands/tools
2. **[Action]** - Description with specific commands/tools
3. **[Action]** - Description with specific commands/tools

**Expected Output:** What success looks like

**Time Estimate:** How long this workflow takes

**Example:**
\`\`\`bash
# Concrete example command
python ../marketing-skill/skills/content-production/scripts/seo_optimizer.py article.md "primary keyword"
\`\`\`

Minimum Requirements

Each agent must document at least 3 workflows covering:

1. Primary use case (most common scenario)
2. Advanced use case (complex scenario)
3. Integration use case (combining multiple tools)

Agent Template

Use this template when creating new agents:

---
name: cs-agent-name
description: One-line description
skills: skill-folder-name
domain: domain-name
model: sonnet
tools: [Read, Write, Bash, Grep, Glob]
---

# Agent Name

## Purpose

[2-3 paragraphs describing what this agent does, why it exists, and who it serves]

## Skill Integration

**Skill Location:** \`../../domain-skill/skill-name/\`

### Python Tools

1. **Tool Name**
   - **Purpose:** What it does
   - **Path:** \`../../domain-skill/skill-name/scripts/tool.py\`
   - **Usage:** \`python ../../domain-skill/skill-name/scripts/tool.py [args]\`

### Knowledge Bases

1. **Reference Name**
   - **Location:** \`../../domain-skill/skill-name/references/file.md\`
   - **Content:** What's inside

### Templates

1. **Template Name**
   - **Location:** \`../../domain-skill/skill-name/assets/template.md\`
   - **Use Case:** When to use

## Workflows

### Workflow 1: [Name]

**Goal:** Description

**Steps:**
1. Step 1
2. Step 2
3. Step 3

**Expected Output:** Success criteria

**Example:**
\`\`\`bash
python ../../domain-skill/skill-name/scripts/tool.py input.txt
\`\`\`

### Workflow 2: [Name]
[Same structure]

### Workflow 3: [Name]
[Same structure]

## Integration Examples

[Concrete examples with actual commands and expected outputs]

## Success Metrics

- Metric 1: How to measure
- Metric 2: How to measure
- Metric 3: How to measure

## Related Agents

- [cs-related-agent](../<domain>/cs-related-agent.md) - How they relate

## References

- [Skill Documentation](../../domain-skill/skill-name/SKILL.md)
- [Domain Roadmap](../../<domain-skill>/roadmap.md)

Quality Standards

Agent Quality Checklist

Before committing an agent:

• YAML frontmatter valid (no parsing errors)
• All required fields present (name, description, skills, domain, model, tools)
• cs-* prefix used for agent naming
• Relative paths resolve correctly (../../ pattern)
• Skill location documented and accessible
• Python tools referenced with correct paths
• At least 3 workflows documented
• Integration examples provided and tested
• Success metrics defined
• Related agents cross-referenced

Testing Agent Integration

Test these aspects:

1. Path Resolution

# From agent directory
cd agents/marketing/
ls ../marketing-skill/skills/content-creator/  # Should list contents

2. Python Tool Execution

# Create test input
echo "Test content" > test-input.txt

# Execute tool
python ../marketing-skill/skills/content-production/scripts/brand_voice_analyzer.py test-input.txt

# Verify output

3. Knowledge Base Access

# Verify reference files exist
cat ../marketing-skill/skills/content-creator/references/brand_guidelines.md

Domain-Specific Guidelines

Marketing Agents (agents/marketing/)

• Focus on content creation, SEO, demand generation
• Reference: ../marketing-skill/
• Tools: brand_voice_analyzer.py, seo_optimizer.py

Product Agents (agents/product/)

• Focus on prioritization, user research, agile workflows
• Reference: ../product-team/
• Tools: rice_prioritizer.py, user_story_generator.py, okr_cascade_generator.py

C-Level Agents (agents/c-level/)

• Focus on strategic decision-making
• Reference: ../c-level-advisor/
• Tools: Strategic analysis and planning tools

Engineering Agents (agents/engineering/)

• Focus on scaffolding, code quality, fullstack development
• Reference: engineering-team/
• Tools: project_scaffolder.py, code_quality_analyzer.py

Common Pitfalls

Avoid these mistakes:

❌ Hardcoding absolute paths ❌ Skipping YAML frontmatter validation ❌ Forgetting to test relative paths ❌ Documenting workflows without examples ❌ Creating agent dependencies (keep them independent) ❌ Duplicating skill content in agent files ❌ Using LLM calls instead of referencing Python tools

Next Steps

After creating an agent:

1. Test all relative paths resolve
2. Execute all Python tools from agent context
3. Verify all workflows with concrete examples
4. Update agent catalog in main README.md
5. Create GitHub issue for agent testing
6. Commit with conventional commit message: feat(agents): implement cs-agent-name

---

Last Updated: June 10, 2026 Current: 33 agents in this folder across 10 domain subfolders (93 agent files repo-wide) Related: See main CLAUDE.md for repository overview