audit-library

name: audit-library description: Guidance for auditing AWS Coworker's agents, skills, and commands version: 1.0.0 category: meta agents: [aws-coworker-meta-designer] tools: [Read, Glob, Grep]

Audit Library

Purpose

This meta-skill provides guidance for auditing AWS Coworker's library of agents, skills, and commands. Use it to identify issues, inconsistencies, and improvement opportunities within the framework itself.

When to Use

• Scheduled periodic reviews of AWS Coworker
• After significant additions or changes
• When issues are reported with skills or commands
• Before major version releases
• When onboarding new team members (to verify library health)

When NOT to Use

• Auditing AWS infrastructure (use AWS-specific tools)
• Creating new skills (use skill-designer)
• Creating new commands (use command-designer)

Audit Process

Phase 1: Inventory

Collect complete inventory of AWS Coworker components:

# List all agents
ls -la .claude/agents/

# List all commands
ls -la .claude/commands/

# List all skills
find skills/ -name "SKILL.md" -type f

# Count components
echo "Agents: $(ls .claude/agents/*.md 2>/dev/null | wc -l)"
echo "Commands: $(ls .claude/commands/*.md 2>/dev/null | wc -l)"
echo "Skills: $(find skills/ -name 'SKILL.md' | wc -l)"

Phase 2: Structural Checks

Verify each component meets structural requirements.

Agent Checks

For each agent in .claude/agents/:

Skill Checks

For each skill in skills/:

Command Checks

For each command in .claude/commands/:

Phase 3: Content Quality

Evaluate content quality across components.

Naming Consistency

Pattern: aws-coworker-{role|action}

✅ aws-coworker-planner
✅ aws-coworker-plan-interaction
❌ planner (missing prefix)
❌ aws-coworker_planner (underscore)
❌ AWSCoworkerPlanner (wrong case)

Cross-Reference Integrity

Verify all references are valid:

1. Skills referenced in commands — Do they exist?
2. Agents referenced in skills — Are they valid?
3. Related skills in skill docs — Do they exist?
4. Tools listed — Are they appropriate for the component?

Documentation Quality

Phase 4: Governance Alignment

Check alignment with AWS Coworker governance:

Safety Compliance

• Mutation commands have approval checkpoints
• Production commands enforce CI/CD patterns
• No direct AWS CLI in read-only agents
• Blast radius disclosure in execution commands

Layer Compliance

• Core skills don't contain org-specific content
• Org skills are in skills/org/
• Meta skills follow self-evolution patterns
• Clear separation between layers

AWS Well-Architected Alignment

• Security: Least-privilege, encryption defaults
• Reliability: Error handling, rollback guidance
• Operational Excellence: Automation, documentation
• Cost: Cost-aware recommendations where applicable

Phase 5: Duplication Detection

Identify overlapping or duplicated functionality:

Skill Overlap

Look for skills that cover similar ground:

Questions to ask:
- Do multiple skills address the same AWS service?
- Are there redundant patterns across skills?
- Could skills be merged or split?

Command Overlap

Look for commands with similar workflows:

Questions to ask:
- Do multiple commands achieve similar outcomes?
- Are there redundant approval patterns?
- Could commands share more common steps?

Phase 6: Gap Analysis

Identify missing coverage:

AWS Service Coverage

Compare against major AWS services:

Core Services:
- [ ] IAM
- [ ] Organizations
- [ ] VPC / Networking
- [ ] EC2
- [ ] ECS / EKS
- [ ] Lambda
- [ ] S3
- [ ] RDS / DynamoDB
- [ ] CloudFormation / CDK
- [ ] CloudWatch / CloudTrail

Workflow Coverage

Compare against common operations:

Standard Workflows:
- [ ] Discovery / inventory
- [ ] Planning
- [ ] Non-prod execution
- [ ] Prod change preparation
- [ ] Rollback
- [ ] Account bootstrap
- [ ] Security audit
- [ ] Cost review

Audit Report Template

# AWS Coworker Audit Report

**Date:** YYYY-MM-DD
**Auditor:** [Name/Agent]
**Scope:** [Full/Partial - specify]

## Executive Summary

[2-3 sentence overview of findings]

## Inventory

| Component | Count | Status |
|-----------|-------|--------|
| Agents | X | ✅/⚠️/❌ |
| Skills | X | ✅/⚠️/❌ |
| Commands | X | ✅/⚠️/❌ |

## Critical Findings

[Issues that must be addressed]

### Finding 1: [Title]
- **Severity:** Critical
- **Component:** [Name]
- **Issue:** [Description]
- **Recommendation:** [Action]

## High Priority Findings

[Issues that should be addressed soon]

## Medium Priority Findings

[Issues to address when convenient]

## Low Priority Findings

[Minor improvements]

## Gap Analysis

### Missing Coverage
- [Gap 1]
- [Gap 2]

### Recommendations
- [Recommendation 1]
- [Recommendation 2]

## Action Items

| Priority | Item | Owner | Due |
|----------|------|-------|-----|
| Critical | [Action] | [Who] | [When] |
| High | [Action] | [Who] | [When] |

## Next Audit

Recommended: [Date or trigger]

Severity Definitions

Automation Opportunities

Automated Checks

These checks can be automated:

# Check all skills have valid frontmatter
for skill in $(find skills/ -name "SKILL.md"); do
  # Validate YAML frontmatter
  head -50 "$skill" | grep -A 20 "^---" | head -n -1 | tail -n +2
done

# Check all commands reference existing skills
for cmd in .claude/commands/*.md; do
  # Extract skills from frontmatter
  # Verify each exists in skills/
done

# Check naming conventions
ls .claude/agents/ | grep -v "^aws-coworker-"
ls .claude/commands/ | grep -v "^aws-coworker-"

Manual Checks

These require human judgment:

• Content quality and clarity
• Appropriateness of scope
• Governance alignment
• Strategic gaps

Audit Frequency

Related Skills

• skill-designer — For creating skills identified as gaps
• command-designer — For creating commands identified as gaps
• git-workflow — For managing audit-driven changes