npm package: @jameskruck/ivey-subagents
Description: Claude Code subagents for educational course development - accessibility, widget testing, and branding validation
Author: Ivey EdTech Lab
Latest version: 1.0.0

# Claude Code Subagents for Course Development

**Native Claude Code Subagents** - No API keys required! Uses your Claude Code subscription.

## What Are Subagents?

Subagents are specialized AI assistants that work **inside Claude Code**. Unlike MCP servers (which require API keys and cost money), subagents use your Claude Code subscription at no additional cost.

## Available Subagents

### 1. Accessibility Auditor ♿
**Purpose**: WCAG 2.2 AA compliance checking with live WCAG verification

**Usage**: "Audit modules/module-1/index.html for accessibility"

**Tools**: Read, Glob, Grep, WebFetch
**Model**: Sonnet

**Special Capability**: Can fetch W3C documentation to verify WCAG criteria and requirements in real-time

### 2. Widget Tester 🧪
**Purpose**: Test interactive widgets with 3 student personas (Sarah, James, Maria)

**Usage**: "Test the fan engagement lab widget"

**Tools**: Read, Glob
**Model**: Sonnet

### 3. Branding Checker 🎨
**Purpose**: Validate Canvas LMS or Uplimit platform branding

**Usage**: "Check branding for modules/module-2/outline.html"

**Tools**: Read, Glob
**Model**: Sonnet

## Installation

### Option 1: NPM (Easiest - Like aitmpl.com)

Install agents with a single command (no download required):

```bash
# Install single agent
npx @jameskruck/ivey-subagents --agent=accessibility-auditor
npx @jameskruck/ivey-subagents --agent=widget-tester
npx @jameskruck/ivey-subagents --agent=branding-checker

# Install all agents at once
npx @jameskruck/ivey-subagents --agent=all

# Show help
npx @jameskruck/ivey-subagents --help
```

Then restart Claude Code and start using!

### Option 2: Manual Installation

1. **Copy subagent files** to your Claude Code agents directory:

```bash
# Windows
copy .agents\subagents\*.md %USERPROFILE%\.claude\agents\

# Mac/Linux
cp .agents/subagents/*.md ~/.claude/agents/
```

2. **Restart Claude Code** - Subagents load on startup

### Option 3: Installation Script

```bash
# Windows
.agents\subagents\install.bat

# Mac/Linux
bash .agents/subagents/install.sh
```

## How to Use

### Natural Language Invocation

Claude Code automatically delegates to the appropriate subagent:

```
"Audit modules/module-1/index.html for WCAG 2.2 compliance"
→ Uses accessibility-auditor subagent

"Test modules/module-1/widgets/fan-engagement-lab.html"
→ Uses widget-tester subagent

"Check if this matches Uplimit branding guidelines"
→ Uses branding-checker subagent
```

### Explicit Invocation

You can also request a specific subagent:

```
"Use the accessibility-auditor subagent on this file"
"Have the widget-tester check this interactive tool"
```

## Benefits vs. MCP Servers

| Feature | Subagents | MCP Servers |
|---------|-----------|-------------|
| **Cost** | ✅ Free (Claude Code subscription) | ❌ API costs ($0.01-1.00 per run) |
| **Setup** | ✅ Copy files, restart | ⚠️ Config + API keys |
| **Natural Language** | ✅ Yes | ✅ Yes |
| **Custom Tools** | ❌ No (uses Read, Glob, etc.) | ✅ Yes |
| **Speed** | ✅ Fast | ⚡ Slightly faster |

**Recommendation**: Use subagents for most tasks. Only use MCP servers if you need custom tools or want to run agents outside Claude Code.

## File Structure

```
.agents/subagents/
├── README.md (this file)
├── accessibility-auditor.md
├── widget-tester.md
├── branding-checker.md
└── install.bat / install.sh
```

## Subagent Format

Each subagent is a Markdown file with YAML frontmatter:

```markdown
---
name: accessibility-auditor
description: When to use this subagent
tools: Read, Glob, Grep
model: sonnet
---

Detailed instructions for the subagent...
```

## Creating New Subagents

1. Create a new `.md` file in `.agents/subagents/`
2. Add YAML frontmatter with name, description, tools, model
3. Write detailed instructions for the subagent
4. Copy to `~/.claude/agents/`
5. Restart Claude Code

See [Claude Code Subagents Documentation](https://docs.claude.com/en/docs/claude-code/sub-agents) for details.

## Troubleshooting

**Subagent not working?**
- Restart Claude Code (subagents load on startup only)
- Check file is in `~/.claude/agents/` directory
- Verify YAML frontmatter is valid

**Which subagent is being used?**
- Claude Code automatically selects based on your request
- Check the response to see which subagent was invoked
- You can explicitly request a specific subagent

**Want to modify a subagent?**
1. Edit the file in `~/.claude/agents/`
2. Restart Claude Code
3. Test with a simple request

## Examples

### Accessibility Audit
```
User: "Audit modules/module-1/index.html for accessibility"

Claude: [Uses accessibility-auditor subagent]

# Accessibility Audit: modules/module-1/index.html

**Compliance Score**: 92% (WCAG 2.2 AA)

## Critical Issues (1)

### 1. Missing Skip Navigation Styles
- **WCAG**: 2.4.1 Bypass Blocks
- **Line**: 159
...
```

**With WebFetch:**
```
User: "Is WCAG 2.4.13 Focus Appearance still the correct criterion?"

Claude: [Uses accessibility-auditor with WebFetch]
Let me verify the current WCAG 2.2 requirements...

[Fetches https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance]

Yes, WCAG 2.4.13 Focus Appearance (Level AA) requires:
- 2px minimum perimeter
- 3:1 contrast ratio against background
- Focus indicator must be visible
...
```

### Widget Testing
```
User: "Test the fan engagement lab widget"

Claude: [Uses widget-tester subagent]

# Widget Test Report: Fan Engagement Lab

**Overall UX Score**: 85/100

## Persona Testing Results

### Sarah (Quick Learner) ⚡
**Experience**: Sarah opens the widget and immediately...
...
```

### Branding Check
```
User: "Check if this file matches Uplimit branding"

Claude: [Uses branding-checker subagent]

# Branding Consistency Report

**Platform Detected**: Uplimit (95% confidence)
**Overall Compliance**: 78/100
...
```

## Additional Resources

- **Claude Code Documentation**: https://docs.claude.com/en/docs/claude-code/sub-agents
- **WCAG 2.2 Guidelines**: https://www.w3.org/WAI/WCAG22/quickref/
- **Uplimit Branding**: `Project Knowledge/Uplimit/styles 1.css`

---

**Course**: Business of Marketing in Sport
**Updated**: October 6, 2025
**Version**: 1.0.0