Skills integration for composable agent knowledge (v2)

[appsechq-brian]

Context

ARCH currently uses persona files (personas/*.md) as the sole mechanism for giving agents role-specific knowledge and workflow instructions. This works well for role identity ("who you are") but doesn't address project-specific conventions and reusable knowledge ("how we do things here").

Claude Code already supports Skills (.claude/skills/*.md) — reusable prompt templates that agents can invoke or receive as context. Since ARCH agents are real claude CLI subprocesses in git worktrees, agents already inherit project-level skills if .claude/skills/ exists in the repo. But ARCH doesn't manage, augment, or leverage this.

Proposal

Add a composable knowledge layer on top of personas:

Layer model

Layer	What	Where	Scope
Persona	Role identity, expertise, workflow	personas/{role}.md	Per-role
Project skills	Codebase conventions, patterns, recipes	.claude/skills/*.md	All agents
Role skills	Role-specific knowledge applicable to this project	Mapped via arch.yaml	Per-role

1. arch init scaffolds a skills directory

.claude/
└── skills/
    ├── testing.md          # How to write tests in this codebase
    ├── commit-style.md     # Commit message conventions
    └── pr-template.md      # PR description template

These are standard Claude Code skills — they work with or without ARCH.

2. arch.yaml gets an optional skills: section

agent_pool:
  - id: frontend
    persona: "personas/frontend.md"
    skills:                          # Optional: additional skills for this role
      - ".claude/skills/testing.md"
      - ".claude/skills/component-patterns.md"

  - id: qa
    persona: "personas/qa.md"
    skills:
      - ".claude/skills/testing.md"
      - ".claude/skills/bug-report.md"

3. Orchestrator injects role-specific skills into worktrees

At spawn time, in addition to writing CLAUDE.md:

• Copy/symlink the role's configured skills into the agent's worktree .claude/skills/ directory
• List available skills in the injected context block so agents know what they can use

4. Optional: ARCH-provided skills

Ship default skills alongside personas:

• /update-docs — Sync documentation after code changes
• /test-and-commit — Run tests, fix failures, then commit
• /review-checklist — Code review checklist for merge requests

Use cases

• Testing conventions: Every agent knows how to write tests for THIS codebase, not just generically
• Commit style: Consistent commit messages across all agents without repeating instructions in every persona
• Deploy recipes: Multi-step workflows that agents can invoke
• Domain knowledge: Business logic explanations that all agents need

Why not just put it in personas?

• DRY: Testing conventions apply to frontend, backend, AND QA agents. With personas, you'd repeat them three times.
• Composability: Users can mix and match skills per role without forking persona files.
• Standard tooling: Skills are a Claude Code feature — they work outside ARCH too.
• Separation of concerns: Persona = agent identity. Skills = project knowledge.

Acceptance Criteria

• arch init creates .claude/skills/ with example skill files
• arch.yaml supports optional skills: list per agent pool entry
• Orchestrator copies/symlinks role skills into agent worktrees at spawn
• Injected CLAUDE.md context block lists available skills
• Project-level skills (in repo's .claude/skills/) work without configuration (inherited via worktree)
• Documentation explains the persona vs. skills model