agentleFS
jaskaranhundaljaskaranhundal/usap-skills/agents/CLAUDE.md

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…

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
  1. Distinctive:

    All cs-* agents created or updated after 2026-03-10 must include these 12 sections in order:

    line 96
  2. Distinctive:

    Add to agent YAML to enable workflow state tracking:

    line 141
  3. Distinctive:

    Write Purpose, Skill Integration, Workflows sections

    line 196
  4. Distinctive:

    Test all relative paths

    line 197
  5. Very specific:

    Update agents/CLAUDE.md agent catalog

    line 198
  6. Distinctive:

    Update root README.md agents table

    line 199

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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

AspectAgent (cs-*)Skill
PurposeOrchestrate and execute workflowsProvide tools, knowledge, templates
Locationagents/<domain>/<slug>/
StructureSingle .md file with YAML frontmatterSKILL.md + scripts/ + references/ + assets/
IntegrationReferences skills via ../../<slug>/Self-contained, no dependencies
Namingcs-security-analyst, cs-ciso-advisorthreat-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, facilitation

Agent Catalog

AgentFileRoleMode
cs-security-analystsecurity/cs-security-analyst.mdTier 2 SOC analystReactive (alert-driven)
cs-incident-respondersecurity/cs-incident-responder.mdIncident lifecycle managerReactive (incident-driven)
cs-red-teamersecurity/cs-red-teamer.mdOffensive security coordinatorProactive (authorized, scoped)
cs-blue-team-analystsecurity/cs-blue-team-analyst.mdBlue Team detection/DFIR orchestratorReactive (alert + hunt-driven)
cs-cloud-investigatorsecurity/cs-cloud-investigator.mdCloud incident investigation orchestratorReactive (CSPM-driven)
cs-supply-chain-defendersecurity/cs-supply-chain-defender.mdSoftware supply chain defense orchestratorReactive (SBOM/CI-driven)
cs-threat-intel-leadsecurity/cs-threat-intel-lead.mdIntelligence-driven SOC orchestratorReactive (IOC-driven)
cs-purple-team-leadsecurity/cs-purple-team-lead.mdPurple team / detection validation orchestratorReactive (exercise-driven)
cs-appsec-engineerappsec/cs-appsec-engineer.mdRuntime + build-time AppSec orchestratorReactive (finding-driven)
cs-devsecops-engineerdevsecops/cs-devsecops-engineer.mdSecurity-in-pipeline engineerPipeline-triggered + doc intake
cs-ciso-advisorexecutive/cs-ciso-advisor.mdExecutive security advisorScheduled (board reporting)
cs-security-program-managergovernance/cs-security-program-manager.mdPassive lifecycle orchestratorPassive (planning, scanning, facilitation)
cs-usap-nextmeta/cs-usap-next.mdOperator 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

  1. Purpose (2-3 paragraphs)
  2. Skill Integration (skill location, Python tools, knowledge bases)
  3. Workflows (minimum 3 workflows with steps and examples)
  4. Integration Examples (concrete bash commands)
  5. Success Metrics
  6. Related Agents
  7. References

Required Agent Sections (v2)

All cs-* agents created or updated after 2026-03-10 must include these 12 sections in order:

  1. YAML Frontmatter — Required fields + optional state: block
  2. Purpose — 2-3 paragraphs: role, audience, and what gap the agent fills
  3. Persona ← NEW — Named identity, background, communication style, operating principles
  4. Critical Actions ← NEW — ALWAYS (3) and NEVER (3) hard operational rules
  5. Command Menu ← NEW — 2-letter trigger codes mapped to workflow names + HE (help) + ST (status)
  6. Input Discovery ← NEW — Documents to auto-discover before prompting for input
  7. Skill Integration — Skill paths, Python tools, knowledge bases
  8. Workflows — Minimum 3 workflows, each with MANDATORY EXECUTION RULES + FAILURE MODES + SUCCESS CRITERIA + FAILURE INDICATORS
  9. Integration Examples — Runnable bash command blocks
  10. Success Metrics — Measurable outcomes (not aspirational)
  11. Related Agents — Agents that send to or receive from this agent
  12. 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: null

Path 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:

  1. Severity is Critical or High, AND
  2. Confirmed by at least 2 independent passive scan signals

Creating a New Agent

  1. Copy ../../templates/agent-template.md
  2. Fill in YAML frontmatter
  3. Write Purpose, Skill Integration, Workflows sections
  4. Test all relative paths
  5. Update agents/CLAUDE.md agent catalog
  6. Update root README.md agents table
  7. Commit: feat(agents): implement cs-<agent-name>

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.