Skip to content
CLAUDE · claude-skills · Flowy
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`).
One agent from claude-skills .
$ npx -y skills add alirezarezvani/claude-skills --agent claude-codeShips with claude-skills. Installing the plugin gets this agent.
⚡ How it fires
How this agent gets triggered: by you, by Claude, or both.
Fires itself Claude auto-loads it when your prompt matches the work. You can call it Invoke it directly when you want it. 👁️ Context preview
The summary Claude sees to decide when to auto-load this agent.
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`). 📦 Ships with claude-skills
</> Agent definition
CLAUDE.md
# 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:
Flowy AI Flows that just work. Hand-picked Claude Code plugins that fire the right skill as you prompt.
| Agent | Domain | Description |
|-------|--------|-------------|
| [cs-content-creator](marketing/cs-content-creator.md) | Marketing | AI-powered content creation with brand voice consistency and SEO optimization |
| [cs-demand-gen-specialist](marketing/cs-demand-gen-specialist.md) | Marketing | Demand generation and customer acquisition specialist |
| [cs-ceo-advisor](c-level/cs-ceo-advisor.md) | C-Level | Strategic leadership advisor for CEOs |
| [cs-cto-advisor](c-level/cs-cto-advisor.md) | C-Level | Technical leadership advisor for CTOs |
| [cs-product-manager](product/cs-product-manager.md) | Product | RICE prioritization and customer discovery |
| [cs-product-strategist](product/cs-product-strategist.md) | Product | Product strategy, OKR cascades, market positioning |
| [cs-agile-product-owner](product/cs-agile-product-owner.md) | Product | Agile product ownership and backlog management |
| [cs-ux-researcher](product/cs-ux-researcher.md) | Product | UX research, usability testing, design insights |
| [cs-product-analyst](product/cs-product-analyst.md) | Product | Product analytics, KPI design, experiment design |
| [cs-engineering-lead](engineering-team/cs-engineering-lead.md) | Engineering | Engineering team coordination and incident management |
| [cs-workspace-admin](engineering-team/cs-workspace-admin.md) | Engineering | Google Workspace administration via gws CLI |
| [cs-senior-engineer](engineering/cs-senior-engineer.md) | Engineering | Architecture decisions, code review, CI/CD setup |
| [cs-fullstack-engineer](engineering/cs-fullstack-engineer.md) | 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/cs-frontend-engineer.md) | 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/cs-backend-engineer.md) | 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/cs-growth-strategist.md) | Business | Growth strategy and revenue optimization |
| [cs-financial-analyst](finance/cs-financial-analyst.md) | Finance | Financial analysis, DCF valuation, SaaS metrics |
| [cs-project-manager](project-management/cs-project-manager.md) | PM | Project management with Atlassian integration |
| [cs-quality-regulatory](ra-qm-team/cs-quality-regulatory.md) | RA/QM | Regulatory affairs and quality management |
**Template Available**: [templates/agent-template.md](../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:
```yaml
---
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:
```markdown
**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:
```bash
# 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:
```markdown
### 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:
```markdown
---
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**
```bash
# From agent directory
cd agents/marketing/
ls ../marketing-skill/skills/content-creator/ # Should list contents
```
**2. Python Tool Execution**
```bash
# 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**
```bash
# 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](../CLAUDE.md) for repository overview
© 2026 Flowy · Free and open source
Built for Claude Code · Not affiliated with Anthropic
