Capstone: Design your team's skills architecture

You've worked through every concept in this course — what Skills are, how to build them, how to configure them, how to share them, and how to fix them when they break. The capstone pulls all of that into a single practical artifact: a skills architecture for your team, written as a document you can take straight back to work.

This is a design exercise, not a coding exercise. The output is a plan. By the end of this lesson you should have a concrete answer to "how will we actually use skills on this team?" — specific enough to implement, detailed enough to hand to someone else.

The three-channel recap

Before you design, remember what you're choosing between. Every skill your team writes has to live somewhere, and that choice determines who gets it and under what priority.

Git repository — commit the skill to .claude/skills in the repo root. Anyone who clones gets it automatically. Best for team coding standards, project-specific workflows, and skills that reference your codebase structure.

Plugin / marketplace — package the skill inside a plugin and publish it. Best for cross-project skills that other teams or the wider community might want: general-purpose review tools, documentation formatters, accessibility auditors.

Enterprise managed settings — deploy organisation-wide with the highest priority. Overrides personal, project, and plugin skills with the same name. Best for mandatory standards, security requirements, and compliance workflows that must be consistent across the entire organisation.

The question for each skill is where does this need to show up, and who is allowed to override it?

Map your team's workflow

Start by thinking about your team's development workflow end-to-end, from ticket to deploy. Where are the repeating instructions? Where do you already have written standards that nobody follows because they live in a wiki? Where does onboarding stall because the conventions aren't obvious?

Reflection prompt. Work through these questions before you start designing:

• What tasks do your team members explain to Claude over and over?
• Which of those tasks are genuinely personal preference, and which should be team standards?
• Where do you need enforcement — things that must be consistent no matter who's working?
• Where would isolated subagent delegation improve consistency? (Code review is the classic answer, but there are others.)
• Which tasks currently don't exist as written standards at all?

Every answer is a candidate skill.

A template for your skills architecture

Use this structure to write your design document. Fill each section with real names, real tasks, and real decisions.

1. Personal skills (individual preferences)

List skills each team member might keep in ~/.claude/skills. These aren't team standards — they're individual style: preferred commit message format, how you like code explained, personal documentation conventions. Example: a commit-message skill that enforces your preferred prefix format.

2. Project skills (shared via Git)

List skills that belong in .claude/skills inside the repo. These are the team standards that every developer who clones the repo should get automatically. Examples:

• Code review checklist for this codebase
• Deployment procedure specific to this project
• Test conventions and naming rules
• Architecture patterns (where components go, how state is shaped)

3. Distribution strategy

For each skill, decide which channel it belongs in:

| Skill | Channel | Reason | |---|---|---| | Example: frontend-review | Project (Git) | Codebase-specific, team-wide | | Example: security-audit | Enterprise | Mandatory, must not be overridden | | Example: accessibility-check | Plugin | Useful across multiple teams |

4. Subagent wiring

List the custom subagents your team will use and the skills each one loads. Remember: skills in subagents load at agent start, not on demand — only list skills that are always relevant to the agent's purpose.

Example: a frontend-reviewer subagent that loads accessibility-audit, performance-check, and react-conventions.

5. Naming conventions

Define how you'll name skills to avoid priority conflicts. Generic names like review or test are collision magnets — prefer descriptive, qualified names:

• frontend-pr-review instead of review
• backend-deploy-check instead of deploy
• api-docs-format instead of docs

Write the convention down so new skills follow it from day one.

6. Troubleshooting runbook

Adapt the Quick Troubleshooting Checklist from the previous lesson into a runbook your team can reference. Something like:

When a skill isn't working:

1. Run the validator first
2. Not triggering? Improve the description and add trigger phrases
3. Not loading? Check path, filename casing, YAML syntax, and run claude --debug
4. Wrong skill used? Make descriptions more distinct
5. Being shadowed? Check the priority hierarchy and rename
6. Plugin missing? Clear cache, restart, reinstall
7. Runtime failure? Check dependencies, execute permissions, and path separators

Put it in your team wiki or onboarding docs. New team members will hit these issues exactly once if the runbook exists.

Closing the loop

Go back to the thesis from the very first lesson. If you find yourself explaining the same thing to Claude repeatedly, that's a skill waiting to be written. The same rule applies at team scale: if your team finds itself explaining the same thing to every new hire, every new project, every PR, that's a skill your team should own.

The architecture you've just designed is how you make that happen systematically. Skills aren't a productivity trick for individual engineers — they're how a team encodes its standards into the tools it already uses.