Lab Build Your Own

Lab: Build Your Own

(Skill)    (Plugin)

Track: Skills + Plugins | Level: Intermediate | Time: 45 minutes

This page combines the hands-on content from skills/03-build-your-first-skill.ipynb and plugins/03-build-your-first-plugin.ipynb into a single walkthrough. By the end you will have built a working skill and packaged it inside a plugin.

---

Part 1: Building a Skill

Step 1: Plan

Before writing anything, answer these questions:

Question	Example
Name	test-file-generator
What does it do?	Generate test files for source code
When is it used?	Creating tests, TDD workflow, coverage improvement
What inputs does it need?	Source file path, language, test framework
What does it produce?	Test file with boilerplate and stubs
Which tools does it need?	Read, Write, Grep
Trigger phrases	"generate test", "create test file", "write tests"

Step 2: Write the Frontmatter

Use the 6 required fields. Keep allowed-tools as a quoted CSV string and scope any Bash access.

---
name: test-file-generator
description: |
  Generate test files for source code with framework-specific boilerplate.
  Use when: creating tests, improving coverage, TDD workflow.
  Triggers: generate test, create test file, write tests, test coverage.
allowed-tools: "Read,Write,Grep,Bash(npm:*)"
version: 1.0.0
author: Your Name <you@example.com>
license: MIT
model: sonnet
tags: [testing, tdd, coverage, productivity]
compatible-with: claude-code
---

Step 3: Write the Body

Include all 7 required sections. Target 150 lines or fewer.

# Test File Generator

## Overview
Analyzes source files to identify public functions and classes, then generates
a complete test file with correct framework boilerplate and test stubs.

## Prerequisites
- Source file must exist and be readable
- Test framework installed (pytest, Jest, Vitest, etc.)

## Instructions
### Step 1: Analyze Source File
Read the source file. Detect language and public API surface.

### Step 2: Determine Test Framework
Grep for framework config files (pytest.ini, jest.config.*, vitest.config.*).

### Step 3: Determine Test File Path
Follow conventions: Python src/mod.py -> tests/test_mod.py, JS src/mod.ts -> src/mod.test.ts.

### Step 4: Generate and Write Test File
Create the file with imports, setup, and one stub per public function.

## Output
Summary of created file, generated stubs, and suggested next steps.

## Error Handling
| Scenario | Action |
|----------|--------|
| Source file not found | Return error with path suggestion |
| Test file already exists | Ask user to overwrite or append |
| Cannot detect language | Ask user to specify |

## Examples
"Generate tests for src/calculator.py" -> creates tests/test_calculator.py
with stubs for add(), subtract(), multiply().

## Resources
- See ${CLAUDE_SKILL_DIR}/references/implementation.md for full templates

Step 4: Validate

Run your skill through the validation checks before saving:

• Name is kebab-case (^[a-z0-9-]+$)
• All 6 required frontmatter fields present
• allowed-tools is CSV, Bash is scoped
• Version is SemVer (3 parts)
• All 7 required body sections present
• Body under 150 lines (or 500 max with PDA)
• Purpose statement under 400 characters
• Uses ${CLAUDE_SKILL_DIR} not absolute paths

Step 5: Save

mkdir -p .claude/skills/test-file-generator
# Save your SKILL.md to:
# .claude/skills/test-file-generator/SKILL.md

Claude Code will auto-discover the skill on next launch.

Step 6: Test

1. Discovery: ask Claude "list available skills" -- yours should appear
2. Auto-invocation: say "generate tests for myfile.py" -- should trigger the skill
3. Slash command: type /test-file-generator myfile.py
4. Error handling: try a nonexistent file -- should get a helpful message

---

Part 2: Building a Plugin

A plugin packages one or more skills (plus optional commands and docs) into an installable unit.

Step 1: Plan the Plugin

Field	Value
Name	code-review-toolkit
Purpose	Automated code review with security and style checks
Skills	security-checker, style-analyzer
Commands	/review

Step 2: Create Directory Structure

code-review-toolkit/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   ├── security-checker/
│   │   └── SKILL.md
│   └── style-analyzer/
│       └── SKILL.md
├── commands/
│   └── review.md
├── README.md
└── LICENSE

Step 3: Write plugin.json

{
  "name": "code-review-toolkit",
  "version": "1.0.0",
  "description": "Automated code review with security scanning and style analysis",
  "author": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "license": "MIT",
  "keywords": ["code-review", "security", "style", "quality"],
  "category": "security",
  "repository": "https://github.com/you/code-review-toolkit"
}

Required fields: name, version, description, author, license, keywords.

Step 4: Write Skills

Each skill in skills/ follows the same SKILL.md format covered in Part 1. The security-checker skill might scan for OWASP Top 10 vulnerabilities; the style-analyzer skill might check against PEP 8 or ESLint rules. Both need their own frontmatter with 6 required fields and body with 7 required sections.

Step 5: Write the Command

Commands are simpler than skills. They live in commands/ as Markdown files with minimal frontmatter:

---
description: Run comprehensive code review (security + style)
allowed-tools: Read, Grep, Bash(git:*)
---

Perform a comprehensive code review of the current file or directory.

1. Run the security-checker skill
2. Run the style-analyzer skill
3. Combine results into a unified report

The /review command becomes available in Claude's slash menu.

Step 6: Add Documentation

Every plugin needs a README.md (features, installation, usage) and a LICENSE file.

Step 7: Validate and Install

Check that:

• .claude-plugin/plugin.json is valid JSON with all required fields
• Every skill directory contains a valid SKILL.md
• README.md and LICENSE exist

Install by copying to the plugins directory:

cp -r code-review-toolkit ~/.claude/plugins/

Or use ccpi:

ccpi install code-review-toolkit

---

Common Mistakes

Mistake	Fix
allowed-tools as YAML array	Use quoted CSV string
Bare Bash in tools	Scope it: Bash(git:*), Bash(npm:*)
camelCase or snake_case name	Use kebab-case
Missing "Use when..." in description	Add trigger phrases for auto-activation
Body over 150 lines	Move content to references/ (PDA)
Absolute paths in body	Use ${CLAUDE_SKILL_DIR}
Missing body sections	Include all 7: Overview, Prerequisites, Instructions, Output, Error Handling, Examples, Resources

See Also

• Lab-Architecture -- understand SKILL.md anatomy first
• Skill-Template -- blank starter template
• Plugin-Structure -- plugin directory conventions
• Lab-Debugging -- fix common issues
• Quality-Standards -- the full grading rubric