aj-geddes/hvs-skill-buddy

HVS Skill Buddy

The meta-skill that keeps the HVS skill ecosystem coherent, current, and consistent. It does three things: audit (find drift), update (stay current), and create (new skills that fit the system).

Mode Selection

Identify which mode applies from the user's request:

| User Says | Mode | |-----------|------| | "Audit my skills", "check for drift", "are these consistent" | → Audit Mode | | "What's new in skills?", "update the skill system", "self-update" | → Self-Update Mode | | "Create a skill for X", "build a skill that does Y" | → Create Mode | | "Fix this skill", "update this skill to match others" | → Audit Mode on single skill + Create Mode to rewrite |

When in doubt, ask. One clarifying question is better than working on the wrong thing.

---

Audit Mode

Systematically inspect the HVS skill library for drift, overlap, and inconsistency.

Step 1 — Inventory the Library

# List all user skills with their sizes
for skill in /mnt/skills/user/*/SKILL.md; do
  name=$(basename $(dirname "$skill"))
  lines=$(wc -l < "$skill")
  refs=$(ls "$(dirname "$skill")/references/" 2>/dev/null | wc -l | tr -d ' ')
  scripts=$(ls "$(dirname "$skill")/scripts/" 2>/dev/null | wc -l | tr -d ' ')
  echo "$name | lines=$lines | refs=$refs | scripts=$scripts"
done

Step 2 — Run the Drift Checker

python3 /mnt/skills/user/hvs-skill-buddy/scripts/audit-skills.py \
  --skills-dir /mnt/skills/user \
  --standard /mnt/skills/user/hvs-skill-buddy/references/hvs-system-standard.md

This script checks every skill against the HVS system standard and outputs a structured drift report. Read the report carefully before proceeding.

Step 3 — Classify Findings

After running the checker, sort findings into three buckets:

Critical (fix now)

• A skill installs a tool/framework that another skill already owns (technology boundary violation)
• A skill's install commands are inconsistent with the HVS canonical form
• A skill references a file that does not exist

Warning (fix soon)

• Missing pre-flight check in a skill that interacts with external systems
• Description lacks trigger keywords for a common use case
• No references directory in a skill with >150 lines

Info (nice to have)

• Different heading styles across similar skills
• Script names don't follow the verb-noun.sh / verb_noun.py convention

Step 4 — Report to User

Present findings as a structured table. Example format:

AUDIT REPORT — HVS Skill Library
Generated: [date]

CRITICAL (2)
─────────────────────────────────────────────────────────────────
hvs-user-journey-skill  | Playwright install: missing pytest-playwright
                        | Fix: pip install playwright pytest-playwright --break-system-packages

hvs-e2e-testing         | Playwright install: missing `playwright` package
                        | Fix: pip install playwright pytest-playwright --break-system-packages

WARNING (1)
─────────────────────────────────────────────────────────────────
sow-bidding             | No pre-flight check for required environment vars
                        | Suggestion: add Step 0 checking for HVS_RATE, etc.

INFO (3)
─────────────────────────────────────────────────────────────────
...

TECHNOLOGY BOUNDARIES (no violations)
─────────────────────────────────────────────────────────────────
✓ Playwright owned by: hvs-e2e-testing (all others defer to it)
✓ Docker builds owned by: docker-build-expert
...

Step 5 — Fix (with permission)

For each critical finding, ask: "Want me to fix this now?" Then apply fixes using the Create Mode template to rewrite only the affected section. Never rewrite a full skill unless the user asks.

---

Self-Update Mode

Keep the HVS skill system current with Anthropic's latest patterns and any advances in the underlying technologies.

Step 1 — Check Anthropic Skill Docs

Use web search to check for updates:

Search: "Anthropic Claude skills system prompt 2025 site:docs.anthropic.com"
Search: "Claude skill creator SKILL.md best practices"
Search: site:docs.claude.com skills

Also fetch the current skill-creator skill to compare against what's embedded here:

cat /mnt/skills/examples/skill-creator/SKILL.md | head -120

Step 2 — Check Technology Currency

For each technology owned by an HVS skill, check for significant updates:

Search: "playwright 2025 latest version breaking changes"
Search: "pytest-playwright 2025 update"
Search: "helm 2025 best practices kubernetes"
Search: "GitHub Actions 2025 new features security"

Look for:

• Deprecated APIs or commands the skills still use
• New security advisories affecting patterns in the skills
• Major version bumps that change install or invocation syntax

Step 3 — Update the System Standard

If Anthropic has changed how skills work (new frontmatter fields, new loading behavior, new triggering mechanism), update references/hvs-system-standard.md to reflect the change.

Show the diff to the user before applying it.

Step 4 — Propagate Critical Changes

If a technology update affects multiple skills (e.g., a Playwright major version changes install syntax), use Audit Mode to find every affected skill and queue them for update.

---

Create Mode

Build a new skill that fits the HVS system standard from the first line.

Step 1 — Intake Interview

Before writing anything, answer these questions (extract from conversation or ask):

1. What does this skill do? (one sentence, active voice)
2. When should it trigger? (list 5-10 user phrases)
3. What technology stack does it use? (check the Technology Registry — don't duplicate ownership)
4. Does a similar skill already exist? (search /mnt/skills/user/)
5. What does the output look like? (file, report, deployed resource, etc.)
6. Does it need scripts/automation, or is it guidance-only?
7. What can go wrong? (pre-flight checks needed)

Step 2 — Technology Boundary Check

Before writing install commands, check references/technology-registry.md. If the skill needs a tool that another skill already owns:

• Don't re-install it — reference the owning skill instead
• Add a dependency note: > This skill requires docker-build-expert for image builds
• Only add install commands for tools unique to this skill

Step 3 — Apply the HVS Skill Template

See references/hvs-system-standard.md for the full template. The short version:

SKILL_NAME/
├── SKILL.md                    # Required. Frontmatter + instructions
│   ├── YAML frontmatter        # name, description (pushy triggers)
│   ├── Mode Selection table    # (if skill has multiple modes)
│   ├── Pre-flight Check        # (if skill touches external systems)
│   ├── Phase N: ...            # Numbered phases for multi-step workflows
│   └── References section      # Pointers to files in references/
├── references/
│   ├── [topic].md              # One file per major sub-topic
│   └── ...
└── scripts/
    ├── [verb]-[noun].sh        # Shell scripts: kebab-case
    └── [verb]_[noun].py        # Python scripts: snake_case

Non-negotiables for every HVS skill:

• --break-system-packages on every pip install
• 2>/dev/null || true on optional npm installs (never fail the pre-flight)
• Playwright install canonical form (see Technology Registry)
• Phase numbers start at 1, not 0
• Decision tables use the 3-column format: | Situation | Approach | Reference |
• Reports go to /tmp/hvs-[skill-name]-[timestamp]/ to avoid clobbering

Step 4 — Write the Skill

Follow the template. Length guidance:

• SKILL.md: 150–400 lines (under 500 hard limit)
• Each references/*.md: 50–300 lines
• Scripts: as long as needed, well-commented

Step 5 — Consistency Check

Before delivering, verify the new skill against the standard:

python3 /mnt/skills/user/hvs-skill-buddy/scripts/audit-skills.py \
  --single /tmp/new-skill-name \
  --standard /mnt/skills/user/hvs-skill-buddy/references/hvs-system-standard.md

Fix any findings before handing to the user.

Step 6 — Package and Deliver

# Copy to outputs
cp -r /tmp/new-skill-name /mnt/user-data/outputs/

Then use present_files to hand the skill directory to the user.

---

Reference Files

| File | Contents | |------|----------| | references/hvs-system-standard.md | The canonical HVS skill template and all non-negotiable rules | | references/technology-registry.md | Which skill owns which technology stack | | references/known-drift.md | Tracked drift issues across the library (running log) |

Read the relevant reference file before taking action in any mode.

---

Guiding Principles

One owner per technology. If docker-build-expert owns Docker, no other skill runs its own image build logic. Skills reference each other, not duplicate.

Fail loud in pre-flight, silent in optional deps. Required tools fail the workflow with a clear error. Optional enhancements use 2>/dev/null || true.

Consistent install patterns. Every skill that installs Python packages uses --break-system-packages. No exceptions.

Phases, not prose. Multi-step workflows use numbered ## Phase N headings. This makes sub-agent handoff deterministic.

Reports have a home. All output goes to /tmp/hvs-[skill]-[timestamp]/. Never scatter files.

The registry is truth. If a technology isn't in the registry, add it before writing install commands. If it's already there, defer to the owning skill.