Skill Maintenance

When to use: When creating new skills, updating outdated skills, or auditing skill quality.

Validation Script

Purpose: Check skills for format compliance and invalid references.

Usage:

# Validate all skills
python scripts/validate_skills.py

# Validate one skill
python scripts/validate_skills.py layer-helpers

# JSON output
python scripts/validate_skills.py --format=json

# Also check if code references exist
python scripts/validate_skills.py --check-refs

Checks performed:

• •YAML frontmatter starts with ---
• •Required fields: name, description
• •name matches directory name, lowercase with hyphens
• •name ≤ 64 chars, no consecutive hyphens
• •description ≤ 1024 chars, non-empty
• •Line count ≤ 500 (warning if exceeded)
• •Code references exist (with --check-refs)

Creating a New Skill

1. •Create directory: .github/skills/<skill-name>/
2. •Create SKILL.md with frontmatter:

---
name: skill-name
description: Use when [trigger conditions]. Provides [capabilities].
---

# Skill Title

**When to use:** [Clear trigger description]

---

## Section 1

Instructions...

---

## Validation Checklist

- [ ] Check 1 **→ Consequence**
- [ ] Check 2 **→ Consequence**

1. •Validate: python scripts/validate_skills.py skill-name

Updating an Existing Skill

When: Architecture changed, code moved, or skill guidance is stale.

Process:

1. •Identify what changed — code location, API, or rules
2. •Read the current skill — understand existing structure
3. •Update ONLY affected sections — don't reformat unrelated content
4. •Validate: python scripts/validate_skills.py <skill-name> --check-refs
5. •Test: Does the skill trigger correctly? Are examples still valid?

Rules:

• •Keep changes minimal and precise
• •Don't add historical context or migration notes
• •Update validation checklists if rules changed
• •Maintain existing tone and verbosity

Skill Format Requirements

Frontmatter (Required)

Name Rules

• •Lowercase letters, numbers, hyphens only
• •No leading/trailing hyphens
• •No consecutive hyphens (--)
• •Must match parent directory name exactly

Description Guidelines

Good:

description: Use when creating or modifying code in nomarr/helpers/. Helpers are pure utilities with NO nomarr.* imports.

Poor:

description: Helper layer rules.

Body Guidelines

• •Keep under 500 lines (move details to references/)
• •Use clear section headers with --- separators
• •Include code examples for patterns
• •End with a Validation Checklist
• •Reference files with relative paths

Checking Reference Validity

Code references in skills can become stale when code moves.

# Find invalid references
python scripts/validate_skills.py --check-refs

# Check specific skill
python scripts/validate_skills.py layer-components --check-refs

Fix invalid references:

1. •Identify the new location of the referenced code
2. •Update the reference in the skill
3. •Re-run validation to confirm

Periodic Audit Workflow

Run monthly or after major refactors:

# 1. Validate all skills
python scripts/validate_skills.py --check-refs

# 2. Review any invalid references
# 3. Update stale skills
# 4. Re-validate
python scripts/validate_skills.py

Skill Locations

Nomarr skills are organized by purpose:

Validation Checklist

Before committing skill changes, verify:

• • Does frontmatter have name and description? → Required
• • Does name match directory name? → Required
• • Is name lowercase with hyphens only? → Required
• • Does description explain WHAT and WHEN? → Required
• • Are code references still valid? → Run --check-refs
• • Is the skill under 500 lines? → Move to references/ if not
• • Does skill end with a validation checklist? → Recommended