Skill Portfolio Architect

Skill Portfolio Architect

Audit, redesign, and optimize the complete Claude skill library using parallel subagents. Run proactively when the vault grows past threshold.

When to Run

Run immediately if any are true:

• Active vault skills > 60 (80% of healthy capacity ceiling of 75)
• New skills added since last audit > 10
• Duplicate plugin skills detected in vault
• misc/ or catch-all categories exist
• Locally installed skills missing from vault backup

Check current state:

# Active skill count
find ~/claude-skill-vault/skills -name "SKILL.md" | grep -v "_archive\|/versions/" | wc -l

# Installed but not backed up
comm -23 \
  <(ls ~/.claude/skills/ | sort) \
  <(find ~/claude-skill-vault/skills -mindepth 2 -maxdepth 2 -type d | grep -v "_archive\|_registry\|_templates\|versions" | xargs -I{} basename {} | sort)

# Categories with content
ls ~/claude-skill-vault/skills/ | grep -v "^_"

If count ≤ 48 and no orphans and no catch-all categories: vault is healthy. No action needed.

Execution Strategy

This skill runs in two parallel phases then a sequential implementation phase.

Spawn Phase 1 + 2 in parallel

Dispatch one subagent per category for inventory, while simultaneously dispatching an orphan-checker subagent.

Per-category inventory subagent prompt:

Read all SKILL.md files in ~/claude-skill-vault/skills/<category>/ (excluding _archive and versions/).
For each skill output a table row: | name | lines | function (1 sentence) | overlap_risk (none/low/high) |
Also flag:
- Plugin duplicates: name matches any skill in the superpowers or skill-creator plugin
- Sub-skills: clearly a subset of another skill in same or different category
- Domain-specific: contains worldbuilding, app-specific paths, or project names
- Catch-all: category is 'misc' or similar
Return the table and a summary: "N skills, M flags"

Orphan-checker subagent prompt:

Compare locally installed skills vs vault backup:
  installed: ls ~/.claude/skills/
  vault:     find ~/claude-skill-vault/skills -mindepth 2 -maxdepth 2 -type d | grep -v "_archive|_registry|_templates|versions" | xargs -I{} basename {}
List any skill directories present in ~/.claude/skills/ but absent from vault.
Also list any skill present in vault but NOT installed locally (informational only).

Spawn all category subagents + orphan-checker in the same message (parallel).

Phase 3: Decision Analysis (sequential, after Phase 1+2 complete)

Aggregate all subagent reports. Apply decision framework:

Plugin duplicate rule: Any vault skill with the same name/function as a currently loaded plugin is always DEPRECATE. Never maintain a local copy of a plugin skill.

Phase 4: Implementation (parallel subagents where independent)

Group actions by type and dispatch in parallel:

Archive subagent (handles all DEPRECATE + ARCHIVE decisions):

Archive these vault skills by moving to _archive/:
  mv ~/claude-skill-vault/skills/<category>/<slug>/ ~/claude-skill-vault/skills/_archive/
List: [list of skills to archive]

Merge subagent (handles each MERGE/CONSOLIDATE group):

Merge these skills into one:
  Sources: [list skill paths]
  Target: ~/claude-skill-vault/skills/<category>/<merged-slug>/SKILL.md
Read all source skills. Write a consolidated SKILL.md that:
- Combines frontmatter descriptions (all trigger terms)
- Uses sections for each source skill's unique content
- Removes cross-references between merged skills
Then archive the source skills.

Import subagent (handles IMPORT decisions):

Import these locally installed skills to vault:
  [list: slug → category]
For each: bash ~/claude-skill-vault/scripts/vault-save.sh <slug> ~/.claude/skills/<slug>/SKILL.md <category>

Recategorize subagent (handles RECATEGORIZE decisions):

Move these vault skills to correct categories:
  [list: current-path → target-category]
mv ~/claude-skill-vault/skills/<old-category>/<slug>/ ~/claude-skill-vault/skills/<new-category>/

Dispatch all four subagents in the same message. They operate on different directories so there is no conflict.

Phase 5: Finalize (sequential, after all Phase 4 agents complete)

cd ~/claude-skill-vault
python3 scripts/vault-registry-refresh.py
python3 scripts/vault-index-refresh.py
git add -A
git commit -m "refactor: skill portfolio audit — archive N, merge M, import K"
git push

Output Report

Always produce after completion:

# Skill Portfolio Audit — YYYY-MM-DD

## Health Check
- Active skills before: N | after: N
- Archived: N (plugin duplicates: N, consolidated: N, superseded: N)
- Merged: N pairs → N skills
- Imported: N (local-only → vault)
- Recategorized: N

## Actions Taken
| Skill | Decision | Reason |
|-------|---------|--------|

## Active Vault State
| Category | Count | Skills |
|----------|-------|--------|

## Next Audit Trigger
Run again when active skills > 60 or > 10 new skills added.

Rules Going Forward

1. No vault copy of any skill that a loaded plugin already provides
2. No misc/ catch-all category — every skill belongs in a real category
3. Every skill in ~/.claude/skills/ must be backed up in vault
4. firecrawl and similar multi-command tools stay as one consolidated skill
5. Maximum 75 active skills before automatic audit is triggered

Related Skills

• skill-creator — skill creation
• skill-reviewer-and-enhancer — skill review
• claude-md-improver — skill documentation

GitNexus Index

This skill is indexed by GitNexus for knowledge graph traversal. Index path: /Users/localuser/.claude/skills/skill-portfolio-architect/.gitnexus Last indexed: 2026-05-23