agentleFS
Sign inStart free
rafaelgarrafielrafaelgarrafiel/team_skills/.claude/CLAUDE.md

team_skills

CLAUDE.md2 starsChanged 30 days agoMITView on GitHub

A plugin for Claude Code and Codex that adds a team (Product Owner and Tech Lead hats on the main session, plus advisor and builder subagents) on top of mattpocock/skills. It overlays Matt's skills when they are installed and runs standalone when they are not. The decisions behind that are ADRs in .agents/adr/; read the ones touching the area you change.

The file

We split this CLAUDE.md into the rules it gives an agent

2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    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:

    No em-dashes anywhere in this repo's prose.

    line 20
  2. Very specific:

    Write skills and personas per the writing-for-agents skill: steps end on a checkable completion criterion, reference is disclosed behind …

    line 21

≈ “Common” is an estimate: at least 1 in 5 of the 26,980 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

team-skills

A plugin for Claude Code and Codex that adds a team (Product Owner and Tech Lead hats on the main session, plus advisor and builder subagents) on top of mattpocock/skills. It overlays Matt's skills when they are installed and runs standalone when they are not. The decisions behind that are ADRs in .agents/adr/; read the ones touching the area you change.

Layout

  • skills/<name>/SKILL.md: one flat folder per skill, no buckets (Codex's manifest takes a single skills path). Every skill folder also carries agents/openai.yaml.
  • agents/<role>.md: the canonical persona files, auto-discovered by Claude Code (the manifest carries no agents field on purpose, see ADR 0002). skills/setup-team/codex-agents/*.toml is generated from them by scripts/build.sh and committed; it lives inside the skill so every installer ships it. Never edit generated output.
  • .claude-plugin/, .codex-plugin/: the two manifests. Run claude plugin validate . --strict after touching either.
  • .agents/adr/: decisions. .agents/roster.md: who leads and supports where. The contribution contract is the team-contribution skill.
  • hooks/: the Claude Code PreToolUse overlay hook (ADR 0003). docs/<skill>.md: one human-facing page per skill, in the shape of Matt's docs pages (What it does, When to reach for it, Common questions, It's working if, Where it fits).
  • evals/: behavioural eval cases for claude plugin eval, run with scripts/eval.sh (costs money, so not in CI; run before a release and after changing a hat, a persona or the Team block). evals/README.md lists what each case catches.
  • PLAN.md: the phased implementation plan, kept current until v1.0 ships. scripts/validate.sh before any commit. A release bumps the version with scripts/set-version.sh <x.y.z> (manifests, package.json, every skill's metadata.version, the README line), never by hand: validate.sh fails when they disagree.

Conventions

  • Skill names carry the team- prefix (team-grill, team-implement), except setup-team and ask-team. Agent names carry no prefix (lgpd-analyst, qa-expert).
  • A skill is either user-invoked (disable-model-invocation: true plus policy.allow_implicit_invocation: false in agents/openai.yaml) or model-invoked. The hat skills (team-grill, team-implement) are model-invoked so the main session can load them from inside Matt's user-invoked skills; setup-team and ask-team are user-invoked. Dependencies between skills are an explicit "call the Skill tool with <name>", never a bare /name.
  • Source prose (skills, personas, ADRs, README) is English. The language of the artifacts the team produces in a target repo is a setup-team setting.
  • No em-dashes anywhere in this repo's prose. Rewrite with a comma, colon, period, parentheses, or a conjunction.
  • Write skills and personas per the writing-for-agents skill: steps end on a checkable completion criterion, reference is disclosed behind pointers, positive phrasing over prohibition.

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.

Check your setup, free