Module 5: Plugins — Creating and Distributing

5. Project — Complete Code Quality Plugin

Next →

5. Project — Complete Code Quality Plugin

Project Description

You've learned the anatomy of a plugin, created one from a scaffold, tested it locally, and understand how versioning and publishing to registries work. Now you integrate everything into a production plugin: a code quality package with two specialized subagents and a conventions skill file, complete with a professional manifest, documentation, and publication to a local registry.

The plugin you'll build packages a quality-reviewer (analyzes code in read-only mode and produces structured reports), a quality-implementer (applies fixes following conventions), and a team-conventions skill (the team's shared rules that both agents consume). These aren't generic agents — they're designed to work as a flow: the reviewer detects problems, the implementer fixes them, and both use the same conventions as the source of truth.

This project is the close of Module 5. If the plugin installs with one command, the agents load automatically, the conventions are applied in the review, and you can publish it to verdaccio so another developer can install it — you've mastered creating and distributing plugins.

⚠️ EXPERIMENTAL FEATURE

The Claude Code plugin system is experimental. If claude plugins add isn't available in your version, this project includes a manual alternative section with an installation script. The agent files and skills work as standard subagents in both cases.

Last check: March 2026

Project Objective

Build a complete code quality plugin with 2 subagent files + 1 skill file, test it locally, and publish it to a local registry (verdaccio).

By the end of this project:

  • ✅ You'll have an npm package with claudeCodePlugin: true and the correct structure
  • ✅ The quality-reviewer will produce structured reports using the skill's conventions
  • ✅ The quality-implementer will apply fixes following the same conventions
  • ✅ The plugin will install with a single command and load automatically
  • ✅ The agents will discover the project structure dynamically (no hardcoded paths)
  • ✅ The plugin will be published to a local registry, installable by other developers
  • ✅ The package.json will have semver versioning and professional fields

Estimated duration: 1.5-2 hours (setup: 15 min + agent files: 30 min + skill: 15 min + testing: 30 min + publishing: 15 min + iteration: 15 min).

Technical Specifications

Technology Stack

  • Tool: Claude Code (recent version with plugin support)
  • Package: npm with claudeCodePlugin
  • Local registry: Verdaccio (private npm registry)
  • Agent files: Markdown with YAML frontmatter
  • Test project: Any project with source code (Python, JavaScript, TypeScript)

Requirements

RequirementMinimumIdeal
Node.jsv18+v20+
npmv9+v10+
Claude CodeWith plugin supportLatest version
VerdaccioInstalled globallyRunning in the background
Test project5+ code filesWith CLAUDE.md and conventions

Final Plugin Structure

@your-org/code-quality-plugin/
├── package.json                ← Professional manifest
├── README.md                   ← Usage documentation
├── CHANGELOG.md                ← Change history
├── agents/
│   ├── quality-reviewer.md     ← Code reviewer (read-only)
│   └── quality-implementer.md  ← Fix implementer
└── skills/
    └── team-conventions.md     ← Shared conventions

Step 1: Initialize the Package

mkdir -p ~/plugins-workshop/code-quality-plugin
cd ~/plugins-workshop/code-quality-plugin

mkdir -p agents skills

Create the package.json:

{
  "name": "@your-org/code-quality-plugin",
  "version": "1.0.0",
  "description": "Code quality plugin for Claude Code. Includes quality-reviewer (read-only analysis), quality-implementer (applies fixes), and team-conventions skill.",
  "claudeCodePlugin": true,
  "files": [
    "agents",
    "skills"
  ],
  "keywords": [
    "claude-code",
    "plugin",
    "code-quality",
    "reviewer",
    "linting",
    "conventions"
  ],
  "author": "Your Name <you@email.com>",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/your-org/code-quality-plugin"
  },
  "engines": {
    "node": ">=18.0.0"
  }
}

Initialize git:

git init
echo "node_modules/" > .gitignore
git add .
git commit -m "Initial plugin scaffold"

Step 2: Create the Quality Reviewer

This agent analyzes code without modifying it. It produces structured reports with severity, exact location, and actionable recommendations. It uses the team-conventions skill's conventions as its evaluation criteria.

Create agents/quality-reviewer.md:

---
name: quality-reviewer
description: Analyzes code for quality issues, security vulnerabilities, and convention violations. Read-only agent that produces actionable reports with severity levels. Uses team-conventions skill as evaluation criteria.
tools: Read, Glob, Grep
model: sonnet
maxTurns: 25
---

## Role

You are a senior code reviewer. You analyze codebases for quality
issues, security vulnerabilities, and convention violations. You
NEVER modify files — you only read, analyze, and report.

Your reviews are thorough but focused. You prioritize issues that
have real impact over stylistic nitpicks.

## Knowledge

Load the `team-conventions` skill. Apply those conventions as your
primary evaluation criteria. When the project has a CLAUDE.md,
merge its conventions with team-conventions (project-specific rules
take precedence).

## Review Process

1. **Discover project structure**
   - Use Glob to map the directory tree
   - Read CLAUDE.md if it exists
   - Identify the tech stack (language, framework, patterns)

2. **Scope the review**
   - If given specific files/directories, focus there
   - If given the full project, prioritize: API routes, data models,
     auth logic, then utilities and helpers
   - Skip generated files, node_modules, vendor/

3. **Analyze each file against criteria**
   - Code quality: complexity, duplication, naming, dead code
   - Security: secrets, injection, auth bypass, input validation
   - Conventions: check against team-conventions and CLAUDE.md
   - Architecture: separation of concerns, dependency direction

4. **Classify findings by severity**
   - CRITICAL: Security vulnerability or data loss risk
   - WARNING: Code quality issue that will cause problems
   - INFO: Style or convention suggestion

5. **Generate actionable report**

## What Makes a Good Finding

A good finding has:
- Exact file and line reference
- Clear description of the problem
- Why it matters (risk or consequence)
- Specific fix recommendation
- Which convention it violates (if applicable)

A bad finding:
- "Code could be improved" (vague)
- "Consider refactoring" (no specific action)
- Style preferences without convention backing

## Output Format

### Code Quality Review

**Project:** [detected tech stack]
**Scope:** [files/directories reviewed]
**Conventions applied:** [team-conventions + CLAUDE.md rules found]
**Files analyzed:** [count]
**Summary:** Critical: [n] | Warning: [n] | Info: [n]

---

#### Critical Issues

**[C1]** `[file]:[line]`
- **Issue:** [clear description]
- **Risk:** [what could go wrong]
- **Convention:** [which rule is violated, or "security best practice"]
- **Fix:** [specific action to take]

---

#### Warnings

**[W1]** `[file]:[line]`
- **Issue:** [description]
- **Impact:** [technical debt, maintainability, performance]
- **Convention:** [rule reference]
- **Suggestion:** [recommended change]

---

#### Info

**[I1]** `[file]:[line]` — [brief observation and suggestion]

---

#### Positive Patterns Found
- [well-implemented pattern worth noting]

---

### Implementer Handoff

For each CRITICAL and WARNING, structured for the quality-implementer:

| ID | File | Line | Action Required | Convention |
|----|------|------|-----------------|------------|

**Priority order:** [C1, C2, ..., W1, W2, ...]

Step 3: Create the Quality Implementer

This agent receives implementation or correction tasks and executes them following the team conventions. It can work independently or receive the reviewer's output as guidance.

Create agents/quality-implementer.md:

---
name: quality-implementer
description: Implements code changes and fixes following team conventions. Can work from reviewer reports or direct task descriptions. Reports all changes with rationale and convention references.
tools: Read, Write, Edit, Glob, Grep, Bash
model: sonnet
maxTurns: 30
---

## Role

You are a senior developer responsible for implementing code changes
that meet team quality standards. You receive either:
- Direct implementation tasks ("create endpoint X")
- Fix lists from the quality-reviewer ("fix issues C1, W2, W3")

In both cases, you follow team conventions strictly and report
every change with rationale.

## Knowledge

Load the `team-conventions` skill. These are your implementation
standards. When the project has a CLAUDE.md, merge its conventions
(project-specific rules take precedence over team-conventions).

## Implementation Process

### For Direct Tasks

1. Read CLAUDE.md and examine existing code patterns
2. Plan the implementation (state your plan before writing code)
3. Implement following conventions and existing patterns
4. Verify: run linter/tests if available (Bash)
5. Report all changes

### For Reviewer Fix Lists

1. Read the reviewer's report (Implementer Handoff section)
2. Process fixes in priority order (Critical first, then Warning)
3. For each fix:
   a. Read the file and understand the context
   b. Apply the fix following the stated convention
   c. Verify the fix doesn't break adjacent code
   d. If the fix requires changes in other files, make them
4. Report each fix applied

## Implementation Standards

### Code Quality
- Functions: single responsibility, max 40 lines
- Naming: match project conventions (read 3 existing files first)
- Error handling: every operation that can fail has error handling
- No dead code: remove commented-out code, unused imports
- Type safety: add types where the project uses them

### File Organization
- Discover project structure before creating files
- Place new files where similar files exist
- Follow the project's module/package organization
- If unsure, check CLAUDE.md or ask

### Dependencies
- Prefer built-in/existing utilities over new dependencies
- If a new dependency is needed, document why
- Check if a similar utility already exists in the project

## When Fixing Reviewer Issues

### Mapping severity to action
- **CRITICAL:** Fix immediately, no questions asked
- **WARNING:** Fix unless there's a documented reason not to
- **INFO:** Fix only if explicitly asked

### What to do when unsure
- If the fix is ambiguous, state both options and pick the safer one
- If the fix could break other code, note the risk in the report
- If the fix requires a design decision, escalate in the report

## Output Format

### Implementation Report

**Task type:** [Direct implementation | Reviewer fixes]
**Conventions applied:** [team-conventions + CLAUDE.md rules]

#### Changes Applied

**[1]** `[file]`
- **Action:** [created | modified | deleted]
- **What:** [description of the change]
- **Why:** [rationale — which convention, what problem it solves]
- **Convention:** [specific rule from team-conventions]
```diff
- [old code]
+ [new code]

[2] [file]

  • ...

Verification

  • Linter: [ran / not available — result]
  • Tests: [ran / not available — result]
  • Manual check: [what I verified manually]

Decisions Made

  • [decision] — [rationale]

Remaining Issues

  • [anything not fixed and why]

Status: COMPLETE | PARTIAL (with explanation)


---

## Step 4: Create the Conventions Skill

This skill is the shared source of truth between the reviewer and the implementer. Both reference it, both apply it. That's how consistency is guaranteed: the reviewer detects violations of the same rules the implementer follows when fixing.

Create `skills/team-conventions.md`:

```markdown
---
name: team-conventions
description: Shared team conventions for code quality, API design, naming, error handling, and file organization. Used by quality-reviewer and quality-implementer as the primary evaluation and implementation standard.
---

## Naming Conventions

### Files
- Components/Classes: PascalCase (`UserProfile.tsx`, `OrderService.py`)
- Utilities/helpers: camelCase (JS/TS) or snake_case (Python)
- Test files: same name as source + `.test` or `_test` suffix
- Config files: lowercase with dots (`tsconfig.json`, `pyproject.toml`)

### Code
- Variables: camelCase (JS/TS) or snake_case (Python)
- Constants: UPPER_SNAKE_CASE
- Classes: PascalCase
- Functions: camelCase (JS/TS) or snake_case (Python)
- Private: prefix with underscore in Python, # in JS/TS
- Boolean variables: prefix with is/has/should/can

### API Endpoints
- URLs: kebab-case (`/user-profiles`, not `/userProfiles`)
- Collections: plural nouns (`/users`, not `/user`)
- Nested resources: `/users/{id}/posts`
- Actions: verb as sub-resource (`/orders/{id}/cancel`)

## Code Structure

### Functions
- Maximum 40 lines per function
- Single responsibility: one function does one thing
- Max 4 parameters; use options object beyond that
- Return early for guard clauses (avoid deep nesting)
- Max 3 levels of nesting

### Files
- Maximum 300 lines per file
- One class/component per file (with exceptions for tightly coupled)
- Imports organized: stdlib → third-party → local (blank line between)
- Exports at the bottom or alongside definitions (be consistent)

### Error Handling
- Catch specific errors, never catch-all without re-throwing
- Custom error classes with error codes
- Log errors with context (what operation, what input)
- API error responses: `{ "error": { "code": "...", "message": "..." } }`
- Never expose stack traces or internal details in API responses

## API Design

### Request/Response
- All endpoints have typed request and response schemas
- Response envelope: `{ "data": {...}, "meta": {...} }`
- Error envelope: `{ "error": { "code": "...", "message": "...", "details": [...] } }`
- Use appropriate HTTP status codes (don't return 200 for errors)

### Pagination
- Cursor-based for large collections
- Query: `?cursor=<opaque>&limit=20`
- Max limit: 100
- Response includes `next_cursor` in meta

### Authentication
- Bearer token in Authorization header
- Consistent auth middleware/dependency
- Protected endpoints return 401 (not authenticated) or 403 (not authorized)

## Testing

### Structure
- Test file mirrors source file path
- Test names: describe what is tested and expected outcome
- Arrange-Act-Assert pattern
- No test interdependencies (each test is independent)

### Coverage Expectations
- Business logic: 80%+ coverage
- API endpoints: integration tests for happy path + error cases
- Utilities: unit tests for edge cases
- UI components: render tests + interaction tests

## Security

### Input Validation
- Validate ALL external input at the API boundary
- Use schema validation (Pydantic, Zod, Joi)
- Sanitize strings: trim whitespace, normalize unicode
- Validate IDs format before database queries

### Secrets
- NEVER hardcode secrets, API keys, or passwords
- Use environment variables
- Never log secrets (even partially)
- .env files in .gitignore

### Data
- Parameterized queries only (prevent SQL injection)
- Hash passwords with bcrypt (never store plaintext)
- Sanitize user input in HTML output (prevent XSS)

Step 5: Create the README

Create README.md:

# @your-org/code-quality-plugin

Code quality plugin for Claude Code with quality-reviewer (read-only analysis)
and quality-implementer (applies fixes) sharing team-conventions as standard.

## Installation

```bash
claude plugins add @your-org/code-quality-plugin
# or from local: claude plugins add ./path/to/code-quality-plugin

Agents

quality-reviewer

Read-only analysis: quality, security, conventions. Usage: "Use quality-reviewer to analyze src/ for code quality issues"

quality-implementer

Implements fixes following conventions. Usage: "Use quality-implementer to fix the critical issues from this review: [paste]"

Skills

team-conventions

Naming, structure, error handling, API design, testing, security standards.

Workflow

  1. Run quality-reviewer → get structured report
  2. Pass Critical/Warning items to quality-implementer
  3. Verify fixes

Respects CLAUDE.md (project rules override team-conventions). Requires Claude Code (latest) + Node.js 18+.


---

## Step 6: Create the CHANGELOG

Create `CHANGELOG.md`:

```markdown
# Changelog

## [1.0.0] — 2026-03-13

### Added
- quality-reviewer agent: read-only code analysis with structured reports
- quality-implementer agent: implements fixes following team conventions
- team-conventions skill: shared naming, structure, API, testing, security rules
- README with usage instructions
- Plugin manifest with claudeCodePlugin support

Step 7: Verify the Structure

find . -type f -not -path './.git/*' -not -path './node_modules/*'

Expected output:

./package.json
./README.md
./CHANGELOG.md
./.gitignore
./agents/quality-reviewer.md
./agents/quality-implementer.md
./skills/team-conventions.md

Pre-testing checklist

✅ package.json has claudeCodePlugin: true
✅ package.json has files: ["agents", "skills"]
✅ package.json has version: "1.0.0"
✅ agents/quality-reviewer.md has valid YAML frontmatter
✅ agents/quality-implementer.md has valid YAML frontmatter
✅ skills/team-conventions.md has valid YAML frontmatter
✅ quality-reviewer only has Read, Glob, Grep (can't modify)
✅ quality-implementer has Read, Write, Edit, Glob, Grep, Bash
✅ Both agents reference team-conventions in their system prompt
✅ No hardcoded paths in any agent file
✅ README.md documents installation and usage

Step 8: Local Testing

Install in a test project

cd ~/your-test-project

claude plugins add ~/plugins-workshop/code-quality-plugin

Verify the installation

claude plugins list

Expected output:

Installed plugins:
  @your-org/code-quality-plugin (1.0.0) — local
    agents: quality-reviewer, quality-implementer
    skills: team-conventions

Test 1: Reviewer loads and analyzes

Inside the session: "Use quality-reviewer to analyze this project. Focus on the API files."

Verify: the reviewer is invoked, discovers the structure with Glob, reads CLAUDE.md, produces a report with the defined format (Critical/Warning/Info), references the skill's conventions, doesn't modify files, and includes the "Implementer Handoff" table.

Test 2: Implementer executes

"Use quality-implementer to create a helper function that validates email format. Follow the team conventions."

Verify: the implementer reads the project before implementing, follows team-conventions naming conventions, creates the file in the correct directory, produces a report with changes and rationale.

Test 3: review → fix flow

"First, use quality-reviewer to analyze src/. Then, use quality-implementer to fix the Critical and Warning issues."

Verify: the reviewer produces findings with the handoff table, the implementer processes those findings, the fixes follow the same conventions the reviewer used to detect them.

Test 4: The skill's conventions are applied

"Use quality-reviewer to analyze a specific file. I want to see which conventions it applies."

Verify: the reviewer mentions specific rules from the skill (naming, error handling), the findings reference the violated convention, it doesn't invent conventions that aren't in the skill.

Step 9: Iterate on the Plugin

Common adjustments after testing

If the reviewer produces too many INFO findings:

Add to the reviewer's agent file:

## Severity Threshold

Default: Report Critical and Warning. Include Info only when
explicitly asked ("include info-level findings").

When reviewing a large codebase (50+ files), limit to:
- Max 10 Critical findings
- Max 15 Warning findings
- Info: suppressed unless asked

If the implementer doesn't follow the conventions consistently:

Reinforce in the agent file:

## MANDATORY Convention Check

Before writing ANY code:
1. List the 3 most relevant conventions from team-conventions
2. State how each applies to this specific task
3. Only then write the code

After writing code, verify:
- Does the naming match convention? [yes/no + which rule]
- Is error handling per convention? [yes/no + which rule]
- Is the file in the right location? [yes/no + which pattern]

If the skill's conventions are too generic for your team:

Customize skills/team-conventions.md with more specific rules for your stack. The generic conventions are a starting point — your team should adapt them.

Commit the plugin after adjustments

cd ~/plugins-workshop/code-quality-plugin
git add .
git commit -m "Refine agent files after testing"

Step 10: Publish to a Local Registry

Option A: Verdaccio (recommended for teams)

Start verdaccio (if it's not running):

verdaccio &

Create a user (first time):

npm adduser --registry http://localhost:4873

Publish:

cd ~/plugins-workshop/code-quality-plugin

npm publish --registry http://localhost:4873

Expected output:

npm notice
npm notice 📦  @your-org/code-quality-plugin@1.0.0
npm notice Tarball Contents
npm notice 1.2kB  package.json
npm notice 2.8kB  README.md
npm notice 680B   CHANGELOG.md
npm notice 3.1kB  agents/quality-reviewer.md
npm notice 2.9kB  agents/quality-implementer.md
npm notice 2.4kB  skills/team-conventions.md
npm notice === Tarball Details ===
npm notice name:          @your-org/code-quality-plugin
npm notice version:       1.0.0
npm notice
+ @your-org/code-quality-plugin@1.0.0

Verify the publication:

npm view @your-org/code-quality-plugin --registry http://localhost:4873

Install from the registry in another project:

cd ~/another-project

claude plugins add @your-org/code-quality-plugin --registry http://localhost:4873

Option B: Install directly from a local path

If you don't want to use verdaccio:

cd ~/your-project

claude plugins add ~/plugins-workshop/code-quality-plugin

It works the same. The difference: it only works on your machine, not on your colleagues'.

Option C: npm pack + share the tarball

To share without a registry:

cd ~/plugins-workshop/code-quality-plugin

npm pack

Generates your-org-code-quality-plugin-1.0.0.tgz. Share this file and the recipient installs it with:

claude plugins add ./your-org-code-quality-plugin-1.0.0.tgz

Step 11: Verify Installation from the Registry

After publishing and installing from the registry (not from a local path), verify that everything works identically:

claude plugins list
Installed plugins:
  @your-org/code-quality-plugin (1.0.0) — registry
    agents: quality-reviewer, quality-implementer
    skills: team-conventions

Note that it now says "registry" instead of "local."

Repeat the 4 tests from Step 8 to confirm that the published plugin works the same as the local version.

Manual Alternative: Installation Script

If claude plugins isn't available:

#!/bin/bash
# install.sh — Manual installation of code-quality-plugin
set -e
PLUGIN_DIR="$(cd "$(dirname "$0")" && pwd)"
TARGET="${1:-.}"

mkdir -p "$TARGET/.claude/agents" "$TARGET/.claude/skills"
cp "$PLUGIN_DIR/agents/"*.md "$TARGET/.claude/agents/"
cp "$PLUGIN_DIR/skills/"*.md "$TARGET/.claude/skills/"
echo "Installed: quality-reviewer, quality-implementer, team-conventions"

Usage: chmod +x install.sh && ./install.sh ~/my-project

Common Errors and Solutions

Error 1: "The reviewer doesn't apply the skill's conventions"

Symptom: The reviewer's report doesn't mention team-conventions conventions. It analyzes with generic judgment.

Cause: The agent file doesn't reference the skill explicitly, or Claude Code doesn't automatically associate skills from the same plugin with its agents.

Solution:

Reinforce the reference in the reviewer's agent file:

## Knowledge (CRITICAL)

You MUST load and apply the `team-conventions` skill before
any review. This skill defines your evaluation criteria:
- Naming: check files, variables, endpoints against conventions
- Structure: check function length, nesting, file organization
- Error handling: check against the error handling standard
- API design: check response format, status codes, pagination
- Security: check input validation, secrets, data handling

If you cannot load the skill, state this in your report header.

Error 2: "The implementer creates files in the wrong directory"

Symptom: The implementer puts a new file where it doesn't belong according to the project structure.

Cause: The implementer didn't examine the existing structure before creating files.

Solution:

Add to the system prompt:

## MANDATORY: Discover Before Create

Before creating ANY new file:
1. Glob the project to understand directory structure
2. Find 3 existing files similar to what you'll create
3. Note their location pattern
4. Place your new file following the same pattern
5. If no similar files exist, check CLAUDE.md for guidance
6. State in your report: "Placed at [path] because [pattern found]"

Error 3: "npm publish fails with 'You do not have permission'"

Symptom: A permission error when publishing a scoped package.

Cause: Scoped packages (@org/name) require special permissions on public npm.

Solution:

# For public npm — you need to be a member of the org
npm publish --access public

# For verdaccio — create a user first
npm adduser --registry http://localhost:4873
npm publish --registry http://localhost:4873

Error 4: "Plugin installs but the agents have generic names"

Symptom: The agents appear as reviewer and implementer without the quality- prefix.

Cause: The name field in the YAML frontmatter doesn't have the prefix.

Solution:

Verify that the frontmatter has the correct name:

---
name: quality-reviewer    # NOT "reviewer"
---

The name in the frontmatter is what Claude Code uses to identify the agent.

Error 5: "The review → fix flow loses context"

Symptom: The implementer doesn't receive the reviewer's findings, or receives them in a hard-to-process format.

Cause: The reviewer's "Implementer Handoff" format isn't structured enough.

Solution:

The handoff table must be parseable:

### Implementer Handoff

| ID | File | Line | Action Required | Convention |
|----|------|------|-----------------|------------|
| C1 | src/api/users.py | 45 | Add input validation | Security: Input Validation |
| W1 | src/utils/format.py | 12 | Rename to snake_case | Naming: Functions |

The implementer reads this table and processes it row by row.

Error 6: "npm pack doesn't include agents/ or skills/"

Symptom: The generated tarball doesn't contain the plugin directories.

Cause: The files field in package.json doesn't list them, or a .npmignore excludes them.

Solution:

# Verify the tarball contents
npm pack
tar -tzf *.tgz

# It should show:
# package/package.json
# package/README.md
# package/agents/quality-reviewer.md
# package/agents/quality-implementer.md
# package/skills/team-conventions.md

If a directory is missing:

  1. Verify that "files" in package.json includes "agents" and "skills"
  2. Verify that there's no .npmignore excluding those directories
  3. Verify that the files actually exist in those directories

Error 7: "The reviewer and the implementer use different criteria"

Symptom: The reviewer detects a naming violation, but the implementer, when fixing, uses a different style than the reviewer expected.

Cause: Both agents interpret the conventions slightly differently.

Solution:

The conventions in team-conventions.md must be specific, not ambiguous:

# Ambiguous (generates different interpretations):
- Use consistent naming

# Specific (only one possible result):
- Functions: snake_case in Python, camelCase in JS/TS
- Example: get_user_profile (Python), getUserProfile (JS/TS)

Add concrete examples to each convention. Examples eliminate ambiguity.

Error 8: "I can't install a colleague's plugin from verdaccio"

Symptom: npm install against verdaccio fails with connection refused or 404.

Cause: The colleague published to their local verdaccio, not a shared one.

Solution:

To share via verdaccio, the registry must be on an accessible server:

# On the shared server
verdaccio --listen 0.0.0.0:4873

# Colleagues configure
npm set registry http://server:4873

If there's no shared server, use the npm pack + share tarball option, or publish to GitHub Packages.

Project Resources

  1. Claude Code Sub-Agents (Anthropic Docs) — Agent files and YAML frontmatter
  2. Create Custom Subagents — Agent file reference
  3. Claude Code CLI Reference — Plugin commands
  4. Verdaccio Documentation — Local npm registry
  5. npm publish — Publishing npm packages
  6. Semantic Versioning — Versioning standard

Connection to the Next Module

You've created a complete plugin with two agents and a shared skill. You packaged it, tested it, and published it. But the plugin has a limitation: it's static. The agents do what their system prompt says and nothing more. They don't react to events, don't activate automatically, don't integrate with external tools beyond what Claude Code provides.

Module 6: Advanced Hooks and Headless SDK adds exactly those capabilities. Advanced hooks (SessionStart, PostToolUse, TaskCompleted) let your plugins react to events — the reviewer can activate automatically when an agent creates a new file. The headless SDK lets you invoke your agents from Python or TypeScript scripts — your plugin becomes a programmatic API.

The agent files you created here are the foundation. In module 6, you'll add hooks that automate their invocation and an SDK that lets you control them from external code. The plugin goes from "manual tool" to "automated system."

Summary

  • You built a complete plugin with quality-reviewer + quality-implementer + team-conventions
  • The quality-reviewer analyzes code in read-only mode and produces reports with severity, convention references, and a handoff table for the implementer
  • The quality-implementer applies fixes or implements features following the shared skill's conventions
  • team-conventions is the shared source of truth — naming, structure, error handling, API design, security
  • The review → fix flow works because both agents use the same conventions as the criteria
  • The plugin installs with one command (claude plugins add) and the agents load automatically
  • Three distribution options: verdaccio (teams), public npm (open source), npm pack + tarball (ad-hoc)
  • The README.md documents installation, available agents, workflows, and configuration
  • The agent files are generic — they discover the project structure dynamically, work in any codebase
  • Everything is copy-paste ready — you can create this plugin right now with the files from this capsule

Next module: Module 6 (Advanced Hooks and Headless SDK) adds automation and programmatic control to everything you built. Advanced hooks activate your agents automatically on events. The headless SDK lets you invoke plugins from Python and TypeScript scripts. Your plugin goes from a manual tool to an automated system.

← Previous4. Dynamic Loading and Versioning — Loading, Semver, and RegistriesNext →1. Module Introduction — Hooks as the Nervous System, the SDK as Programmatic Control