agentleFS
Sign inStart free
bordenetbordenet/superpowers-plus/skills/engineering/skills-hierarchy-tuning/skill.md

skills-hierarchy-tuning

Skill8 starsChanged 6 months agoMITView on GitHub

Use when reviewing skill organization, rebalancing domains, adjusting loading triggers, or responding to structural review signals. Triggers on "reorganize skills", "skill hierarchy needs adjustment", "too many skills in domain", "split this skill folder", "domain rebalancing".

The file

Create a free account to mount
Files
skill.md

Skills Hierarchy Tuning

When to Invoke

TriggerAction
"skills audit"Full hierarchy review
"domain too big"Domain has >8 skills
"can't find skill for X"Discovery failing
"wrong skill loaded"Trigger mismatch
"skills not firing"Module loading issues

Step 1: Gather Current State

# Count skills per domain
for domain in */; do
  [ -d "$domain" ] && [ "$domain" != "_shared/" ] && [ "$domain" != "_archive/" ] && \
  echo "$domain: $(find "$domain" -name "skill.md" | wc -l | tr -d ' ') skills"
done

# Identify oversized skills
find . -name "skill.md" -exec wc -l {} \; | sort -rn | head -20

Step 2: Check Review Triggers

CategorySignalThreshold
StructuralDomain >8 skillsAny domain
StructuralOrphan skills>2 orphans
Operational"File not found" errors>3 in 1 week
OperationalWrong skill loaded>2 occurrences
LoadingModule path errors>3 in 1 week

Step 3: Diagnose & Fix

ProblemSymptomsSolution
Domain too large>8 skills, hard to findSplit into sub-domains
Skill too large>250 lines, AI misses rulesExtract to references/ directory
Module not loadingTrigger doesn't fireMake triggers more explicit with action words
Shared module conflictsTwo skills need variationsUse skill-specific sections in shared module

Step 4: Execute

Moving skills: mv old-domain/skill/ new-domain/skill/ → re-run your install/deploy mechanism → update cross-references

Creating domains: mkdir new-domain → move skills → your install auto-discovers

Extracting references: Move sections >50 lines to references/*.md, add pointer in core skill

After changes: Re-run install, update any documentation that lists skills or counts, commit and push.

Key Metrics

MetricTarget
Core skill.md≤250 lines
Reference files≤150 lines each
Critical rulesFirst 30 lines
Domains3-8 skills each

Failure Modes

ModeSymptomRecovery
Misconfigure triggersWrong skill firesTest anti_triggers after changes
Breaking existing triggersChanging hierarchy orphans trigger routesAudit all trigger strings before and after a move
Circular dependenciesSkill A → B → A reference loopsDraw the dependency graph before restructuring
Missing parent skillsChild skills added without updating orchestratorCheck all escalates_to / enables references after a move

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free