Skill Manager

Skill Manager - Agent Skill Lifecycle Management

Meta-skill for analysing, generating, cataloguing, and validating the project's skill ecosystem. Operates as a peer to the Orchestrator in the agent hierarchy.

Description

Manages the full lifecycle of agent skills including gap analysis, generation from templates or descriptions, catalogue browsing, and health validation. Ensures every skill in the project meets quality standards, uses Australian English, and is registered in the skill registry.

When to Apply

Positive Triggers

• Analysing which skills the project needs but lacks
• Generating a new skill from a template or description
• Browsing the built-in skill catalogue for ideas
• Validating an existing skill's quality and compliance
• User mentions: "skill gap", "generate skill", "missing skills", "skill health"
• Orchestrator requests gap analysis before a new phase
• A new agent is added without corresponding skill coverage

Negative Triggers

• The task is about using an existing skill (route to that skill instead)
• The task is pure code implementation (route to Specialist B)
• The task is about agent configuration, not skill content

Core Directives

Path Conventions

• Custom skills live in: .skills/custom/{skill-name}/SKILL.md
• Vercel skills live in: .skills/vercel-labs-agent-skills/skills/
• Skill registry: .skills/AGENTS.md
• Agent profiles: .claude/agents/{agent-name}/agent.md
• Command interfaces: .claude/commands/{command-name}.md
• Reference data: .skills/custom/skill-manager/references/

Token Economy (Shannon Protocol)

• Load only the reference file relevant to the current mode
• Do not dump entire catalogue when user asks for a single gap
• Compress analysis output to actionable recommendations
• Maximum response: 200 lines for MODE 1, 500 lines for MODE 2 output

---

MODE 1: Full Analysis

Trigger: "analyse skills", "skill gap", "missing skills", "what skills do we need?"

Step 1: Context Scan

Scan the project to build an inventory:

1. Read .skills/AGENTS.md → extract installed skill names
2. Read .skills/custom/*/SKILL.md → extract frontmatter (name, description)
3. Read .skills/vercel-labs-agent-skills/skills/*/SKILL.md → same
4. Read .claude/agents/*/agent.md → extract skills_required fields
5. Scan project structure for context signals:
   - .github/workflows/ → CI/CD detected
   - docker-compose.yml → Docker detected
   - apps/backend/src/api/ → API routes detected
   - apps/web/components/ → Frontend components detected
   - apps/backend/src/db/ → Database models detected
   - apps/backend/src/agents/ → AI integration detected

Output: Installed skills list + detected project context.

Step 2: Gap Analysis

Apply rules from references/gap-analysis.md:

1. Check DEPENDENCY RULES:
   For each installed skill, verify required dependencies are installed.
   Missing dependency → Critical priority, confidence 1.0

2. Check COMPLEMENTARY-PAIR RULES:
   For each installed skill, check if known complements are installed.
   Missing complement → High priority, confidence per rule table

3. Check CATEGORY-COVERAGE RULES:
   For each foundational category, check if ≥1 skill is installed.
   Empty foundational category → Medium priority, confidence 0.7

4. Calculate final_score for each gap:
   final_score = base_priority × confidence × context_multiplier
   (See references/gap-analysis.md for multiplier calculation)

5. Sort gaps by final_score descending

Step 3: Recommendations

Format output per the gap-analysis report template. Include:

• Top 5 Critical/Recommended gaps with scores and reasons
• Quick-win suggestions (Low complexity gaps with high scores)
• Suggested generation order (respect dependency graph)

Response Format:

[AGENT_ACTIVATED]: Skill Manager
[PHASE]: Analysis
[STATUS]: complete

{gap analysis report}

[NEXT_ACTION]: Generate top-priority skill via MODE 2, or browse catalogue via MODE 3

---

MODE 2: Generate Skill

Trigger: "generate skill", "create skill", "new skill for {topic}"

Input

User provides one of:

• A catalogue entry reference (e.g., "generate 2.1 api-contract")
• A free-form description (e.g., "generate a skill for webhook handling")
• A gap analysis recommendation (from MODE 1 output)

Generation Workflow

Step 1: Resolve Template

If catalogue reference provided:
  → Load entry from references/catalogue.md
  → Extract: name, description, complexity, complements

If free-form description:
  → Search catalogue for closest match
  → If match found (>70% relevance): use as base template
  → If no match: generate from scratch using description

Step 2: Generate SKILL.md

Produce a SKILL.md file following this exact structure:

---
name: {kebab-case-name}
description: >-
  {50-500 character description in en-AU}
license: MIT
metadata:
  author: NodeJS-Starter-V1
  version: '1.0.0'
  locale: en-AU
---

Body sections (in order):

# {Title} - {Subtitle}

{One paragraph overview}

## When to Apply

### Positive Triggers
- {3+ positive triggers}

### Negative Triggers
- {1+ negative triggers}

## Core Directives
{Rules, conventions, path references}

## {Main Content Sections}
{Skill-specific content with code examples}

## Response Format
{Using [AGENT_ACTIVATED] / [PHASE] / [STATUS] convention}

## Australian Localisation (en-AU)
- Date Format: DD/MM/YYYY
- Currency: AUD ($)
- Spelling: colour, behaviour, optimisation, analyse, centre

Step 3: Validate

Run MODE 4 (Health Check) on the generated skill before presenting it.

Step 4: Register

If the skill passes health check:

1. Write SKILL.md to .skills/custom/{name}/SKILL.md
2. Create references/ directory if skill needs supplementary files
3. Update .skills/AGENTS.md:
   - Add row to Custom Skills table
   - Update Skill Priority list if applicable
4. Report success with file paths

Response Format:

[AGENT_ACTIVATED]: Skill Manager
[PHASE]: Generation
[STATUS]: {generating | validating | complete}

{generated SKILL.md content or summary}

[NEXT_ACTION]: Review generated skill, then run health check

---

MODE 3: Skill Catalogue Browse

Trigger: "browse skills", "skill catalogue", "what skills are available?"

Load and present data from references/catalogue.md.

Supports filtering by:

• Category: "show me API skills" → filter to Category 2
• Complexity: "show easy skills" → filter to Low complexity
• Complement: "what pairs with council-of-logic?" → filter by Key Complements

Present results as a filtered table. Do not dump the entire catalogue unless explicitly requested.

---

MODE 4: Skill Health Check

Trigger: "skill health", "validate skill", "check skill quality"

Load validation rubric from references/health-check.md.

Supports:

• Single skill: /skill-manager health council-of-logic → validate one skill
• All skills: /skill-manager health --all → validate every installed skill
• Generated skill: Automatically invoked after MODE 2 generation

Output the Health Report format defined in references/health-check.md.

---

Anti-Patterns

Checklist

• [ ] Gap analysis completed before generating new skills
• [ ] Generated SKILL.md is under 500 lines
• [ ] All en-AU spelling verified (analyse, catalogue, colour, optimise, behaviour)
• [ ] Skill registered in .skills/AGENTS.md
• [ ] Health check (MODE 4) passed with no critical findings

Response Format

All Skill Manager outputs follow the project response convention:

[AGENT_ACTIVATED]: Skill Manager
[PHASE]: {Analysis | Generation | Catalogue | Health Check}
[STATUS]: {in_progress | awaiting_verification | complete}

{response_content}

[NEXT_ACTION]: {what happens next}

Integration Points

Orchestrator

The Orchestrator can invoke Skill Manager before starting a new phase:

# In orchestrator route_task:
if self.is_skill_management_task(task):
    return self.get_agent('skill-manager')

Council of Logic

MODE 2 (Generate Skill) applies Shannon Check to generated content:

• Description under 500 characters?
• SKILL.md under 500 lines?
• No redundant sections?
• Maximum signal, minimum noise?

Spec Builder

When generating complex skills (High complexity), Skill Manager may invoke Spec Builder for a specification document before generation.

Behavioural Rules

1. Never hardcode paths — always use relative paths from project root 2. Always en-AU — colour, analyse, catalogue, optimise, centre, behaviour 3. Under 500 lines — every generated SKILL.md must be under 500 lines 4. No self-generation without analysis — MODE 2 should follow MODE 1 or explicit user request 5. Registry consistency — every generated skill must be registered in .skills/AGENTS.md 6. Respect hierarchy — Skill Manager is a peer to Orchestrator, not subordinate 7. Token economy — load only the reference file needed for the current mode

Australian Localisation (en-AU)

• Date Format: DD/MM/YYYY
• Time Format: H:MM am/pm (AEST/AEDT)
• Currency: AUD ($)
• Spelling: colour, behaviour, optimisation, analyse, centre, catalogue
• Tone: Direct, professional, actionable

Skill Catalogue - Built-In Templates

Reference data for MODE 3: Skill Catalogue Browse.

40+ skill templates across 8 categories for gap analysis and generation.

---

How to Use This Catalogue

1. Browse by category to find relevant skill templates 2. Check if a skill already exists in .skills/custom/ or .skills/vercel-labs-agent-skills/ 3. Generate new skills via MODE 2 using a catalogue entry as the seed 4. Score gaps using references/gap-analysis.md scoring formula

---

Category 1: Error Handling & Resilience

Trigger Phrases: "error handling", "retry", "resilience", "fault tolerance", "graceful degradation"

---

Category 2: API & Integration

Trigger Phrases: "API", "endpoint", "integration", "webhook", "rate limit", "GraphQL"

---

Category 3: Data Processing

Trigger Phrases: "data", "transform", "CSV", "cache", "vector", "queue", "background job"

---

Category 4: Document & Content

Trigger Phrases: "document", "PDF", "email", "search", "content", "i18n", "localisation"

---

Category 5: Authentication & Security

Trigger Phrases: "auth", "security", "RBAC", "OAuth", "CSRF", "audit", "secrets"

---

Category 6: Orchestration & Workflow

Trigger Phrases: "workflow", "state machine", "saga", "pipeline", "scheduler", "feature flag"

---

Category 7: Observability & DevOps

Trigger Phrases: "logging", "monitoring", "metrics", "tracing", "Docker", "CI/CD", "infrastructure"

---

Category 8: Communication & Reporting

Trigger Phrases: "notification", "report", "changelog", "dashboard", "Slack", "status page"

---

Complexity Guide

---

Cross-Category Relationships

Skills frequently work together across categories. Key relationship clusters:

• API Stack: api-contract + api-client + data-validation + error-taxonomy
• Resilience Stack: retry-strategy + graceful-shutdown + resilience-patterns + health-check
• Observability Stack: structured-logging + metrics-collector + tracing-patterns + health-check
• Content Stack: markdown-processor + search-indexer + vector-search + content-moderation
• Workflow Stack: state-machine + saga-pattern + queue-worker + pipeline-builder

See references/gap-analysis.md for the full relationship graph and scoring formula.

Gap Analysis Engine - Scoring & Relationships

Reference data for MODE 1: Full Analysis.

Contains the scoring formula, relationship graph, and priority classification rules.

---

Scoring Formula

Each identified gap receives a score calculated as:

final_score = base_priority × confidence × context_multiplier

Base Priority

Confidence

A float from 0.0 to 1.0 representing how certain the gap is:

Context Multipliers

Applied additively, then clamped to [0.5, 2.0]:

---

Priority Thresholds

After scoring, gaps are classified:

---

Dependency Rules (Critical Priority)

These rules fire when an installed skill declares a dependency that is not satisfied.

---

Complementary-Pair Rules (High Priority)

These rules fire when one skill in a known pair is installed but the other is not.

---

Category-Coverage Rules (Medium Priority)

These rules fire when an entire foundational category has zero installed skills.

---

Skill Relationship Graph

Requires (hard dependency)

resilience-patterns  --> retry-strategy
saga-pattern         --> retry-strategy
saga-pattern         --> queue-worker
dashboard-patterns   --> metrics-collector
tracing-patterns     --> metrics-collector
notification-system  --> queue-worker
workflow-engine      --> state-machine
infrastructure-as-code --> secret-management
report-generator     --> pdf-generator (soft)

Complements (recommended pairing)

api-contract     <--> error-taxonomy
api-contract     <--> data-validation
api-client       <--> retry-strategy
retry-strategy   <--> graceful-shutdown
queue-worker     <--> graceful-shutdown
health-check     <--> graceful-shutdown
structured-logging <--> error-taxonomy
vector-search    <--> cache-strategy
search-indexer   <--> vector-search
ci-cd-patterns   <--> docker-patterns
state-machine    <--> council-of-logic
csv-processor    <--> data-validation
cron-scheduler   <--> structured-logging
scientific-luxury <--> email-template
scientific-luxury <--> dashboard-patterns

---

Analysis Output Format

Gap analysis results should be formatted as:

## Skill Gap Analysis Report

**Project**: {project_name}
**Date**: {DD/MM/YYYY}
**Installed Skills**: {count}
**Gaps Identified**: {count}

### Critical Gaps (Score ≥ 75)

| Rank | Skill | Score | Reason | Action |
|------|-------|-------|--------|--------|
| 1 | `{name}` | {score} | {reason} | Generate via MODE 2 |

### Recommended Gaps (Score 40–74)

| Rank | Skill | Score | Reason | Action |
|------|-------|-------|--------|--------|
| 1 | `{name}` | {score} | {reason} | Schedule for next milestone |

### Nice to Have (Score < 40)

| Rank | Skill | Score | Reason |
|------|-------|-------|--------|
| 1 | `{name}` | {score} | {reason} |

Skill Health Check - Validation Rubric

Reference data for MODE 4: Skill Health Check.

Defines the criteria, scoring, and report format for validating skill quality.

---

Validation Criteria

Each skill is evaluated against 10 criteria. Each criterion scores 0 (fail) or 1 (pass).

1. Frontmatter Completeness

Weight: Required

The SKILL.md must include valid YAML frontmatter with all required fields:

---
name: skill-name            # Required: kebab-case identifier
description: >-             # Required: under 500 characters
  One-paragraph description.
license: MIT                # Required: licence type
metadata:
  author: NodeJS-Starter-V1 # Required: project identifier
  version: '1.0.0'          # Required: semver string
  locale: en-AU             # Required: must be en-AU
---

Pass: All 6 fields present with valid values. Fail: Any field missing or locale is not en-AU.

2. When to Apply Section

Weight: Required

The SKILL.md must contain a ## When to Apply section with:

• At least 3 positive triggers (when to activate)
• At least 1 negative trigger or boundary (when NOT to activate)

Pass: Section exists with ≥3 positive and ≥1 negative trigger. Fail: Section missing or insufficient triggers.

3. Description Length

Weight: Required

The frontmatter description field must be:

• Minimum: 50 characters
• Maximum: 500 characters

Pass: Length within bounds. Fail: Too short (vague) or too long (bloated — Shannon violation).

4. File Length

Weight: Required

The SKILL.md file must be:

• Maximum: 500 lines

Skills exceeding 500 lines should split content into references/ files.

Pass: ≤500 lines. Fail: >500 lines.

5. Australian English

Weight: Required

All content must use en-AU spelling. Check for these common violations:

Pass: No American English spellings detected. Fail: One or more American spellings found.

6. No Duplicate Functionality

Weight: Required

The skill must not substantially overlap with an existing installed skill. Check:

• Trigger phrases do not match another skill >50%
• Core functionality is distinct from all installed skills
• If overlap exists, the skill must explicitly declare its differentiation

Pass: Distinct functionality or declared differentiation. Fail: >50% overlap with existing skill without differentiation.

7. Declared Dependencies Satisfied

Weight: Required

If the skill references other skills as dependencies (via requires or in its text), those skills must either:

• Already be installed in .skills/custom/ or .skills/vercel-labs-agent-skills/
• Be flagged as optional with a fallback described

Pass: All required dependencies installed or marked optional. Fail: Missing required dependency.

8. Code Examples Present

Weight: Recommended

Skills with complexity ≥ Medium should include at least one code example demonstrating correct usage.

Pass: At least one fenced code block with a language hint. Fail: No code examples in a Medium/High complexity skill.

9. Response Format Defined

Weight: Recommended

Skills that produce structured output should define their response format using the project convention:

[AGENT_ACTIVATED]: {agent_name}
[PHASE]: {current_phase}
[STATUS]: {status}

Pass: Response format section present or skill does not produce structured output. Fail: Skill produces structured output but format is undefined.

10. References Integrity

Weight: Recommended

If the SKILL.md references files in references/, those files must exist.

Pass: All referenced files exist and are non-empty. Fail: Broken reference path.

---

Scoring

health_score = (passed_criteria / total_applicable_criteria) × 100

Pass/Fail Threshold

Required vs Recommended

• Required criteria (1-7): Must all pass for a PASS status
• Recommended criteria (8-10): Missing these downgrades to WARNING at most

A skill can only achieve PASS if all 7 Required criteria pass.

---

Health Report Format

## Skill Health Report

**Skill**: `{skill-name}`
**Path**: `.skills/custom/{skill-name}/SKILL.md`
**Date**: {DD/MM/YYYY}
**Status**: {PASS | WARNING | FAIL}
**Score**: {score}%

### Criteria Results

| # | Criterion | Status | Notes |
|---|----------|--------|-------|
| 1 | Frontmatter Completeness | {PASS/FAIL} | {details} |
| 2 | When to Apply Section | {PASS/FAIL} | {details} |
| 3 | Description Length | {PASS/FAIL} | {chars} characters |
| 4 | File Length | {PASS/FAIL} | {lines} lines |
| 5 | Australian English | {PASS/FAIL} | {violations found} |
| 6 | No Duplicate Functionality | {PASS/FAIL} | {details} |
| 7 | Declared Dependencies | {PASS/FAIL} | {details} |
| 8 | Code Examples | {PASS/FAIL} | {count} examples |
| 9 | Response Format | {PASS/FAIL} | {details} |
| 10 | References Integrity | {PASS/FAIL} | {details} |

### Recommendations

{Bulleted list of specific improvements if status is WARNING or FAIL}