Modular agent composition: build agent .md from reusable components

[krisrowe]

Problem

Agent definitions are monolithic markdown files. As agents grow (privacy-guard is ~350 lines with built-in patterns, judgment tables, scan instructions, output schema), shared logic between agents (PERSON.md loading, OS discovery, credential patterns, employer judgment) is duplicated.

Vision

A build-time composition system that assembles agent .md files from reusable components. The shipped agent is still a single .md (Claude Code requires this), but the source is modular.

Possible structure

agent-components/
  person-md-loading.md
  os-discovery.md
  builtin-patterns.md
  employer-judgment.md
  output-schema-guard.md
  scan-pre-push.md
  scan-full-history.md

A build step concatenates components with frontmatter injection to produce the final .md files. Different compositions for different use cases — CI variant, local variant, strict vs relaxed.

Scope

• Research how others solve agent definition modularity. Use /identify-best-practices to survey approaches in the Claude Code ecosystem, other agent frameworks (CrewAI, AutoGen, LangGraph), and prompt engineering best practices for composable system prompts.
• Design the component format and composition mechanism.
• Prototype with privacy-guard and privacy-audit as first consumers.
• Consider how this interacts with the plugin system's agent discovery.

Related

• Agent interface contract: parent-facing skill, schema enforcement, and discovery #4 — agent interface contract
• CI/CD integration: privacy scanning in GitHub Actions for PRs #6 — CI integration (CI variant could be a different composition)
• Agent should own PII categories and reason from any input, not just structured YAML #2 — agent category ownership