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

Create directory: .github/skills/<skill-name>/
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**

Validate: python scripts/validate_skills.py skill-name

Updating an Existing Skill

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

Process:

Identify what changed — code location, API, or rules
Read the current skill — understand existing structure
Update ONLY affected sections — don't reformat unrelated content
Validate: python scripts/validate_skills.py <skill-name> --check-refs
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)

| Field | Required | Constraints | |-------|----------|-------------| | name | Yes | 1-64 chars, lowercase alphanumeric + hyphens, must match directory | | description | Yes | 1-1024 chars, describe WHAT and WHEN |

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:

Identify the new location of the referenced code
Update the reference in the skill
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:

| Skill | Purpose | |-------|---------| | layer-* | Architecture layer guidance | | code-discovery | Codebase exploration tools | | code-generation | Boilerplate generation | | quality-analysis | QC and linting tools | | skill-maintenance | This skill (meta) |

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