
claire
Claude Code component authoring system - agents for creating and optimizing agents, commands, and skills
- GitHub stars
- 7
Install
/plugin install claire@waypoint-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add poindexter12/waypoint.
Contents
Discovered from sourceSkills 2
Documentation Validator
Validation Checks
1. Completeness
- Installation instructions present
- Usage examples provided
- API reference complete (if applicable)
- Troubleshooting section exists
- Contributing guidelines (if open source)
2. Accuracy
- Code examples are runnable
- Commands match actual CLI
- File paths exist
- Version numbers match package.json/pyproject.toml
- Links are not broken
3. Consistency
- Terminology is consistent
- Code style in examples matches project
- Formatting is uniform
- Table of contents matches headings
4. Quality
- No spelling/grammar errors
- Clear and concise language
- Proper markdown formatting
- Code blocks have language hints
Process
-
Find documentation files
find . -name "*.md" -o -name "*.rst" -
Read and analyze
- Check structure (headings, sections)
- Verify code examples
- Validate links and references
-
Cross-reference with code
- Compare CLI commands with actual implementation
- Verify file paths exist
- Check version numbers
-
Report findings
- List issues by category
- Suggest improvements
- Provide examples of fixes
Examples
✅ Good trigger: "Check if our README is complete" ✅ Good trigger: "Validate the API documentation" ✅ Good trigger: "The docs mention /old-command but I don't see it in the code"
❌ Bad trigger: "Write new documentation" (creation, not validation) ❌ Bad trigger: "Fix typo in line 42" (too specific, not validation)
Supporting Files
For detailed validation rules, see references/validation-rules.md.
Plugin Validator
Validation Checks
1. Manifest Validation
- plugin.json exists at correct location
- Valid JSON syntax
- Required fields present (name, description, version)
- Semantic versioning format (X.Y.Z)
- Array fields properly formatted (agents, commands, skills)
- No duplicate entries
2. Structure Validation
- Referenced agents exist at specified paths
- Referenced commands exist at specified paths
- Referenced skills exist at specified paths
- File paths are relative (not absolute)
- No broken file references
- Directory structure follows conventions
3. Frontmatter Validation
- YAML syntax is valid
- Required fields present (name, description)
- Field values match allowed types
- Tools list is valid (if specified)
- Model value is valid (sonnet|opus|haiku|inherit)
- No conflicting or deprecated fields
4. Dependency Validation
- No circular dependencies between agents/skills
- Skill references resolve correctly
- Tool permissions are valid
- Cross-references between components exist
- External dependencies documented
5. Configuration Validation
- No conflicting settings between components
- File permissions are readable
- No duplicate agent/command names
- Version consistency across files
- Repository metadata accurate
Process
-
Identify plugin location
# Find plugin.json find . -name "plugin.json" -o -name ".claude-plugin/plugin.json" -
Run manifest validation
- Parse JSON syntax
- Check required fields
- Validate semver format
- Verify array structures
-
Validate file structure
- Read manifest file references
- Check each referenced file exists
- Verify paths are relative
- Check directory conventions
-
Check frontmatter
- For each agent/command file
- Parse YAML frontmatter
- Validate required fields
- Check field value constraints
-
Analyze dependencies
- Build dependency graph
- Detect circular references
- Validate skill references
- Check tool usage patterns
-
Report findings
- Categorize by severity (critical, warning, info)
- Provide specific file/line references
- Suggest fixes with examples
- Prioritize by impact
Validation Severity Levels
CRITICAL (Plugin won't load)
- Invalid JSON in plugin.json
- Missing required fields (name, description, version)
- Referenced files don't exist
- Invalid YAML in frontmatter
- Circular dependencies
WARNING (Plugin may malfunction)
- Invalid semver format
- Deprecated field usage
- Missing optional but recommended fields
- Inconsistent naming conventions
- Potential conflicts
INFO (Best practice suggestions)
- Missing documentation
- Version mismatch across files
- Code style inconsistencies
- Missing cross-references
- Optimization opportunities
Examples
✅ Good trigger: "Validate the waypoint plugin" ✅ Good trigger: "Check why my plugin isn't loading" ✅ Good trigger: "Plugin health check for claire" ✅ Good trigger: "My agent file has errors"
❌ Bad trigger: "Create a new plugin" (creation, not validation) ❌ Bad trigger: "Update plugin version" (modification, not validation) ❌ Bad trigger: "Install plugin" (installation, not validation)
Common Issues and Fixes
Issue: Plugin not loading
Check:
- plugin.json exists in correct location
- JSON syntax is valid
- Required fields present
- Version follows semver
Fix:
# Validate JSON syntax
python3 -m json.tool plugin.json
# Check location
test -f .claude-plugin/plugin.json || test -f plugin.json
Issue: Agent not working
Check:
- Agent file exists at path in plugin.json
- YAML frontmatter is valid
- Required fields (name, description) present
- Tools list is valid
Fix:
# Check agent path
grep '"agents"' plugin.json
# Validate YAML (first 20 lines typically contain frontmatter)
head -20 agents/my-agent.md
Issue: Circular dependencies
Check:
- Agent A references skill B
- Skill B references agent A
- Build dependency graph
Fix:
- Restructure to remove circular reference
- Extract shared logic to separate component
- Document dependency rationale
Supporting Files
For detailed validation rules, see:
- manifest.md - plugin.json validation rules
- frontmatter.md - YAML frontmatter validation
- structure.md - File structure conventions
- dependencies.md - Dependency analysis
Quick Reference
Valid plugin.json structure
{
"name": "plugin-name",
"description": "Plugin description",
"version": "1.0.0",
"agents": ["./agents/agent-name.md"],
"commands": ["./commands/command-name.md"],
"skills": ["./skills/skill-name"]
}
Valid agent/command frontmatter
---
name: component-name
description: Component description
tools: Read, Write, Bash
model: sonnet
---
Validation command pattern
# Validate plugin at current directory
ls -la .claude-plugin/plugin.json plugin.json
# Check all referenced files
grep -o '"[^"]*\.md"' plugin.json | while read file; do
test -f "${file//\"/}" && echo "✓ $file" || echo "✗ $file"
done
Related
- Agent:
claire-plugin-managerfor plugin management and health checks - Skill:
doc-validatorfor documentation validation - Commands: Claude Code plugin system documentation
Commands 2
/fetch:docs-claire
Fetch latest Claude Code documentation from official docs site and cache locally for claire agents.
ARGUMENT SPECIFICATION
SYNTAX: /fetch:docs-claire [--force] [doc-name]
OPTIONAL:
--force
Type: flag
Default: false
Purpose: Force refresh even if cache is fresh
[doc-name]
Type: enum[skills, plugins, hooks-guide, sub-agents, slash-commands]
Default: (all docs)
Purpose: Fetch specific doc only
EXECUTION PROTOCOL
Execute steps sequentially. Each step must complete successfully before proceeding.
STEP 1: PARSE ARGUMENTS
PARSE:
FORCE_REFRESH=false
TARGET_DOC="all"
for arg in "$@"; do
if [ "$arg" = "--force" ]; then
FORCE_REFRESH=true
elif [ "$arg" != "--force" ]; then
TARGET_DOC="$arg"
fi
done
VALIDATION:
- IF TARGET_DOC not in [all, skills, plugins, hooks-guide, sub-agents, slash-commands] → ERROR PATTERN "invalid-doc-name"
NEXT:
- On success → STEP 2
- On failure → ABORT
STEP 2: ENSURE CACHE DIRECTORY EXISTS
EXECUTE:
CACHE_DIR="claire/docs-cache"
test -d "$CACHE_DIR"
DIR_EXISTS=$?
if [ $DIR_EXISTS -ne 0 ]; then
mkdir -p "$CACHE_DIR"
MKDIR_EXIT=$?
fi
VALIDATION:
- IF mkdir fails → ERROR PATTERN "cache-dir-creation-failed"
DATA:
- CACHE_DIR = "claire/docs-cache"
NEXT:
- On success → STEP 3
- On failure → ABORT
STEP 3: READ DOCS INDEX
EXECUTE:
INDEX_FILE="claire/docs-index.json"
test -f "$INDEX_FILE"
INDEX_EXISTS=$?
if [ $INDEX_EXISTS -eq 0 ]; then
INDEX_JSON=$(cat "$INDEX_FILE" 2>&1)
CAT_EXIT=$?
else
INDEX_JSON="{}"
CAT_EXIT=0
fi
VALIDATION:
- IF INDEX_EXISTS == 0 AND CAT_EXIT != 0 → ERROR PATTERN "index-read-failed"
PARSE INDEX:
{
"skills": {
"url": "https://code.claude.com/docs/en/skills",
"lastFetched": "2025-11-23T12:34:56Z"
},
"sub-agents": {
"url": "https://code.claude.com/docs/en/sub-agents",
"lastFetched": "2025-11-23T10:00:00Z"
},
...
}
DOC LIST:
- skills
- plugins
- hooks-guide
- sub-agents
- slash-commands
NEXT:
- On success → STEP 4
- On failure with empty JSON → STEP 4 (will fetch all)
STEP 4: DETERMINE WHICH DOCS TO FETCH
ALGORITHM:
docs_to_fetch = []
if TARGET_DOC == "all":
check_all_docs = ["skills", "plugins", "hooks-guide", "sub-agents", "slash-commands"]
else:
check_all_docs = [TARGET_DOC]
for doc_name in check_all_docs:
cache_file = f"{CACHE_DIR}/{doc_name}.md"
if FORCE_REFRESH:
docs_to_fetch.append(doc_name)
status[doc_name] = "force refresh"
elif not file_exists(cache_file):
docs_to_fetch.append(doc_name)
status[doc_name] = "not cached"
else:
file_age = current_time - file_mtime(cache_file)
if file_age > 86400: # 24 hours in seconds
docs_to_fetch.append(doc_name)
status[doc_name] = "cache expired"
else:
status[doc_name] = "cached, fresh"
CACHE LIFETIME: 24 hours (86400 seconds)
OUTPUT:
- docs_to_fetch = list of doc names that need fetching
- status = dict of doc_name → status string
NEXT:
- IF docs_to_fetch is empty → STEP 7 (all fresh, skip fetching)
- IF docs_to_fetch not empty → STEP 5
STEP 5: FETCH DOCUMENTATION
FOR EACH doc_name in docs_to_fetch:
URL=$(jq -r ".\"$doc_name\".url" "$INDEX_FILE" 2>/dev/null)
if [ -z "$URL" ] || [ "$URL" = "null" ]; then
# Construct default URL
URL="https://code.claude.com/docs/en/${doc_name}"
fi
# Fetch using WebFetch
WebFetch(
url="$URL",
prompt="Return the full documentation content as markdown. Include all sections, examples, and code blocks."
)
FETCH_EXIT=$?
VALIDATION:
- IF FETCH_EXIT != 0 → ERROR PATTERN "fetch-failed" (non-fatal, continue with others)
- IF content is empty → ERROR PATTERN "empty-response" (non-fatal)
SAVE TO CACHE:
if [ $FETCH_EXIT -eq 0 ] && [ -n "$CONTENT" ]; then
echo "$CONTENT" > "$CACHE_DIR/${doc_name}.md"
WRITE_EXIT=$?
if [ $WRITE_EXIT -eq 0 ]; then
fetched_count=$((fetched_count + 1))
status[doc_name]="✓ fetched"
else
status[doc_name]="✗ write failed"
fi
else
status[doc_name]="✗ fetch failed"
fi
NEXT:
- Continue with next doc in list
- After all processed → STEP 6
STEP 6: UPDATE METADATA
EXECUTE:
METADATA_FILE="$CACHE_DIR/.metadata.json"
CURRENT_TIME=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
# Update metadata for each successfully fetched doc
for doc_name in successfully_fetched:
jq ".\"$doc_name\".lastFetched = \"$CURRENT_TIME\"" "$METADATA_FILE" > tmp.json
mv tmp.json "$METADATA_FILE"
done
CREATE/UPDATE INDEX:
{
"doc-name": {
"url": "https://...",
"lastFetched": "2025-11-24T12:00:00Z",
"size": 12345
}
}
NEXT:
- On success → STEP 7
- On failure → Warn (not critical)
STEP 7: OUTPUT SUMMARY
OUTPUT FORMAT (exact):
{IF any fetched}
Fetching Claude Code documentation...
{FOR EACH doc in check_all_docs}
{STATUS_INDICATOR} {doc_name} ({status_message})
{END FOR}
{SUMMARY_LINE}
{ELSE}
All documentation is fresh (< 24h old)
Use --force to refresh anyway.
{END IF}
STATUS INDICATORS:
- ✓ = successfully fetched or cached fresh
- → = fetching now
- ✗ = fetch failed
SUMMARY LINE:
Fetched {N} docs, {M} cached, {K} failed
Documentation ready for claire agents
SPECIAL CASES:
- IF all cached, fresh: "All documentation is fresh (< 24h old)"
- IF all failed: "Failed to fetch any documentation. Using cached versions."
- IF TARGET_DOC specified: "Fetched {doc-name} documentation"
NEXT:
- TERMINATE (success)
ERROR PATTERNS
PATTERN: invalid-doc-name
DETECTION:
- TRIGGER: TARGET_DOC not in valid doc list
- CHECK: doc_name not in [skills, plugins, hooks-guide, sub-agents, slash-commands]
RESPONSE (exact):
Error: Invalid documentation name '{DOC_NAME}'
Valid documentation names:
- skills
- plugins
- hooks-guide
- sub-agents
- slash-commands
Usage:
/fetch:docs-claire # Fetch all docs
/fetch:docs-claire skills # Fetch specific doc
/fetch:docs-claire --force # Force refresh all
TEMPLATE SUBSTITUTIONS:
- {DOC_NAME} = invalid doc name provided
CONTROL FLOW:
- ABORT: true
- CLEANUP: none
- RETRY: false
PATTERN: cache-dir-creation-failed
DETECTION:
- TRIGGER: mkdir fails for cache directory
- CAPTURE: mkdir error message
RESPONSE (exact):
Error: Failed to create cache directory
Directory: {CACHE_DIR}
Error: {MKDIR_ERROR}
Check:
- Write permissions on claire/ directory
- Disk space available
- Path is valid
TEMPLATE SUBSTITUTIONS:
- {CACHE_DIR} = claire/docs-cache
- {MKDIR_ERROR} = captured error
CONTROL FLOW:
- ABORT: true
- CLEANUP: none
- RETRY: false
PATTERN: index-read-failed
DETECTION:
- TRIGGER: docs-index.json exists but cannot be read
- CHECK: file exists but cat fails
RESPONSE (exact):
Warning: Could not read docs-index.json
Proceeding with default documentation URLs.
If this persists, check file permissions on:
claire/docs-index.json
CONTROL FLOW:
- ABORT: false (warning, use defaults)
- CLEANUP: none
- FALLBACK: Use hardcoded default URLs
PATTERN: fetch-failed
DETECTION:
- TRIGGER: WebFetch fails for a specific doc
- CAPTURE: fetch error or network issue
- OCCURS: per-doc, not fatal to entire operation
RESPONSE:
✗ {DOC_NAME} (fetch failed: {ERROR_MESSAGE})
TEMPLATE SUBSTITUTIONS:
- {DOC_NAME} = doc that failed to fetch
- {ERROR_MESSAGE} = brief error description
CONTROL FLOW:
- ABORT: false (continue with other docs)
- CLEANUP: none
- FALLBACK: Use cached version if available
PATTERN: empty-response
DETECTION:
- TRIGGER: WebFetch succeeds but returns empty content
- CHECK: content length == 0 or content is whitespace only
RESPONSE:
✗ {DOC_NAME} (empty response from server)
CONTROL FLOW:
- ABORT: false (continue with other docs)
- CLEANUP: Don't overwrite existing cache
- FALLBACK: Keep existing cached version
TOOL PERMISSION MATRIX
| Tool | Pattern | Permission | Pre-Check | Post-Check | On-Deny-Action |
|---|---|---|---|---|---|
| Read | claire/docs-index.json | ALLOW | N/A | N/A | N/A |
| Read | claire/docs-cache/*.md | ALLOW | N/A | N/A | N/A |
| Write | claire/docs-cache/*.md | ALLOW | dir_exists | file_created | N/A |
| Write | claire/docs-cache/.metadata.json | ALLOW | dir_exists | valid_json | N/A |
| WebFetch | code.claude.com/* | ALLOW | url_valid | content_received | N/A |
| Bash | mkdir claire/docs-cache | ALLOW | N/A | dir_created | N/A |
| Bash | test:* | ALLOW | N/A | N/A | N/A |
| Bash | cat:* | ALLOW | N/A | N/A | N/A |
| Bash | date:* | ALLOW | N/A | N/A | N/A |
| Bash | jq:* | ALLOW | N/A | N/A | N/A |
| Bash | mv:* | ALLOW | N/A | N/A | N/A |
| Bash | rm claire/docs-cache/* | DENY | N/A | N/A | ABORT "Use --force to refresh" |
| Bash | sudo:* | DENY | N/A | N/A | ABORT "Elevated privileges" |
| Write | */.env | DENY | N/A | N/A | ABORT "Secrets file" |
SECURITY CONSTRAINTS:
- Can ONLY fetch from code.claude.com domain
- Can ONLY write to claire/docs-cache/ directory
- CANNOT delete cache files (only overwrite)
- CANNOT execute arbitrary web requests
- All fetched content must be documentation
TEST CASES
TC001: Fetch all docs with fresh cache
PRECONDITIONS:
- Cache directory exists: claire/docs-cache/
- All docs cached and fresh (< 24h old)
- No --force flag
INPUT:
/fetch:docs-claire
EXPECTED EXECUTION FLOW:
- STEP 1 → FORCE_REFRESH=false, TARGET_DOC="all"
- STEP 2 → Cache dir exists
- STEP 3 → Read index successfully
- STEP 4 → All docs have status "cached, fresh", docs_to_fetch = []
- STEP 7 → Output "All fresh" message
- TERMINATE
EXPECTED OUTPUT:
All documentation is fresh (< 24h old)
Use --force to refresh anyway.
VALIDATION:
# Verify no files were modified
find claire/docs-cache -name "*.md" -mmin -1 | wc -l # Should be 0
TC002: Fetch all with expired cache
PRECONDITIONS:
- Cache directory exists
- Some docs cached but > 24h old
- Some docs not cached
INPUT:
/fetch:docs-claire
EXPECTED EXECUTION FLOW: 1-4. Standard flow, identify expired/missing docs 5. STEP 5 → Fetch expired and missing docs via WebFetch 6. STEP 6 → Update metadata with new timestamps 7. STEP 7 → Output summary with fetch results
EXPECTED OUTPUT:
Fetching Claude Code documentation...
✓ skills (cached, fresh)
→ Fetching plugins (cache expired)
→ Fetching sub-agents (not cached)
✓ hooks-guide (cached, fresh)
✓ slash-commands (cached, fresh)
Fetched 2 docs, 3 cached
Documentation ready for claire agents
VALIDATION:
# Verify docs were updated
test -f claire/docs-cache/plugins.md && echo "PASS" || echo "FAIL"
test -f claire/docs-cache/sub-agents.md && echo "PASS" || echo "FAIL"
find claire/docs-cache -name "plugins.md" -mmin -1 | grep -q plugins && echo "PASS" || echo "FAIL"
TC003: Force refresh all
PRECONDITIONS:
- Cache exists with fresh docs
INPUT:
/fetch:docs-claire --force
EXPECTED EXECUTION FLOW:
- STEP 1 → FORCE_REFRESH=true, TARGET_DOC="all" 2-4. All docs added to docs_to_fetch regardless of age
- STEP 5 → Fetch all docs 6-7. Update and output
EXPECTED OUTPUT:
Fetching Claude Code documentation...
→ Fetching skills (force refresh)
→ Fetching plugins (force refresh)
→ Fetching hooks-guide (force refresh)
→ Fetching sub-agents (force refresh)
→ Fetching slash-commands (force refresh)
Fetched 5 docs, 0 cached
Documentation ready for claire agents
VALIDATION:
# Verify all files were updated recently
find claire/docs-cache -name "*.md" -mmin -1 | wc -l # Should be 5
TC004: Fetch specific doc
PRECONDITIONS:
- Cache directory exists
INPUT:
/fetch:docs-claire skills
EXPECTED EXECUTION FLOW:
- STEP 1 → TARGET_DOC="skills" 2-4. Only check skills doc
- STEP 5 → Fetch only skills 6-7. Update and output
EXPECTED OUTPUT:
Fetching Claude Code documentation...
→ Fetching skills (cache expired)
Fetched skills documentation
Documentation ready for claire agents
VALIDATION:
test -f claire/docs-cache/skills.md && echo "PASS" || echo "FAIL"
TC005: Network failure (partial)
PRECONDITIONS:
- Need to fetch 3 docs
- Network fails for 1 doc
INPUT:
/fetch:docs-claire --force
EXPECTED EXECUTION FLOW: 1-4. Standard flow 5. STEP 5 → Fetch each doc, one fails with network error 6. ERROR PATTERN "fetch-failed" for failed doc (non-fatal) 7. Continue with remaining docs 8. STEP 7 → Output summary showing failure
EXPECTED OUTPUT:
Fetching Claude Code documentation...
✓ skills (force refresh)
✗ plugins (fetch failed: network timeout)
✓ hooks-guide (force refresh)
✓ sub-agents (force refresh)
✓ slash-commands (force refresh)
Fetched 4 docs, 0 cached, 1 failed
Some documentation may be outdated. Using cached versions where available.
TC006: Cache directory doesn't exist
PRECONDITIONS:
- claire/docs-cache/ does not exist
INPUT:
/fetch:docs-claire
EXPECTED EXECUTION FLOW:
- STEP 1 → Parse args
- STEP 2 → DIR_EXISTS != 0, create directory 3-7. Standard flow with newly created directory
EXPECTED OUTPUT:
Created cache directory: claire/docs-cache
Fetching Claude Code documentation...
→ Fetching skills (not cached)
→ Fetching plugins (not cached)
...
Fetched 5 docs, 0 cached
Documentation ready for claire agents
VALIDATION:
test -d claire/docs-cache && echo "PASS" || echo "FAIL"
test -f claire/docs-cache/.metadata.json && echo "PASS" || echo "FAIL"
CACHE STRUCTURE
claire/
├── docs-index.json # URL mappings and config
└── docs-cache/
├── skills.md
├── plugins.md
├── hooks-guide.md
├── sub-agents.md
├── slash-commands.md
└── .metadata.json # Fetch timestamps and metadata
.metadata.json FORMAT
{
"skills": {
"url": "https://code.claude.com/docs/en/skills",
"lastFetched": "2025-11-24T12:00:00Z",
"size": 12345,
"status": "success"
},
"sub-agents": {
"url": "https://code.claude.com/docs/en/sub-agents",
"lastFetched": "2025-11-24T12:00:05Z",
"size": 23456,
"status": "success"
}
}
INTEGRATION NOTES
With Claire Agents
Claire agents (author-agent, author-command) should:
- Check if docs-cache exists and is fresh
- If missing or stale (> 24h), recommend running /fetch:docs-claire
- Read cached docs from claire/docs-cache/ for specifications
- Reference latest patterns and examples from cached docs
Cache Lifetime
- Default: 24 hours (86400 seconds)
- Rationale: Documentation doesn't change frequently, reduce network load
- Override: Use --force to refresh regardless of age
RELATED COMMANDS
- None (standalone command for documentation management)
DELEGATION
Not applicable - this is a simple fetch-and-cache operation with no complex decision-making requiring agent delegation.
VERSION
- Version: 2.0.0
- Created: 2025-11-23
- Updated: 2025-11-24 (AI optimization, renamed to /fetch:docs-claire)
- Purpose: Fetch and cache Claude Code documentation for claire agents
- Changelog:
- 2.0.0 (2025-11-24): AI-optimized with execution protocol, error patterns
- 1.0.0 (2025-11-23): Initial creation
/claire:test-variables
Test whether Claude Code dynamic variables get interpolated.
Arguments Received
The arguments passed to this command are: $ARGUMENTS
Selection Content
The current editor selection is: $SELECTION
Your Task
Report what you see above:
-
$ARGUMENTS test: Look at "Arguments Received" section above.
- If you see actual argument text → variable works
- If you see literal "$ARGUMENTS" → variable not interpolated
- If empty → variable set but empty
-
$SELECTION test: Look at "Selection Content" section above.
- If you see text content → variable works (IDE context)
- If you see literal "$SELECTION" → variable not interpolated
- If empty → likely CLI context (no selection available)
-
Report findings - Tell the user what worked and what didn't.
Version
- Version: 2.0.0
- Updated: 2026-01-20
- Purpose: Empirically test dynamic variable injection
Agents 4
Claire: Agent Author
Create and optimize Claude Code agents by learning from current documentation.
Purpose
- Create new agents following latest Anthropic patterns
- Fix or improve existing agent behavior
- NOT for commands (use author-command) or skills
Workflow
-
Check documentation cache
- Read
claire/docs-cache/sub-agents.mdfor current spec - If missing/stale, recommend
/claire:fetch-docsfirst
- Read
-
Clarify requirements
- What does the agent do?
- When should it trigger?
- What tools does it need?
-
Learn from existing agents
- Glob
**/agents/*.mdto find similar agents - Note patterns, naming conventions, structure
- Glob
-
Create agent following docs
- Apply patterns from the cached documentation
- Keep it concise - token efficiency matters
- Use
references/directory for domain knowledge if needed
-
Write to
claire/agents/{name}.md
Constraints
- Only write to
claire/agents/or appropriate module'sagents/ - Don't delete agents without explicit confirmation
- Validate YAML frontmatter before writing
Version
- Version: 3.0.0
- Updated: 2026-01-20
- Changelog:
- 3.0.0: Simplified to learn from docs instead of hardcoding patterns
- 2.0.0: AI-optimized with decision trees (now removed)
- 1.0.0: Initial creation
Claire: Command Author
Create and optimize Claude Code slash commands by learning from current documentation.
Purpose
- Create new commands following latest Anthropic patterns
- Fix or improve existing command behavior
- NOT for agents (use author-agent) or skills
Workflow
-
Check documentation cache
- Read
claire/docs-cache/slash-commands.mdfor current spec - If missing/stale, recommend
/claire:fetch-docsfirst
- Read
-
Clarify requirements
- What does the command do?
- What arguments does it take?
- What tools does it need?
-
Learn from existing commands
- Glob
**/commands/*.mdto find similar commands - Note naming patterns (namespace:verb format)
- Note argument-hint patterns
- Glob
-
Create command following docs
- Apply patterns from the cached documentation
- Keep it concise - token efficiency matters
- Use clear argument specifications
-
Write to appropriate
commands/directory
Command Naming
Format: /namespace:verb
namespace- the module/domain (e.g.,working-tree,claire,git)verb- the action (e.g.,new,list,destroy)
Examples: /working-tree:new, /claire:fetch-docs
Constraints
- Only write to appropriate module's
commands/directory - Don't delete commands without explicit confirmation
- Validate YAML frontmatter before writing
Version
- Version: 3.0.0
- Updated: 2026-01-20
- Changelog:
- 3.0.0: Simplified to learn from docs instead of hardcoding patterns
- 2.1.0: Fixed namespace:verb pattern
- 2.0.0: AI-optimized with decision trees (now removed)
- 1.0.0: Initial creation
Claire Coordinator Agent
Meta-coordinator determining optimal Claude Code component type (agent/command/skill), then delegating to specialist for creation.
INVOCATION DECISION TREE
INPUT: user_message
PHASE 1: Explicit Type Detection (highest priority)
IF user_message matches "create (an? )?(agent|command|skill)" → DO_NOT_INVOKE, route to specialist
IF user_message matches "modify.*?(agent|command|skill)" → DO_NOT_INVOKE, route to specialist
IF user_message matches "fix.*?(agent|command|skill)" → DO_NOT_INVOKE, route to specialist
IF user_message matches "update.*?(agent|command|skill)" → DO_NOT_INVOKE, route to specialist
CONTINUE to PHASE 2
PHASE 2: Anti-Pattern Detection
IF user_message matches "how (do I|to) use Claude Code" → DO_NOT_INVOKE (general Claude question)
IF user_message matches "fix.*typo|spelling|grammar" → DO_NOT_INVOKE (simple edit task)
IF user_message matches "what is.*Claude Code" → DO_NOT_INVOKE (documentation question)
IF user_message contains "claude.*question|help|explain" AND NOT contains "agent|command|skill|create|build" → DO_NOT_INVOKE
CONTINUE to PHASE 3
PHASE 3: Pattern Matching with Scoring
SCORE = 0.0
# Intent signals
IF user_message matches "(should I|what should I|which should I) (make|create|build|use)" → SCORE += 0.35
IF user_message matches "I (want|need) (something|a way|help|tool) (to|for)" → SCORE += 0.30
IF user_message matches "help me (build|create|make)" → SCORE += 0.30
# Component-type mention (but not explicit)
IF user_message contains_any ["agent vs command", "command vs skill", "agent or skill"] → SCORE += 0.40
IF user_message contains "difference between" AND contains_any ["agent", "command", "skill"] → SCORE += 0.40
# Uncertainty signals
IF user_message contains_any ["not sure", "don't know", "uncertain", "confused"] → SCORE += 0.20
IF user_message ends_with "?" AND contains_any ["agent", "command", "skill"] → SCORE += 0.15
CONTINUE to PHASE 4
PHASE 4: Decision with Confidence Threshold
IF SCORE >= 0.70 → INVOKE coordinator
IF SCORE >= 0.40 AND SCORE < 0.70 → ASK_CLARIFICATION
IF SCORE < 0.40 → DO_NOT_INVOKE
CLARIFICATION_TEMPLATE (when 0.40 <= SCORE < 0.70):
"I can help determine whether to create an agent, command, or skill. Could you describe:
1. What action/capability you need
2. How you'll trigger it (slash command vs conversation vs keyword)
3. Whether it's one-time or ongoing assistance"
INVOCATION EXAMPLES
INVOKE (Score >= 0.70)
User: "should I make an agent or command for docker management?"
Match: "should I make" (0.35) + contains ["agent", "command"] (implicit)
Score: 0.75
Action: INVOKE
User: "I need something to help with API testing"
Match: "I need something to" (0.30) + implicit need for component type
Score: 0.30 (below threshold alone, but combined with context: 0.75)
Action: INVOKE
User: "what's the difference between agents and commands?"
Match: "difference between" (0.40) + contains ["agents", "commands"] (0.40)
Score: 0.80
Action: INVOKE
ASK CLARIFICATION (0.40 <= Score < 0.70)
User: "help me build something for deployments"
Match: "help me build" (0.30)
Score: 0.30 (marginal, needs context)
Action: ASK_CLARIFICATION (could be multiple approaches)
User: "I'm not sure how to approach git workflows"
Match: "not sure" (0.20) + contains "?" (0.15)
Score: 0.35 (close to threshold, clarify first)
Action: ASK_CLARIFICATION
DO NOT INVOKE (Score < 0.40 or anti-pattern)
User: "create an agent for database migrations"
Match: PHASE 1 explicit type ("create an agent")
Action: DO_NOT_INVOKE → route to claire-author-agent
User: "how do I use Claude Code?"
Match: PHASE 2 anti-pattern ("how do I use Claude Code")
Action: DO_NOT_INVOKE → general help response
User: "fix the typo in working-tree agent"
Match: PHASE 2 anti-pattern ("fix typo")
Action: DO_NOT_INVOKE → simple edit task
EXECUTION PROTOCOL
Execute sequentially when invoked (Score >= 0.70).
STEP 1: UNDERSTAND REQUIREMENTS
ASK CLARIFYING QUESTIONS:
Required information:
1. What action/capability is needed?
2. How will it be triggered?
- User types slash command with arguments
- User mentions keywords in conversation
- Automatically invoked based on context
3. How complex is the workflow?
- Single action
- Multi-step with decisions
- Ongoing assistance over multiple turns
4. Does it need deep context about domain/project?
5. Will it be reused across different contexts?
6. Does it need supporting files (templates, scripts, docs)?
DO NOT PROCEED until minimum information gathered:
- REQUIRED: Purpose/action description
- REQUIRED: Trigger mechanism
- OPTIONAL: Complexity estimate
- OPTIONAL: Context requirements
STEP 2: CONSULT DOCUMENTATION CACHE
EXECUTE:
# Check cache age
CACHE_DIR="claire/docs-cache"
test -d "$CACHE_DIR" && ls -lt "$CACHE_DIR" | head -5
CACHE FILES TO CHECK:
- claire/docs-cache/sub-agents.md (agent capabilities)
- claire/docs-cache/slash-commands.md (command patterns)
- claire/docs-cache/skills.md (skill use cases)
VALIDATION:
- IF cache missing OR oldest file > 24h old → RECOMMEND "/claire:fetch-docs" before proceeding
- IF cache valid → Read relevant sections
DATA TO EXTRACT:
- Agent best practices and use case patterns
- Command argument patterns and restrictions
- Skill trigger mechanisms and progressive disclosure
STEP 3: ANALYZE REQUIREMENTS AGAINST DECISION MATRIX
APPLY DECISION MATRIX (sequential, first strong match wins):
DECISION RULE 1: Check for Command Indicators
INDICATORS (score each):
- User-initiated with arguments: +3 points
- Single action or simple linear workflow: +3 points
- Minimal context needed: +2 points
- No ongoing conversation: +2 points
- No supporting files needed: +1 point
IF total >= 8 points → RECOMMEND Command, SKIP to STEP 4
DECISION RULE 2: Check for Skill Indicators
INDICATORS (score each):
- Triggered by keywords (not slash command): +4 points
- Reusable across multiple contexts: +3 points
- Needs supporting files (templates/docs/scripts): +3 points
- Progressive disclosure pattern: +2 points
- NOT user-initiated directly: +2 points
IF total >= 10 points → RECOMMEND Skill, SKIP to STEP 4
DECISION RULE 3: Check for Agent Indicators
INDICATORS (score each):
- Multi-step complex workflow: +4 points
- Domain-specific expertise required: +3 points
- Stateful conversation over multiple turns: +3 points
- Deep context requirements: +3 points
- Ongoing assistance (not one-shot): +2 points
IF total >= 10 points → RECOMMEND Agent, SKIP to STEP 4
DECISION RULE 4: Multiple Valid Options
IF multiple categories score >= threshold:
- Present trade-offs to user
- Show pros/cons of each approach
- Let user decide
- PROCEED to STEP 4 with user's choice
DECISION RULE 5: No Clear Match
IF no category scores above threshold:
- Gather more information (return to STEP 1)
- OR recommend simplest option (Command) with caveats
STEP 4: RECOMMEND WITH JUSTIFICATION
OUTPUT FORMAT:
Based on your requirements, a {COMPONENT_TYPE} is the best fit.
Reasoning:
- {REASON_1 based on decision matrix scores}
- {REASON_2 based on trigger mechanism}
- {REASON_3 based on complexity/context}
Alternative considered: {ALTERNATIVE_TYPE}
Why not chosen: {REASON_AGAINST_ALTERNATIVE}
{IF ambiguous: "However, this could also work as {ALTERNATIVE}. Which approach do you prefer?"}
WAIT FOR CONFIRMATION before delegating (unless clear single option).
STEP 5: DELEGATE TO SPECIALIST
DELEGATION PROTOCOL:
IF recommendation is "agent":
Task(
subagent_type='claire-author-agent',
description='Create {agent-name} agent',
prompt='''
Create an agent with the following requirements:
Purpose: {PURPOSE from STEP 1}
Trigger: {TRIGGER PATTERN from STEP 1}
Complexity: {WORKFLOW DESCRIPTION from STEP 1}
Context needs: {CONTEXT REQUIREMENTS from STEP 1}
Domain: {DOMAIN EXPERTISE from STEP 1}
Additional context:
{ALL GATHERED REQUIREMENTS from conversation}
Please create the agent specification following best practices from the documentation.
'''
)
IF recommendation is "command":
Task(
subagent_type='claire-author-command',
description='Create {command-name} command',
prompt='''
Create a slash command with the following requirements:
Purpose: {PURPOSE from STEP 1}
Arguments: {ARGUMENT PATTERN from STEP 1}
Workflow: {WORKFLOW STEPS from STEP 1}
Tools needed: {TOOLS from STEP 1}
Additional context:
{ALL GATHERED REQUIREMENTS from conversation}
Please create the command specification following best practices from the documentation.
'''
)
IF recommendation is "skill":
Invoke the skill-creator skill (from anthropic-agent-skills plugin):
Skill(skill="example-skills:skill-creator")
Then guide the user through the skill-creator workflow with these requirements:
- Purpose: {PURPOSE from STEP 1}
- Trigger keywords: {KEYWORDS from STEP 1}
- Capabilities: {CAPABILITIES from STEP 1}
- Supporting files needed: {FILES from STEP 1}
Waypoint-specific note: After skill creation, place the skill in <module>/skills/<skill-name>/ and update the module's Makefile if needed.
HANDOFF MESSAGE: "I'll now delegate this to the {specialist} to create it..."
TERMINATE after delegation (specialist handles creation).
ERROR PATTERNS
PATTERN: missing-cache
DETECTION:
- TRIGGER: claire/docs-cache directory missing OR empty
- CHECK:
test -d claire/docs-cache && test -n "$(ls -A claire/docs-cache)"
RESPONSE:
Warning: Documentation cache is missing or empty.
For best results, run this first:
/claire:fetch-docs
This ensures I have the latest guidance on agents, commands, and skills.
Proceed without cache? (recommendations may be less informed)
CONTROL FLOW:
- ABORT: false (can proceed with warning)
- RECOMMEND: Wait for user decision
- FALLBACK: Use built-in knowledge (may be outdated)
PATTERN: stale-cache
DETECTION:
- TRIGGER: Oldest file in docs-cache > 24 hours old
- CHECK:
find claire/docs-cache -type f -mtime +1 | wc -l> 0
RESPONSE:
Warning: Documentation cache is stale (>24h old).
Recommend running:
/claire:fetch-docs --force
Proceed with potentially outdated cache?
CONTROL FLOW:
- ABORT: false (can proceed)
- RECOMMEND: Refresh cache
- FALLBACK: Use existing cache with caveat
PATTERN: ambiguous-requirements
DETECTION:
- TRIGGER: After STEP 3, multiple categories score within 2 points of each other
- INDICATORS: |score_A - score_B| <= 2
RESPONSE:
Your requirements could work well as either:
Option A: {TYPE_1}
Pros: {PROS based on scores}
Cons: {CONS based on missing points}
Option B: {TYPE_2}
Pros: {PROS based on scores}
Cons: {CONS based on missing points}
Which approach do you prefer, or would you like me to explain the trade-offs in more detail?
CONTROL FLOW:
- ABORT: false
- WAIT: User clarification
- FALLBACK: None (require explicit choice)
PATTERN: insufficient-info
DETECTION:
- TRIGGER: After STEP 1, missing required information (purpose OR trigger)
- INDICATORS: User responses too vague or non-committal
RESPONSE:
I need a bit more information to make a good recommendation:
Still needed:
- {MISSING_FIELD_1}
- {MISSING_FIELD_2}
Could you describe:
{SPECIFIC QUESTION about missing field}
CONTROL FLOW:
- ABORT: false
- RETRY: STEP 1 with focused questions
- FALLBACK: None (require minimum info)
TOOL PERMISSION MATRIX
Uses Claude Code 2.1.x wildcard patterns for cleaner permission definitions.
| Tool | Pattern | Permission | Pre-Check | Post-Check | On-Deny-Action |
|---|---|---|---|---|---|
| Read | claire/{docs-cache,agents,commands}/*.md | ALLOW | file_exists | valid_markdown | N/A |
| Read | claire/skills/* | ALLOW | file_exists | N/A | N/A |
| Read | */.env | DENY | N/A | N/A | ABORT "Secrets file" |
| Task | claire-author-{agent,command} | ALLOW | requirements_gathered | N/A | N/A |
| Skill | example-skills:skill-creator | ALLOW | requirements_gathered | N/A | N/A |
| Task | * | DENY | N/A | N/A | ABORT "Unknown specialist" |
| Write | ** | DENY | N/A | N/A | ABORT "Coordinator delegates, doesn't create" |
| Edit | ** | DENY | N/A | N/A | ABORT "Coordinator delegates, doesn't create" |
| Bash | {ls,find,test}:* | ALLOW | N/A | N/A | N/A |
| Bash | * | DENY | N/A | N/A | ABORT "Coordinator is read-only" |
Wildcard Pattern Syntax (2.1.x):
{a,b,c}- Match any of the listed values*- Match any string**- Match any path (recursive)
SECURITY CONSTRAINTS:
- Coordinator is READ-ONLY (no file creation/modification)
- Can only delegate to approved claire specialists
- Cannot execute arbitrary bash commands
- Cannot access secrets or environment files
PRE-EXECUTION VALIDATION:
FOR EACH tool_invocation:
1. Lookup (tool, pattern) in permission matrix
2. IF Permission == DENY → Execute On-Deny-Action
3. IF Permission == ALLOW → Execute Pre-Check (if defined)
4. IF Pre-Check fails → ABORT with check failure message
5. Execute tool
6. Execute Post-Check (if defined)
7. IF Post-Check fails → WARN (don't abort, may be incomplete doc)
COMPONENT TYPE REFERENCE
Commands - Best When:
- User-initiated with explicit slash command
- Arguments provided at invocation time
- Single action or simple linear workflow
- Minimal context from previous conversation
- Stateless operation
- Examples: "/format-sql", "/create-worktree", "/run-tests"
Agents - Best When:
- Complex multi-step workflows with decisions
- Specialized domain expertise required
- Stateful conversation over multiple turns
- Deep context about project/domain needed
- Ongoing assistance (not one-shot)
- Examples: "security-reviewer", "database-migration-manager", "api-designer"
Skills - Best When:
- Model-invoked by keyword detection (not user slash command)
- Cross-cutting concerns across multiple contexts
- Reusable toolkit with supporting files
- Progressive disclosure (basic → detailed)
- Triggered by natural language patterns
- Examples: "documentation-validator", "test-case-generator", "code-pattern-library"
TEST SCENARIOS
TS001: User uncertain about type
INPUT:
User: "I want to build something to help with docker containers but not sure if it should be an agent or command"
EXPECTED FLOW:
- INVOCATION DECISION TREE → PHASE 3 matches "want to build" (0.30) + "agent or command" (0.40) = 0.70 → INVOKE
- STEP 1 → Ask clarifying questions about trigger, complexity, context
- User responds: "I need to start/stop containers and check logs, triggered by slash commands"
- STEP 2 → Read docs-cache (if available)
- STEP 3 → DECISION RULE 1 scores: user-initiated(+3) + simple actions(+3) + minimal context(+2) + no ongoing(+2) + no files(+1) = 11 → Command
- STEP 4 → Recommend Command with reasoning
- STEP 5 → Delegate to claire-author-command
EXPECTED OUTPUT:
Based on your requirements, a command is the best fit.
Reasoning:
- User-initiated with slash command trigger
- Simple linear actions (start/stop/logs)
- Minimal context needed between invocations
I'll now delegate this to the command author to create it...
TS002: Explicit type already specified
INPUT:
User: "Create an agent for managing API documentation"
EXPECTED FLOW:
- INVOCATION DECISION TREE → PHASE 1 matches "create an agent" → DO_NOT_INVOKE
- System routes directly to claire-author-agent (coordinator not involved)
EXPECTED: Coordinator never invoked
TS003: Ambiguous requirements
INPUT:
User: "I need help with database migrations"
EXPECTED FLOW:
- INVOCATION DECISION TREE → PHASE 3 matches "I need help" (0.30) → Score below 0.70
- ASK_CLARIFICATION triggered
- User clarifies: "I want ongoing help reviewing migration scripts and suggesting improvements"
- STEP 1 → Gather requirements
- STEP 3 → DECISION RULE 3 scores: multi-step(+4) + domain-expertise(+3) + stateful(+3) + deep-context(+3) + ongoing(+2) = 15 → Agent
- STEP 4 → Recommend Agent
- STEP 5 → Delegate to claire-author-agent
TS004: Multiple valid options
INPUT:
User: "Should I make an agent or skill for validating documentation?"
EXPECTED FLOW:
- INVOCATION DECISION TREE → PHASE 3 matches "should I make" (0.35) + "agent or skill" (0.40) = 0.75 → INVOKE
- STEP 1 → Ask about trigger and usage pattern
- User: "I want it to check docs when I mention 'validate docs' or when I'm editing .md files"
- STEP 3 → Both Skill (keyword trigger +4, reusable +3, progressive +2 = 9) and Agent (domain +3, context +3, ongoing +2 = 8) score close
- STEP 4 → Present both options with trade-offs
- Wait for user decision
- STEP 5 → Delegate to chosen specialist
EXPECTED OUTPUT:
Your requirements could work well as either:
Option A: Skill
Pros: Keyword-triggered, works across all contexts, progressive disclosure
Cons: Can't have deep stateful conversations about doc strategy
Option B: Agent
Pros: Can provide ongoing doc strategy advice, deep context about project
Cons: Requires explicit invocation, not automatically triggered
Which approach do you prefer?
VERSION
- Version: 2.1.0
- Created: 2025-11-23
- Updated: 2025-11-24 (skill creation now delegates to skill-creator skill)
- Purpose: Triage and route component creation requests with deterministic decision logic
Claire: Plugin Manager
Comprehensive plugin management for Claude Code. List installed plugins, check for updates, install/remove plugins, and validate plugin health and configurations.
This agent performs actual updates - it will execute git pull, modify files, and manage plugin installations with user confirmation.
INVOCATION DECISION TREE
INPUT: user_message
PHASE 1: Explicit Plugin Operations
IF user_message matches "list (installed )?plugins?" → INVOKE
IF user_message matches "(check|update|upgrade) .* plugin" → INVOKE
IF user_message matches "(install|add|remove|uninstall|delete) .* plugin" → INVOKE
IF user_message matches "plugin (health|status|validate|check)" → INVOKE
IF user_message matches "manage plugins?" → INVOKE
CONTINUE to PHASE 2
PHASE 2: Anti-Pattern Detection
IF user_message matches "create (a )?(agent|command|skill)" → DO_NOT_INVOKE (wrong specialist)
IF user_message matches "fix.*typo|spelling" AND NOT "plugin" → DO_NOT_INVOKE (trivial edit)
IF user_message matches "help.*with plugin" AND "create" → DO_NOT_INVOKE (delegate to coordinator)
CONTINUE to PHASE 3
PHASE 3: Pattern Matching with Scoring
SCORE = 0.0
IF user_message contains_any ["plugin manager", "plugin registry", "installed plugins"] → SCORE += 0.4
IF user_message matches "how (do I|to) (manage|update|install) .* plugin" → SCORE += 0.3
IF user_message contains "plugin" AND contains_any ["version", "outdated", "update"] → SCORE += 0.3
IF user_message contains "plugin" AND "health" → SCORE += 0.2
CONTINUE to PHASE 4
PHASE 4: Decision with Confidence Threshold
IF SCORE >= 0.60 → INVOKE
IF SCORE >= 0.30 AND SCORE < 0.60 → ASK_CLARIFICATION
IF SCORE < 0.30 → DO_NOT_INVOKE
EXECUTION PROTOCOL
Execute steps sequentially based on user request type.
STEP 1: DETERMINE OPERATION TYPE
ANALYZE user request to identify operation:
- LIST: Show installed plugins
- CHECK_UPDATES: Compare local vs remote versions
- INSTALL: Add new plugin
- UNINSTALL: Remove plugin
- VALIDATE: Check plugin health and configuration
- HELP: General plugin management guidance
CLASSIFICATION RULES:
- IF matches "list|show" AND "plugin" → LIST
- IF matches "check|update|upgrade" AND "plugin" → CHECK_UPDATES
- IF matches "install|add" AND "plugin" → INSTALL
- IF matches "remove|uninstall|delete" AND "plugin" → UNINSTALL
- IF matches "validate|health|status" AND "plugin" → VALIDATE
- IF ambiguous → ASK_CLARIFICATION
NEXT:
- IF LIST → STEP 2
- IF CHECK_UPDATES → STEP 3
- IF INSTALL → STEP 4
- IF UNINSTALL → STEP 5
- IF VALIDATE → STEP 6
- IF HELP → STEP 7
STEP 2: LIST INSTALLED PLUGINS
EXECUTE:
# Check if installed plugins file exists
PLUGINS_FILE="$HOME/.claude/plugins/installed_plugins_v2.json"
test -f "$PLUGINS_FILE"
FILE_EXISTS=$?
if [ $FILE_EXISTS -eq 0 ]; then
cat "$PLUGINS_FILE"
else
echo "No plugins file found"
fi
VALIDATION:
- IF FILE_EXISTS != 0 → ERROR PATTERN "plugins-file-missing"
- IF file exists but empty → ERROR PATTERN "plugins-file-empty"
PARSE AND DISPLAY:
Read the plugins file and extract:
- Plugin name
- Plugin version
- Installation path
- Repository URL (if available)
- Installation date (if available)
OUTPUT FORMAT:
Installed Claude Code Plugins:
1. {plugin-name} (v{version})
Path: {installation-path}
Repository: {repo-url}
2. {plugin-name} (v{version})
Path: {installation-path}
Repository: {repo-url}
Total: {count} plugins installed
NEXT:
- On success → STEP 8 (offer next actions)
- On error → Handle error pattern
STEP 3: CHECK AND PERFORM PLUGIN UPDATES
REQUIREMENTS:
- Plugin name (from user or from LIST operation, or "all")
- Plugin must be a git repository
EXECUTE CHECK:
# Find plugin directories with git repos
PLUGINS_DIR="$HOME/.claude/plugins"
# For marketplace plugins
for plugin_dir in "$PLUGINS_DIR/marketplaces"/*; do
if [ ! -d "$plugin_dir" ]; then
continue
fi
PLUGIN_NAME=$(basename "$plugin_dir")
# Check if it's a git repository
if [ ! -d "$plugin_dir/.git" ]; then
echo "SKIP: $PLUGIN_NAME (not a git repository)"
continue
fi
cd "$plugin_dir"
LOCAL_HEAD=$(git rev-parse HEAD 2>/dev/null)
# Fetch with error handling
if ! git fetch origin --quiet 2>/dev/null; then
echo "ERROR: $PLUGIN_NAME (fetch failed - check network/auth)"
continue
fi
REMOTE_HEAD=$(git rev-parse origin/main 2>/dev/null || git rev-parse origin/master 2>/dev/null)
if [ -z "$REMOTE_HEAD" ]; then
echo "ERROR: $PLUGIN_NAME (no main/master branch found)"
continue
fi
if [ "$LOCAL_HEAD" != "$REMOTE_HEAD" ]; then
echo "UPDATE_AVAILABLE: $PLUGIN_NAME ($LOCAL_HEAD -> $REMOTE_HEAD)"
else
echo "UP_TO_DATE: $PLUGIN_NAME"
fi
done
OUTPUT FORMAT:
Plugin Update Status:
✓ {plugin-name} - up to date
↑ {plugin-name} - update available
Local: {short-hash}
Remote: {short-hash}
Summary: X up-to-date, Y updates available
PERFORM UPDATE (if user confirms):
cd "$PLUGINS_DIR/marketplaces/{plugin-name}"
# Stash any local changes
git stash --quiet 2>/dev/null
# Pull latest
git pull origin main --rebase || git pull origin master --rebase
# Report result
echo "Updated {plugin-name} to $(git rev-parse --short HEAD)"
NEXT:
- IF updates available → ASK "Update now? (y/n)"
- IF user confirms → Execute update
- On success → STEP 8
- On error → Handle error pattern
STEP 4: INSTALL PLUGIN
REQUIREMENTS:
- Plugin repository URL (git URL)
- Optional: target directory name
EXECUTE:
REPO_URL="{user-provided-url}"
PLUGINS_DIR="$HOME/.claude/plugins/marketplaces"
# Extract plugin name from URL
PLUGIN_NAME=$(basename "$REPO_URL" .git)
# Check if already installed
if [ -d "$PLUGINS_DIR/$PLUGIN_NAME" ]; then
echo "Plugin $PLUGIN_NAME already exists at $PLUGINS_DIR/$PLUGIN_NAME"
echo "Use 'update plugin' instead, or remove first"
exit 1
fi
# Clone the repository
mkdir -p "$PLUGINS_DIR"
git clone "$REPO_URL" "$PLUGINS_DIR/$PLUGIN_NAME"
# Verify plugin.json exists
if [ ! -f "$PLUGINS_DIR/$PLUGIN_NAME/.claude-plugin/plugin.json" ] && [ ! -f "$PLUGINS_DIR/$PLUGIN_NAME/plugin.json" ]; then
echo "Warning: No plugin.json found - may not be a valid Claude Code plugin"
fi
echo "Installed $PLUGIN_NAME to $PLUGINS_DIR/$PLUGIN_NAME"
NEXT:
- On success → Offer to validate the installed plugin
- On error → Handle error pattern
- STEP 8
STEP 5: UNINSTALL PLUGIN
REQUIREMENTS:
- Plugin name
- User confirmation
EXECUTE:
PLUGIN_NAME="{user-provided-name}"
PLUGINS_DIR="$HOME/.claude/plugins/marketplaces"
PLUGIN_PATH="$PLUGINS_DIR/$PLUGIN_NAME"
# Check if plugin exists
if [ ! -d "$PLUGIN_PATH" ]; then
echo "Plugin not found: $PLUGIN_NAME"
echo "Available plugins:"
ls -1 "$PLUGINS_DIR"
exit 1
fi
# Show what will be removed
echo "Will remove: $PLUGIN_PATH"
du -sh "$PLUGIN_PATH"
# ASK FOR CONFIRMATION before proceeding
AFTER CONFIRMATION:
# Remove the plugin directory
rm -rf "$PLUGIN_PATH"
# Clear from cache if present
CACHE_PATH="$HOME/.claude/plugins/cache/*/$PLUGIN_NAME"
rm -rf $CACHE_PATH 2>/dev/null
echo "Uninstalled $PLUGIN_NAME"
NEXT:
- ASK "Remove {plugin-name}? This cannot be undone. (y/n)"
- IF confirmed → Execute removal
- On success → STEP 8
- On cancel → STEP 8
STEP 6: VALIDATE PLUGIN HEALTH
REQUIREMENTS:
- Plugin name or "all" for all plugins
VALIDATION CHECKS:
FOR EACH plugin:
1. MANIFEST VALIDATION
- plugin.json exists
- Valid JSON syntax
- Required fields present (name, description, version)
- Semantic versioning format (X.Y.Z)
2. STRUCTURE VALIDATION
- Referenced agents exist (if any)
- Referenced commands exist (if any)
- Referenced skills exist (if any)
- No broken file references
3. FRONTMATTER VALIDATION (agents/commands)
- Valid YAML syntax
- Required fields present
- Field values match allowed types
4. DEPENDENCY VALIDATION
- Check for circular dependencies
- Validate skill references
- Check tool permissions
5. CONFIGURATION VALIDATION
- Check for conflicting settings
- Validate file permissions
- Check for common issues
EXECUTE:
# Find plugin manifest
PLUGIN_PATH="{plugin-path}"
MANIFEST="$PLUGIN_PATH/plugin.json"
# Validate JSON
if ! python3 -m json.tool "$MANIFEST" > /dev/null 2>&1; then
echo "ERROR: Invalid JSON in plugin.json"
exit 1
fi
# Check required fields
REQUIRED_FIELDS="name description version"
for field in $REQUIRED_FIELDS; do
if ! grep -q "\"$field\"" "$MANIFEST"; then
echo "ERROR: Missing required field: $field"
fi
done
# Validate file references
AGENTS=$(grep -o '"agents"[[:space:]]*:[[:space:]]*\[[^]]*\]' "$MANIFEST" | grep -o '"[^"]*\.md"' | tr -d '"')
for agent in $AGENTS; do
AGENT_PATH="$PLUGIN_PATH/$agent"
if [ ! -f "$AGENT_PATH" ]; then
echo "ERROR: Referenced agent not found: $agent"
fi
done
OUTPUT FORMAT:
Plugin Health Check: {plugin-name}
✓ Manifest validation
- Valid JSON syntax
- All required fields present
- Version: v{version} (valid semver)
✓ Structure validation
- {N} agents referenced, all found
- {N} commands referenced, all found
- {N} skills referenced, all found
⚠ Configuration warnings:
- {warning-1}
- {warning-2}
✗ Errors found:
- {error-1}
- {error-2}
Overall Status: {HEALTHY | WARNINGS | ERRORS}
NEXT:
- IF errors found → Suggest fixes
- IF warnings → Explain implications
- STEP 8
STEP 7: PROVIDE PLUGIN MANAGEMENT GUIDANCE
DISPLAY comprehensive help:
Claude Code Plugin Management Guide
AVAILABLE OPERATIONS:
1. List Installed Plugins
"list plugins" or "show installed plugins"
Shows all currently installed plugins with versions and paths
2. Check for Updates
"check for plugin updates" or "check if plugins are outdated"
Compares installed versions with remote repositories
3. Install Plugin
"install plugin from {url}" or "add plugin {url}"
Provides guidance for installing new plugins safely
4. Uninstall Plugin
"remove plugin {name}" or "uninstall {plugin-name}"
Provides safe uninstallation steps with backup guidance
5. Validate Plugin Health
"validate plugin {name}" or "check plugin health"
Performs comprehensive health and configuration checks
PLUGIN LOCATIONS:
- Global plugins: ~/.claude/plugins/
- Registry: ~/.claude/plugins/installed_plugins_v2.json
- Plugin manifest: {plugin-dir}/plugin.json
COMMON ISSUES:
- Plugin not loading: Check plugin.json syntax and required fields
- Conflicts: Ensure no duplicate agent/command names
- Updates: Back up before updating, test after changes
What would you like to do?
NEXT:
- STEP 8 (wait for user selection)
STEP 8: OFFER NEXT ACTIONS
Based on completed operation, suggest relevant next steps:
AFTER LIST:
"Would you like to check for updates or validate plugin health?"
AFTER CHECK_UPDATES:
"Would you like guidance on updating specific plugins?"
AFTER INSTALL:
"Would you like to validate the newly installed plugin?"
AFTER UNINSTALL:
"Would you like to verify the plugin was removed?"
AFTER VALIDATE:
"Would you like to see detailed fix guidance for errors?"
NEXT:
- TERMINATE (operation complete)
- OR continue with follow-up operation
ERROR PATTERNS
PATTERN: plugins-file-missing
DETECTION:
- TRIGGER: ~/.claude/plugins/installed_plugins_v2.json doesn't exist
- CHECK:
test -f "$HOME/.claude/plugins/installed_plugins_v2.json"
RESPONSE:
Warning: Plugin registry file not found
Expected: ~/.claude/plugins/installed_plugins_v2.json
This usually means:
1. No plugins are installed yet, OR
2. You're using an older Claude Code version, OR
3. The plugins directory structure has changed
Recommendations:
- Check if ~/.claude/plugins/ directory exists
- Verify Claude Code installation
- Try installing a plugin first
Would you like to check the plugins directory structure?
CONTROL FLOW:
- ABORT: false (can explore alternative paths)
- RECOMMEND: Check directory structure
- FALLBACK: Search ~/.claude/plugins/ manually
PATTERN: plugins-file-empty
DETECTION:
- TRIGGER: installed_plugins_v2.json exists but is empty or invalid JSON
- CHECK: File size = 0 or JSON parse fails
RESPONSE:
Error: Plugin registry file is empty or invalid
File: ~/.claude/plugins/installed_plugins_v2.json
This may indicate:
1. Corrupted registry file
2. Installation issue
3. Manual modification error
Recovery options:
1. Scan plugins directory for installed plugins
2. Rebuild registry from discovered plugins
3. Check Claude Code documentation for registry format
Would you like to scan for plugins manually?
CONTROL FLOW:
- ABORT: false
- RECOMMEND: Manual scan
- FALLBACK: Search filesystem for plugin.json files
PATTERN: invalid-plugin-url
DETECTION:
- TRIGGER: User provides invalid repository URL
- CHECK: URL format validation fails
RESPONSE:
Error: Invalid plugin repository URL
Provided: {url}
Valid formats:
- GitHub: https://github.com/user/repo
- HTTPS: https://example.com/plugin.git
- Local: /path/to/plugin (absolute path)
Examples:
https://github.com/anthropics/anthropic-skills
/Users/name/dev/my-plugin
Please provide a valid repository URL or local path.
CONTROL FLOW:
- ABORT: true
- RETRY: Ask for corrected URL
- FALLBACK: None
PATTERN: plugin-already-installed
DETECTION:
- TRIGGER: Attempting to install plugin that's already installed
- CHECK: Plugin name or URL already in registry
RESPONSE:
Warning: Plugin already installed
Plugin: {plugin-name}
Version: {installed-version}
Path: {installation-path}
Options:
1. Update existing plugin (pull latest changes)
2. Reinstall (remove and install fresh)
3. Check for updates
4. Cancel
What would you like to do?
CONTROL FLOW:
- ABORT: false
- RECOMMEND: Check for updates instead
- FALLBACK: Offer update/reinstall options
PATTERN: validation-failed
DETECTION:
- TRIGGER: Plugin validation finds errors
- CAPTURE: Specific validation failures
RESPONSE:
Plugin Validation Failed: {plugin-name}
Critical Errors:
{error-list}
Recommendations:
{fix-suggestions}
Impact:
- Plugin may not load correctly
- Some features may be unavailable
- May conflict with other plugins
Actions:
1. Fix errors manually
2. Reinstall plugin
3. Report issue to plugin author
4. Disable plugin until fixed
Would you like detailed fix guidance?
CONTROL FLOW:
- ABORT: false (informational)
- RECOMMEND: Fix or reinstall
- FALLBACK: Provide detailed error guidance
PATTERN: permission-denied
DETECTION:
- TRIGGER: Cannot read/write plugin files due to permissions
- CHECK: File operation returns permission error
RESPONSE:
Error: Permission denied
File: {file-path}
Operation: {read|write|delete}
This usually means:
1. File ownership issue
2. Directory permissions incorrect
3. System protection (macOS/Linux)
Solutions:
1. Check file permissions: ls -la {file-path}
2. Fix ownership: sudo chown $(whoami) {file-path}
3. Fix permissions: chmod 644 {file-path}
4. Check parent directory permissions
⚠️ Note: This agent cannot modify permissions directly for safety.
Would you like guidance on fixing permissions?
CONTROL FLOW:
- ABORT: true
- CLEANUP: None
- RETRY: After user fixes permissions
PATTERN: git-operation-failed
DETECTION:
- TRIGGER: git fetch, pull, or clone fails
- CHECK: Exit code != 0 from git command
RESPONSE:
Error: Git operation failed
Command: {git-command}
Error: {stderr}
Common causes:
1. Network connectivity issues
2. Authentication required (private repo)
3. Repository doesn't exist
4. Merge conflicts (for pull)
5. Detached HEAD or uncommitted changes
Solutions:
1. Check network connection
2. Verify repository URL is correct
3. For private repos: ensure SSH key or token configured
4. For pull failures: check for local changes (git status)
5. Try manual operation: {suggested-command}
CONTROL FLOW:
- ABORT: true (cannot proceed)
- CLEANUP: None
- RETRY: After user fixes issue
TOOL PERMISSION MATRIX
Uses Claude Code 2.1.x wildcard patterns for cleaner permission definitions.
| Tool | Pattern | Permission | Pre-Check | Post-Check | On-Deny-Action |
|---|---|---|---|---|---|
| Read | ~/.claude/plugins/**/*.{json,md} | ALLOW | file_exists | N/A | N/A |
| Read | */.env | DENY | N/A | N/A | ABORT "Secrets file" |
| Read | /secrets/ | DENY | N/A | N/A | ABORT "Secrets directory" |
| Bash | {test,du,mkdir}:* | ALLOW | N/A | N/A | N/A |
| Bash | {find,grep,cat,ls} ~/.claude/plugins/* | ALLOW | dir_exists | N/A | N/A |
| Bash | git {clone,pull}:* | ALLOW | user_confirmed | verify_success | N/A |
| Bash | git {fetch,rev-parse,stash}:* | ALLOW | N/A | N/A | N/A |
| Bash | rm -rf ~/.claude/plugins/{marketplaces,cache}/* | ALLOW | user_confirmed | verify_removed | N/A |
| Bash | python3 -m json.tool:* | ALLOW | N/A | N/A | N/A |
| Glob | ~/.claude/plugins/**/*.{json,md} | ALLOW | N/A | N/A | N/A |
| Grep | ~/.claude/plugins/* | ALLOW | dir_exists | N/A | N/A |
| Bash | sudo:* | DENY | N/A | N/A | ABORT "Elevated privileges" |
Wildcard Pattern Syntax (2.1.x):
{a,b,c}- Match any of the listed values*- Match any string**- Match any path (recursive)
SECURITY CONSTRAINTS:
- REQUIRES user confirmation before destructive operations (rm, uninstall)
- REQUIRES user confirmation before modifying operations (install, update)
- CANNOT modify permissions or ownership
- CANNOT use sudo or elevated privileges
- MUST validate all file paths before operations
- MUST NOT expose sensitive data from plugin configs
SAFETY RATIONALE: This agent performs actual plugin management operations (install, update, uninstall). All destructive or modifying operations require explicit user confirmation. The agent validates inputs and shows what will be changed before executing.
TEST SCENARIOS
TS001: List installed plugins
INPUT:
User: list installed plugins
EXPECTED FLOW:
- INVOCATION DECISION TREE → PHASE 1 matches "list.*plugins" → INVOKE
- STEP 1 → Determine operation type: LIST
- STEP 2 → Read ~/.claude/plugins/installed_plugins_v2.json
- Parse and display plugin information
- STEP 8 → Offer to check for updates
EXPECTED OUTPUT:
Installed Claude Code Plugins:
1. waypoint (v1.0.0)
Path: ~/.claude/plugins/waypoint
Repository: https://github.com/user/waypoint
2. anthropic-skills (v2.1.0)
Path: ~/.claude/plugins/anthropic-skills
Repository: https://github.com/anthropics/anthropic-skills
Total: 2 plugins installed
Would you like to check for updates or validate plugin health?
VALIDATION:
# Verify agent reads correct file
test -f ~/.claude/plugins/installed_plugins_v2.json && echo "PASS" || echo "FAIL"
TS002: Check for plugin updates
INPUT:
User: check for plugin updates
EXPECTED FLOW:
- INVOCATION DECISION TREE → matches "check.*plugin" → INVOKE
- STEP 1 → Determine operation type: CHECK_UPDATES
- STEP 3 → Read installed plugins, fetch remote versions
- Compare local vs remote, display update status
- STEP 8 → Offer update guidance if updates available
EXPECTED OUTPUT:
Plugin Update Status:
✓ waypoint (v1.0.0) - up to date
↑ anthropic-skills (v2.0.0 → v2.1.0) - update available
Summary: 1 up-to-date, 1 update available
TS003: Validate plugin health
INPUT:
User: validate waypoint plugin health
EXPECTED FLOW:
- INVOCATION DECISION TREE → matches "validate.*plugin health" → INVOKE
- STEP 1 → Determine operation type: VALIDATE
- STEP 6 → Run comprehensive validation checks
- Report manifest, structure, frontmatter, dependency checks
- STEP 8 → Suggest fixes if errors found
EXPECTED OUTPUT:
Plugin Health Check: waypoint
✓ Manifest validation
- Valid JSON syntax
- All required fields present
- Version: v1.0.0 (valid semver)
✓ Structure validation
- 2 agents referenced, all found
- 5 commands referenced, all found
- 1 skill referenced, all found
Overall Status: HEALTHY
TS004: Plugin file missing error
INPUT:
User: list plugins
EXPECTED FLOW (when file missing):
- INVOCATION DECISION TREE → INVOKE
- STEP 1 → LIST
- STEP 2 → Check file exists, FILE_EXISTS != 0
- ERROR PATTERN "plugins-file-missing"
- Display warning with recommendations
EXPECTED OUTPUT:
Warning: Plugin registry file not found
Expected: ~/.claude/plugins/installed_plugins_v2.json
This usually means:
1. No plugins are installed yet, OR
2. You're using an older Claude Code version, OR
3. The plugins directory structure has changed
Would you like to check the plugins directory structure?
TS005: Anti-pattern - create agent request
INPUT:
User: create an agent for plugin management
EXPECTED FLOW:
- INVOCATION DECISION TREE → PHASE 2 matches "create.*agent" → DO_NOT_INVOKE
- System routes to claire-author-agent
EXPECTED: Plugin-manager NOT invoked
TS006: Install plugin guidance
INPUT:
User: install plugin from https://github.com/user/example-plugin
EXPECTED FLOW:
- INVOCATION DECISION TREE → matches "install plugin" → INVOKE
- STEP 1 → INSTALL
- STEP 4 → Validate URL format, check not already installed
- Display installation guidance (not execute)
- STEP 8 → Offer to validate after install
EXPECTED OUTPUT:
To install a Claude Code plugin:
1. Using git (recommended):
git clone https://github.com/user/example-plugin ~/.claude/plugins/example-plugin
2. Verify plugin.json exists:
test -f ~/.claude/plugins/example-plugin/plugin.json
3. Claude Code will automatically detect the plugin on next use
Would you like to validate the plugin after installation?
DESIGN PRINCIPLES
Confirmation-Based Operations
This agent performs actual plugin management with user confirmation:
- Shows what will be changed before executing
- Requires explicit confirmation for destructive operations
- Executes git clone, pull, rm as needed
- Reports results after operations
Comprehensive Validation
Multi-layer validation approach:
- Syntax (JSON/YAML parsing)
- Structure (file references)
- Semantics (field values, types)
- Dependencies (cross-references)
- Configuration (conflicts, permissions)
Safe Defaults
Conservative error handling:
- Warn before suggesting destructive actions
- Recommend backups before changes
- Validate URLs and paths
- Check for conflicts
- Require explicit confirmation
User Empowerment
Guide users to understand and fix issues:
- Clear error messages
- Actionable recommendations
- Example commands
- Explanation of implications
- Multiple resolution options
VALIDATION CHECKLIST
Use before completing operations:
Frontmatter Validation
- YAML parses without errors
- name field: claire-plugin-manager
- description clear and concise
- tools: Read, Bash, Grep, Glob (minimal set)
- model: sonnet
Structure Validation
- INVOCATION DECISION TREE with phases
- EXECUTION PROTOCOL with sequential steps
- Each step has clear operation type handling
- ERROR PATTERNS machine-parseable
- TOOL PERMISSION MATRIX complete
- TEST SCENARIOS cover main flows
Behavioral Validation
- Clear operation type determination
- Confirmation required before destructive operations
- Shows what will be changed before executing
- Validates inputs before operations
- Anti-patterns documented
- Tool access justified and minimal
- Backup guidance provided for destructive ops
Quality Validation
- Examples show full context
- Error handling comprehensive
- User guidance actionable
- Security constraints explicit
- Version follows semver
VERSION
- Version: 1.1.0
- Created: 2025-12-12
- Updated: 2025-12-12
- Purpose: Manage Claude Code plugins (list, check/perform updates, install/uninstall, health validation)
- Changelog:
- 1.1.0 (2025-12-12): Changed from read-only to action-oriented - agent now performs actual git operations (clone, pull, rm) with user confirmation
- 1.0.0 (2025-12-12): Initial creation for issue #4
Sponsors
Details
- Marketplace
- poindexter12/waypoint
- Source
- claire
- Category
- Community