Vibe coding with Claude Code course Β· Module 15: Advanced Claude Code

Your own crew: subagents, skills and plugins

9 min read
In this lesson9

Before every commit in Treasure Map you ask Claude for the same thing: review the API routes for security. Once you write "take a look at the session", once "will anyone save a pin on someone else's board", and once you forget to ask about validation. Each time the review looks a little different, and each time something else slips through. A procedure you repeat from memory in different words is a procedure you do not have.

What you already know

In lesson 9_5 you ordered the video-reviewer subagent with tools: Read, Grep, Glob and model: sonnet, and in lesson 5_4 you sent the built-in Explore on a scouting trip. You know skills from lesson 6_1, and in lesson 10_5 the /deploy skill with disable-model-invocation: true left the decision about deployment to you. From lesson 5_10 you know that a subagent costs tokens and does not think more cleverly, it only works in a separate context. Now you put these parts together into one procedure for the crew: a reviewer, a skill that summons it, and a plugin in which you carry both to other projects.

Request for Claude Code

You order the reviewer and the skill with one request, because the skill is to call that reviewer by name:

Create a project subagent .claude/agents/security-reviewer.md that only reads
(Read, Grep, Glob) and checks the routes in app/api: the session, the data owner,
the Zod schema and the text of errors. In description say when to use it. Then create the skill
.claude/skills/pre-commit/SKILL.md: tests, lint and this subagent for the files
in the staging area, and at the end a table with a verdict. Only I run this skill.
Do not change the application code.

The request says not only what the reviewer is to do, but also what it must not do. The last sentence guards against "while I was at it, I fixed it".

What Claude wrote: the reviewer

In Cursor open .claude/agents/security-reviewer.md. At the top stands the frontmatter, that is, the agent's settings:

---
name: security-reviewer
description: Security reviewer of the Treasure Map API routes. Use it before every commit that changes files in app/api or lib/session.ts. It gets a list of files and only reads the code.
tools: Read, Grep, Glob
model: sonnet
---

description tells Claude when to delegate, so concrete folders work better than "reviews code". tools is the list of allowed tools. When you omit the field, the agent gets all the tools of the conversation, and disallowedTools: Write, Edit leaves it Bash and the MCP tools, so for a reviewer you choose a short list. model: sonnet takes the cheaper model for routine work. Without this field the subagent works on the conversation model, and the documentation adds that Claude may name a different model when it calls the agent. Below the frontmatter stands the text that becomes the agent's system prompt:

You are a security reviewer. You get a list of changed files.
For every route in app/api check:
1. whether a route that changes data calls getCurrentUserId() and returns 401 without a session;
2. whether it checks the owner of the board or pin and returns 403 for someone else's data;
3. whether the input passes through a Zod schema;
4. whether the error response does not reveal database details.

Fix nothing. Answer with a list: file:line | problem | suggestion.
When you find nothing, write: No remarks.

The subagent does not see your conversation: it gets this prompt and the task from Claude. The four questions are the core, because the review checks the same things every time, regardless of how you word the request today. You know the answer format from lesson 14_1, and you compare each line with the diff.

What Claude wrote: the /pre-commit skill

Now .claude/skills/pre-commit/SKILL.md. The skill header has four fields:

---
name: pre-commit
description: Report before a commit: tests, lint and a security review of the staged changes.
disable-model-invocation: true
allowed-tools: Bash(npm run test *) Bash(npm run lint)
---

You know disable-model-invocation: true from /deploy: only you run the skill, and its description does not take up context. allowed-tools approves those two commands without asking, but only in the turn in which the skill runs, and it takes nothing away. The documentation adds a warning: Claude Code applies a skill's allowed-tools from a repository even in a -p run in a folder you have not trusted. So skills in someone else's repository you read like scripts. Below the header stand the steps:

## Staged files
!`git diff --cached --name-only`

## Steps
1. Run `npm run test -- --run` and record the result.
2. Run `npm run lint` and record the result.
3. Pass the security-reviewer subagent the list of staged files.
4. Fix nothing. At the end show a table: tests, lint, review, and below it a verdict "ready to commit" or "needs fixes" with a list of reasons.

The line with the exclamation mark is an injection: Claude Code runs the command before Claude reads the skill and pastes its output in place of the line. It is not an ornament. A reviewer with Read, Grep, Glob will not run git diff itself, so the list of files must come in the task. The steps do not stop at the first error, because before a commit you want the full picture.

A trial: /pre-commit

In the session you type /pre-commit. We ran the same through claude -p "/pre-commit", with lib/pinInput.ts from lesson 14_1 in the staging area. A shortened result:

| Tests | 3 failing out of 64 |
| Lint | 2 errors |
| Security review | 1 high, 1 medium, 3 low remarks |
High, line 9: z.union([startsWith("/pins/"), z.url()]) lets any URL through
Verdict: needs fixes

In the run's JSON the subagent_stats field showed one subagent of type security-reviewer started. The reviewer found the same hole as the quick review from the pipe in lesson 14_1, but now everyone in the crew will find it with the same command.

Captain's review

  1. The reviewer's tools. The frontmatter has only Read, Grep, Glob. A typical agent mistake: it adds Edit and Write "just in case, so the reviewer can fix it at once". Then the reviewer quietly changes code whose diff you did not read, and the review stops being independent. You will recognise it by the tools line or by its absence.
  2. A description with a condition. description says when to use the agent. Without it Claude will not reach for the agent by itself and you will be calling it by name.
  3. Who runs the skill. disable-model-invocation: true must be here, because the report ends with a decision about a commit.
  4. A check. Type @ and pick the reviewer from the suggestions, and /skills will show the skill on the list. A .claude/agents/ folder created during a session needs a session restart, and a new .claude/skills/ needs the /reload-skills command, as in lesson 6_1.

Plugins: the crew in one chest

The files in .claude/agents/ and .claude/skills/ travel with the Treasure Map repository. And what when you want the same reviewer in a Spotify clone? A plugin is a directory with skills, agents, hooks and MCP servers that Claude Code installs and loads as a whole. You browse other people's plugins with the /plugin command: the Discover tab shows plugins from your marketplaces, that is, catalogues of plugins. Anthropic's official marketplace, claude-plugins-official, Claude Code adds itself at the first terminal session. Installation starts with a preview:

/plugin install commit-commands@claude-plugins-official

In a session this command installs nothing yet: it opens the details with the list of what the plugin will add and asks about the scope. The project scope writes the plugin into .claude/settings.json, but everyone in the crew still installs it on their own machine. A plugin works with your permissions, so you read it like any other foreign code.

You pack your own crew the same way. The documentation describes moving a ready .claude/ folder into a plugin with this layout:

treasure-crew/
β”œβ”€β”€ .claude-plugin/plugin.json      # name and description of the plugin
β”œβ”€β”€ agents/security-reviewer.md
└── skills/pre-commit/SKILL.md

claude plugin validate ./treasure-crew checks the manifest and frontmatters, and claude --plugin-dir ./treasure-crew loads the plugin for one session. The skill then gets a prefix: /treasure-crew:pre-commit. Two differences are worth knowing. A subagent from a plugin ignores the fields hooks, mcpServers and permissionMode, and every enabled plugin brings the descriptions of its skills and agents into every turn, also when you do not use them. I recommend a simple rule: one project means .claude/ in the repository, several projects mean a plugin.

MCP for the crew

You already know MCP servers for the whole crew: in lesson 11_4 --scope project saved Sentry in .mcp.json, and in lesson 13_7 you added Supabase read-only and an ask rule for mcp__supabase__*. Add one more thing to that: in .mcp.json you can write ${API_KEY} instead of a token, and Claude Code will substitute an environment variable from each sailor's computer, so the secret does not reach the repository. The advice from lesson 11_4 still holds: when a system has a CLI, for example gh for GitHub, start with it and leave MCP for systems without a CLI.

Next step

Add a type check to the procedure:

Add to the /pre-commit skill a step npx tsc --noEmit before lint
and add Bash(npx tsc --noEmit) to allowed-tools. Do not change the reviewer.

Run /pre-commit once more and ask for a commit, for example "Security reviewer and the pre-commit skill". In the editor next to the lesson you will paste the frontmatter of a subagent or a skill and see what Claude Code will not load, what tools the reviewer will get and who can run the skill.

Remember: you recruit a crew once, and the procedure works on every voyage.

Code for this lesson: App.tsx
// Frontmatter check: what Claude Code will do with a subagent or skill file
import { useState } from 'react';

export type Kind = 'agent' | 'skill';
export type Level = 'ok' | 'warn' | 'error';

export interface Finding {
  level: Level;
  text: string;
}

export interface Parsed {
  hasFrontmatter: boolean;
  fields: Record<string, string>;
  body: string;
}

const BT = String.fromCharCode(96);

export function parseFrontmatter(src: string): Parsed {
  const lines = src.split('\n');
  if (lines[0] !== '---') return { hasFrontmatter: false, fields: {}, body: src };
  const end = lines.findIndex((l, i) => i > 0 && l.trim() === '---');
  if (end === -1) return { hasFrontmatter: false, fields: {}, body: src };
  const fields: Record<string, string> = {};
  for (const line of lines.slice(1, end)) {
    const m = /^([A-Za-z_-]+):\s*(.*)$/.exec(line);
    if (m) fields[m[1]] = m[2].trim();
  }
  return { hasFrontmatter: true, fields, body: lines.slice(end + 1).join('\n') };
}

export function toolList(value: string | undefined): string[] {
  if (!value) return [];
  return value.split(/[,\s]+/).filter(Boolean);
}

const AGENT_FIELDS = ['name', 'description', 'tools', 'disallowedTools', 'model', 'permissionMode', 'maxTurns', 'skills', 'mcpServers', 'hooks', 'memory', 'background', 'effort', 'isolation', 'color'];
const MODELS = ['sonnet', 'opus', 'haiku', 'fable', 'inherit'];
const WRITERS = ['Edit', 'Write', 'Bash', 'NotebookEdit'];

export function checkAgent(p: Parsed): Finding[] {
  const f = p.fields;
  const out: Finding[] = [];
  if (!p.hasFrontmatter || !f.name) {
    return [{ level: 'error', text: 'Without name (or without --- on the first line) Claude Code treats the file as documentation and skips it.' }];
  }
  if (f.name.includes(':')) out.push({ level: 'error', text: 'name cannot contain a colon: it is reserved for plugins.' });
  if (!f.description) {
    out.push({ level: 'error', text: 'There is a name but no description: Claude Code will skip the file and log the reason in --debug.' });
  } else if (!/use /i.test(f.description)) {
    out.push({ level: 'warn', text: 'description does not say when to use the agent. Claude delegates based on this description.' });
  } else {
    out.push({ level: 'ok', text: 'description says when to delegate.' });
  }
  const tools = toolList(f.tools);
  if (!f.tools && f.disallowedTools) {
    out.push({ level: 'warn', text: 'disallowedTools without tools: the agent inherits the remaining tools, Bash and MCP too.' });
  } else if (!f.tools) {
    out.push({ level: 'warn', text: 'No tools: the agent gets all the tools of the conversation, Edit, Write and Bash too.' });
  } else {
    const writers = tools.filter((t) => WRITERS.includes(t));
    out.push(
      writers.length
        ? { level: 'warn', text: 'A reviewer with ' + writers.join(', ') + ' can change code or run commands. Read, Grep, Glob is enough for a review.' }
        : { level: 'ok', text: 'Read only (' + tools.join(', ') + '). It must get the list of files in the task, because it will not run git diff.' },
    );
  }
  if (f.model) {
    const known = MODELS.includes(f.model) || f.model.startsWith('claude-');
    out.push(known ? { level: 'ok', text: 'model: ' + f.model + '.' } : { level: 'warn', text: 'Unknown model "' + f.model + '".' });
  }
  for (const key of Object.keys(f)) {
    if (!AGENT_FIELDS.includes(key)) {
      out.push({ level: 'warn', text: 'The field ' + key + ' does not exist for an agent; Claude Code ignores it without an error (agent fields are written in camelCase).' });
    }
  }
  return out;
}

const SKILL_FIELDS = ['name', 'description', 'when_to_use', 'argument-hint', 'arguments', 'disable-model-invocation', 'user-invocable', 'allowed-tools', 'disallowed-tools', 'model', 'effort', 'context', 'agent', 'background', 'hooks', 'paths', 'shell'];

export function checkSkill(p: Parsed): Finding[] {
  const f = p.fields;
  const out: Finding[] = [];
  if (!p.hasFrontmatter) {
    return [{ level: 'warn', text: 'Without --- on the first line the whole file is content, and the skill has no fields.' }];
  }
  out.push(
    f.description
      ? { level: 'ok', text: 'description is there; it tells Claude what the skill is for.' }
      : { level: 'warn', text: 'No description: Claude will take the first line of the content.' },
  );
  const sideEffects = /commit|deploy|push|npm run/i.test(p.body);
  if (f['disable-model-invocation'] === 'true') {
    out.push({ level: 'ok', text: 'Only you run the skill; its description is not kept in the context.' });
  } else if (sideEffects) {
    out.push({ level: 'warn', text: 'The steps have side effects, and Claude may run the skill itself. Add disable-model-invocation: true.' });
  }
  if (f['allowed-tools']) {
    out.push({ level: 'ok', text: 'allowed-tools zatwierdza ' + f['allowed-tools'] + ' only in the skill turn and takes nothing away. In someone else repository read this line carefully.' });
  }
  const injected = p.body.split('\n').filter((l) => l.startsWith('!' + BT));
  for (const line of injected) {
    out.push({ level: 'ok', text: 'Injection: ' + line.slice(2, -1) + ' runs before Claude reads the skill, and the output replaces the line.' });
  }
  for (const key of Object.keys(f)) {
    if (!SKILL_FIELDS.includes(key)) {
      out.push({ level: 'warn', text: 'The field ' + key + ' does not exist for a skill; Claude Code ignores it without an error (skill fields are written with hyphens).' });
    }
  }
  return out;
}

export const SAMPLES: Record<string, { kind: Kind; text: string }> = {
  'Read-only reviewer': {
    kind: 'agent',
    text: [
      '---',
      'name: security-reviewer',
      'description: Security reviewer of the API routes. Use it before every commit that changes app/api.',
      'tools: Read, Grep, Glob',
      'model: sonnet',
      '---',
      'Check the session, the data owner and the Zod schema. Fix nothing.',
    ].join('\n'),
  },
  'Reviewer just in case': {
    kind: 'agent',
    text: [
      '---',
      'name: security-reviewer',
      'description: Reviews code.',
      'tools: Read, Grep, Glob, Edit, Write',
      'disallowed-tools: Bash',
      '---',
      'Check the routes and fix what you find at once.',
    ].join('\n'),
  },
  'Pre-commit skill': {
    kind: 'skill',
    text: [
      '---',
      'name: pre-commit',
      'description: Report before a commit: tests, lint and a security review.',
      'disable-model-invocation: true',
      'allowed-tools: Bash(npm run test *) Bash(npm run lint)',
      '---',
      '## Staged files',
      '!' + BT + 'git diff --cached --name-only' + BT,
      '1. Run npm run test -- --run.',
      '2. Pass the list of files to the security-reviewer subagent.',
    ].join('\n'),
  },
  'Skill without a lock': {
    kind: 'skill',
    text: [
      '---',
      'name: pre-commit',
      'disableModelInvocation: true',
      '---',
      'Run the tests and make a commit if they pass.',
    ].join('\n'),
  },
};

const LEVEL_CLASS: Record<Level, string> = {
  ok: 'text-emerald-400',
  warn: 'text-amber-400',
  error: 'text-rose-400',
};

export default function App() {
  const names = Object.keys(SAMPLES);
  const [kind, setKind] = useState<Kind>(SAMPLES[names[0]].kind);
  const [text, setText] = useState(SAMPLES[names[0]].text);
  const parsed = parseFrontmatter(text);
  const findings = kind === 'agent' ? checkAgent(parsed) : checkSkill(parsed);

  return (
    <div className="min-h-screen space-y-4 bg-slate-950 p-4 text-slate-100">
      <h1 className="text-xl font-bold">Crew check: subagent and skill</h1>
      <div className="flex flex-wrap gap-2">
        {names.map((n) => (
          <button
            key={n}
            type="button"
            className="rounded bg-slate-700 px-3 py-1 text-sm"
            onClick={() => {
              setKind(SAMPLES[n].kind);
              setText(SAMPLES[n].text);
            }}
          >
            {n}
          </button>
        ))}
      </div>
      <label className="block text-sm">
        File kind{' '}
        <select className="rounded bg-slate-800 p-1" value={kind} onChange={(e) => setKind(e.target.value as Kind)}>
          <option value="agent">.claude/agents/*.md</option>
          <option value="skill">.claude/skills/*/SKILL.md</option>
        </select>
      </label>
      <textarea
        className="h-56 w-full rounded bg-slate-900 p-2 font-mono text-xs"
        value={text}
        onChange={(e) => setText(e.target.value)}
      />
      <ul className="space-y-1 text-sm">
        {findings.map((f, i) => (
          <li key={i} className="rounded border border-slate-800 p-2">
            <strong className={LEVEL_CLASS[f.level]}>{f.level}</strong> {f.text}
          </li>
        ))}
      </ul>
    </div>
  );
}

Spotted a mistake in this lesson?

Check yourself

Answer the questions from this lesson. Pick an answer to see right away whether it is correct.

  1. 1. The security-reviewer subagent is only to review the API routes. What do you write in its frontmatter?

  2. 2. Where do you save the security-reviewer subagent so that everyone who clones Treasure Map gets it?

These are 2 of 4 questions for this lesson. Solve the rest in the game.

Hands-on tasks in the game

  • Horizontal ordering

    Arrange the command that checks the manifest and frontmatters of your treasure-crew plugin before you give it to the crew:

  1. QuestionQuiz: The reviewer subagent's tools
  2. QuestionQuiz: A subagent for the whole crew
  3. Put in orderSorting: Checking a plugin
  4. QuestionQuiz: CLI or MCP
  5. QuestionQuiz: An injected list of files in a skill

Useful articles