skill-manager

name

skill-manager

description

Discover, audit, update, and organise skills across all agent skill directories. Use when asked to list installed skills, find duplicates or broken symlinks, update a skill with session learnings, promote a project skill to the personal collection, or audit skill health. Triggers on "list skills", "update skill", "skill audit", "promote skill", "skill inventory", "what skills do I have", "sync skills", or "skill health check".

Skill Manager

Higher-order skill that wraps skill-creator for new skills and adds discovery, audit, and update workflows across all skill installation locations.

Skill topology

Skills live at two levels:

1. Personal (L1) — {SKILLS_DIR}/ (canonical). Other agents symlink here:

   • ~/.claude/skills → {SKILLS_DIR}
   • ~/.gemini/skills → {SKILLS_DIR}
   • ~/.kiro/skills → {SKILLS_DIR}

2. Project (L2) — .github/skills/ in each repo. Scoped to that project.

Personal skills come from multiple sources via symlinks:

• ~/shalomb/agent-skills/skills/ — personal, git-tracked (sharable)
• ~/projects/obra/superpowers/skills/ — obra's superpowers (upstream)
• Local dirs in {SKILLS_DIR}/ — not symlinked (codemap, _common)

Workflows

1. Inventory

# Count by source
echo "=== Skill sources ==="
find {SKILLS_DIR} -maxdepth 1 -type l -exec readlink {} \; | \
  sed 's|/[^/]*$||' | sort | uniq -c | sort -rn

# List local (untracked) skills
find {SKILLS_DIR} -maxdepth 1 -not -type l -type d | tail -n +2 | \
  xargs -I{} basename {}

# List project skills in current repo
ls .github/skills/ 2>/dev/null

2. Audit

Check for broken symlinks, missing SKILL.md, or skills not in git:

# Broken symlinks
find {SKILLS_DIR} -maxdepth 1 -type l ! -exec test -e {} \; -print

# Missing SKILL.md
for d in {SKILLS_DIR}/*/; do
  [ -f "$d/SKILL.md" ] || echo "MISSING: $d"
done

# Local skills not in agent-skills repo
for d in {SKILLS_DIR}/*/; do
  [ -L "$d" ] || echo "UNTRACKED: $(basename $d)"
done

3. Update a skill from session learnings

When a session reveals new knowledge (gotchas, patterns, workflows):

1. Identify the skill — which skill's domain does the learning belong to?
2. Decide the scope — does it go in SKILL.md body or a reference file?
   • Core workflow change → SKILL.md
   • Service-specific gotcha → references/{topic}.md
   • Cross-reference to another skill → one-liner in References section
3. Edit and verify — read the skill-creator SKILL.md for progressive disclosure principles. Keep SKILL.md lean (ideally under 100-300 lines).
4. Commit — if the skill is in a git-tracked location, follow the Atomic Commit Protocol (ACP): one logical change per commit, code + tests + docs together. Use the git-commit-formatter skill.

Key principle: add what you fumbled with. If you had to discover something through trial and error that wasn't in the skill, that's exactly what should be added.

4. Promote a project skill to personal

When a .github/skills/ skill is generic enough to share:

SKILL="terraform-plan-parser"
SOURCE=".github/skills/$SKILL"
TARGET="$HOME/shalomb/agent-skills/skills/$SKILL"

# 1. Copy, stripping org-specific references
cp -r "$SOURCE" "$TARGET"

# 2. Audit for org-specific content
grep -rni "takeda\|oneTakeda\|apms\|your-org" "$TARGET/"

# 3. Replace hardcoded paths with env vars or placeholders
#    e.g. ~/oneTakeda/repo → $REPO_ROOT or {REPO_PATH}

# 4. Symlink from pi skills
ln -sf "$TARGET" "$SKILLS_DIR/$SKILL"

# 5. Commit to agent-skills repo
cd ~/shalomb/agent-skills && git add "skills/$SKILL" && git commit -m "feat($SKILL): promote from project skills"

5. Create a new skill

Delegate to skill-creator:

# Read the skill-creator SKILL.md first for full guidance
python3 {SKILLS_DIR}/skill-creator/scripts/init_skill.py <name> --path ~/shalomb/agent-skills/skills

Then symlink: ln -sf ~/shalomb/agent-skills/skills/<name> {SKILLS_DIR}/<name>

Decision: where does a skill live?

Criterion	Personal (agent-skills)	Project (.github/skills/)
Org-specific references (ARNs, team names, internal URLs)	✗	✓
Reusable across orgs	✓	✗
Depends on project codebase layout	✗	✓
Generic tool/workflow (plan parser, git patterns)	✓	✗

When in doubt: start in .github/skills/, promote later after stripping org-specific content.

References

• skill-creator skill — SKILL.md structure, progressive disclosure, init/package scripts
• See references/skill-update-checklist.md for the post-session update procedure