usap-skills / agents
CLAUDE.md4 starsChanged 2 months agoApache-2.0View on GitHub
This guide provides instructions for creating *cs- prefixed agents** that orchestrate the USAP skill packages. How agents hand work to each other (the payload as envelope, next_agents, the hold on human_approval_required, the four USAP chains) is specified in ../ORCHESTRATION.md. Workflows you write must fit one of the chains or patterns defined there. *cs- agents** are specialized orchestrators that combine multiple USAP skills into coherent, role-specific workflows. Each agent: - References skills via relative paths (../../<slug>/) - Executes Python automation tools…
In this repository100 other files it gives its agents.
- appsec-devsecops/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- cloud-infra/CLAUDE.mdCLAUDE.md
- detection/CLAUDE.mdCLAUDE.md
- governance/CLAUDE.mdCLAUDE.md
- identity-access/CLAUDE.mdCLAUDE.md
- pentest/CLAUDE.mdCLAUDE.md
- platform-ai/CLAUDE.mdCLAUDE.md
- red-team/CLAUDE.mdCLAUDE.md
- response/CLAUDE.mdCLAUDE.md
- risk-compliance/CLAUDE.mdCLAUDE.md
- system-security/CLAUDE.mdCLAUDE.md
- webapp-security/CLAUDE.mdCLAUDE.md
- agent-integrity-monitorSkill
- ai-agent-securitySkill
- ai-ethics-governanceSkill
- ai-red-teamingSkill
- api-security-postureSkill
- appsec-code-reviewSkill
- appsec-customizeSkill
- attack-path-analysisSkill
- attack-surface-managementSkill
- behavioral-analyticsSkill
- build-integritySkill
- ciso-brief-generatorSkill
- cloud-security-postureSkill
- cloud-workload-protectionSkill
- compliance-mappingSkill
- container-image-scanSkill
- containment-advisorSkill
- continuous-pentestingSkill
- credential-attacksSkill
- cryptography-key-managementSkill
- cyber-insuranceSkill
- data-security-classificationSkill
- deception-honeypotSkill
- detection-engineeringSkill
- devsecops-pipelineSkill
- endpoint-os-securitySkill
- enterprise-risk-assessmentSkill
- findings-trackerSkill
- finding-triageSkill
- forensicsSkill
- guardrailSkill
- iac-securitySkill
- identity-access-riskSkill
- incident-classificationSkill
- incident-commanderSkill
- insider-physical-riskSkill
- internal-audit-assuranceSkill
- knowledge-managementSkill
- metrics-reportingSkill
- network-exposureSkill
- orchestratorSkill
- os-hardeningSkill
- ot-iot-device-securitySkill
- owasp-top10-classifierSkill
- patch-candidateSkill
- pentest-reportingSkill
- persona-coverage-auditSkill
- The first 60 shown.
The file
We split this CLAUDE.md into the rules it gives an agent
6 rules. About 0 are common, 5 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 96
All cs-* agents created or updated after 2026-03-10 must include these 12 sections in order:
- Distinctive: line 141
Add to agent YAML to enable workflow state tracking:
- Distinctive: line 196
Write Purpose, Skill Integration, Workflows sections
- Distinctive: line 197
Test all relative paths
- Very specific: line 198
Update agents/CLAUDE.md agent catalog
- Distinctive: line 199
Update root README.md agents table
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Agent Development Guide
This guide provides instructions for creating cs- prefixed agents* that orchestrate the USAP skill packages.
How agents hand work to each other (the payload as envelope, next_agents, the hold on human_approval_required, the four USAP chains) is specified in ../ORCHESTRATION.md. Workflows you write must fit one of the chains or patterns defined there.
What are cs-* Agents?
cs- agents* are specialized orchestrators that combine multiple USAP skills into coherent, role-specific workflows. Each agent:
- References skills via relative paths (
../../<slug>/) - Executes Python automation tools from skill packages
- Follows the established SKILL.md workflow patterns
- Maintains skill portability and independence
Key Principle: Agents ORCHESTRATE skills, they do not replace them. Skills remain self-contained and portable.
Agent vs Skill
| Aspect | Agent (cs-*) | Skill |
| Purpose | Orchestrate and execute workflows | Provide tools, knowledge, templates |
| Location | agents/<domain>/ | <slug>/ |
| Structure | Single .md file with YAML frontmatter | SKILL.md + scripts/ + references/ + assets/ |
| Integration | References skills via ../../<slug>/ | Self-contained, no dependencies |
| Naming | cs-security-analyst, cs-ciso-advisor | threat-hunting, secrets-exposure |
Directory Structure
agents/
├── CLAUDE.md # This file
├── security/
│ ├── cs-security-analyst.md # Tier 2 SOC analyst orchestrator
│ ├── cs-incident-responder.md # Incident lifecycle manager
│ ├── cs-red-teamer.md # Offensive security coordinator
│ ├── cs-blue-team-analyst.md # Blue Team detection/DFIR orchestrator
│ ├── cs-cloud-investigator.md # Cloud incident investigation orchestrator
│ ├── cs-supply-chain-defender.md # Software supply chain defense orchestrator
│ ├── cs-threat-intel-lead.md # Intelligence-driven SOC orchestrator
│ └── cs-purple-team-lead.md # Purple team / detection validation orchestrator
├── appsec/
│ └── cs-appsec-engineer.md # Runtime + build-time AppSec orchestrator
├── devsecops/
│ └── cs-devsecops-engineer.md # Security-in-pipeline engineer
├── executive/
│ └── cs-ciso-advisor.md # Executive security advisor
└── governance/
└── cs-security-program-manager.md # Passive lifecycle: program planning, proactive scanning, facilitationAgent Catalog
| Agent | File | Role | Mode |
| cs-security-analyst | security/cs-security-analyst.md | Tier 2 SOC analyst | Reactive (alert-driven) |
| cs-incident-responder | security/cs-incident-responder.md | Incident lifecycle manager | Reactive (incident-driven) |
| cs-red-teamer | security/cs-red-teamer.md | Offensive security coordinator | Proactive (authorized, scoped) |
| cs-blue-team-analyst | security/cs-blue-team-analyst.md | Blue Team detection/DFIR orchestrator | Reactive (alert + hunt-driven) |
| cs-cloud-investigator | security/cs-cloud-investigator.md | Cloud incident investigation orchestrator | Reactive (CSPM-driven) |
| cs-supply-chain-defender | security/cs-supply-chain-defender.md | Software supply chain defense orchestrator | Reactive (SBOM/CI-driven) |
| cs-threat-intel-lead | security/cs-threat-intel-lead.md | Intelligence-driven SOC orchestrator | Reactive (IOC-driven) |
| cs-purple-team-lead | security/cs-purple-team-lead.md | Purple team / detection validation orchestrator | Reactive (exercise-driven) |
| cs-appsec-engineer | appsec/cs-appsec-engineer.md | Runtime + build-time AppSec orchestrator | Reactive (finding-driven) |
| cs-devsecops-engineer | devsecops/cs-devsecops-engineer.md | Security-in-pipeline engineer | Pipeline-triggered + doc intake |
| cs-ciso-advisor | executive/cs-ciso-advisor.md | Executive security advisor | Scheduled (board reporting) |
| cs-security-program-manager | governance/cs-security-program-manager.md | Passive lifecycle orchestrator | Passive (planning, scanning, facilitation) |
| cs-usap-next | meta/cs-usap-next.md | Operator co-pilot — "where am I, what's next" | Read-only (advisory) |
Required Frontmatter
---
name: cs-<agent-name>
description: <one-line description>
skills: <primary-skill-slug>
domain: <security|devsecops|executive>
model: sonnet
tools: [Read, Write, Bash, Grep, Glob]
---Required Sections
- Purpose (2-3 paragraphs)
- Skill Integration (skill location, Python tools, knowledge bases)
- Workflows (minimum 3 workflows with steps and examples)
- Integration Examples (concrete bash commands)
- Success Metrics
- Related Agents
- References
Required Agent Sections (v2)
All cs-* agents created or updated after 2026-03-10 must include these 12 sections in order:
- YAML Frontmatter — Required fields + optional
state:block - Purpose — 2-3 paragraphs: role, audience, and what gap the agent fills
- Persona ← NEW — Named identity, background, communication style, operating principles
- Critical Actions ← NEW — ALWAYS (3) and NEVER (3) hard operational rules
- Command Menu ← NEW — 2-letter trigger codes mapped to workflow names + HE (help) + ST (status)
- Input Discovery ← NEW — Documents to auto-discover before prompting for input
- Skill Integration — Skill paths, Python tools, knowledge bases
- Workflows — Minimum 3 workflows, each with MANDATORY EXECUTION RULES + FAILURE MODES + SUCCESS CRITERIA + FAILURE INDICATORS
- Integration Examples — Runnable bash command blocks
- Success Metrics — Measurable outcomes (not aspirational)
- Related Agents — Agents that send to or receive from this agent
- References — Links to primary SKILL.md files used
Workflow Block Requirements (v2)
Each workflow must include at the top (after Goal:):
MANDATORY EXECUTION RULES:
1. [rule]
2. [rule]
3. [rule]
FAILURE MODES:
- [condition] → [fallback]
- [condition] → [fallback]
- [condition] → [fallback]And at the bottom (after Expected Output:):
SUCCESS CRITERIA:
- [measurable outcome]
- [measurable outcome]
FAILURE INDICATORS:
- [observable sign of invalid output]
- [observable sign of invalid output]Optional state: Frontmatter Block
Add to agent YAML to enable workflow state tracking:
state:
active_workflow: null
steps_completed: []
input_documents: []
workflow_started_utc: null
last_step_completed_utc: nullPath Resolution
From agents/security/cs-security-analyst.md to a skill:
agents/security/ → ../../ → repo root → threat-hunting/So: ../../threat-hunting/scripts/threat-hunting_tool.py
Quality Checklist
- YAML frontmatter valid
cs-prefix used- All skill slugs referenced are valid (exist in repo)
- Relative paths resolve correctly
- At least 3 workflows documented
- Integration examples tested
- Success metrics defined
Passive vs. Reactive Split
Passive workflows are owned exclusively by cs-security-program-manager. No other cs-* agent should self-initiate a passive/scheduled workflow. The split:
cs-security-program-manager→ owns PL (program planning), SC (proactive scan), FR (facilitated review)cs-security-analyst→ owns AT (alert triage), TH (threat hunt), CA (compromise assess), DI (doc intake)cs-incident-responder→ owns IT (incident triage), CO (containment), FO (forensics)cs-red-teamer→ owns ES (engagement scoping), AP (attack path), FR (red team facilitation — authorized, scoped)cs-devsecops-engineer→ owns PR (pipeline review), RS (requirements scan), PA (pipeline assessment), DR (design review)cs-ciso-advisor→ owns BR (board report), RP (risk presentation), RG (regulatory guidance)
cs-security-program-manager may ROUTE findings to any reactive agent for further action. Reactive agents do not dispatch back — they produce outputs that cs-security-program-manager may consume in subsequent passive scans.
Routing boundary rule: A finding is only escalated from a passive workflow (SC) to a reactive agent (cs-security-analyst AT) when:
- Severity is Critical or High, AND
- Confirmed by at least 2 independent passive scan signals
Creating a New Agent
- Copy
../../templates/agent-template.md - Fill in YAML frontmatter
- Write Purpose, Skill Integration, Workflows sections
- Test all relative paths
- Update
agents/CLAUDE.mdagent catalog - Update root
README.mdagents table - Commit:
feat(agents): implement cs-<agent-name>
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

