Claude-skill-registry agent-ops-lint-instructions

name: agent-ops-lint-instructionsdescription: "Validate and lint AgentOps instruction files (skills, prompts, agents). Checks formatting, structure, and consistency."category: extended []invoked_by: [agent-ops-housekeeping, agent-ops-create-skill]state_files: read: [] write: []---# Instruction File LinterValidate AgentOps markdown-based instruction files for formatting, structure, and consistency.## Supported File Types| Type | Pattern | Location ||------|---------|----------|| Skill | `SKILL.md` | `.github/skills/*/` || Prompt | `*.prompt.md` | `.github/prompts/` || Agent | `AGENTS.md` | Project root or subdirs || Instructions | `copilot-instructions.md` | `.github/` |## Trigger```/lint-instructions [path]/lint-skills/lint-prompts```## Validation Rules### Critical Errors (must fix)| ID | Rule | Description ||----|------|-------------|| ERR001 | No code fence wrapper | File must NOT be wrapped in ` ```markdown ` / ` ``` ` || ERR002 | Valid YAML frontmatter | Frontmatter must parse without errors || ERR003 | Required frontmatter fields | Skills must have `name`, `description` || ERR004 | File encoding | Must be UTF-8 without BOM |### Warnings (should fix)| ID | Rule | Description ||----|------|-------------|| WARN001 | Excessive blank lines | Max 2 consecutive blank lines allowed || WARN002 | Trailing whitespace | Lines should not end with spaces/tabs || WARN003 | Heading hierarchy | Don't skip levels (H1 → H3 without H2) || WARN004 | Inconsistent list markers | Use `-` consistently, not mixed `*` and `-` || WARN005 | Missing newline at EOF | File should end with single newline || WARN006 | Table alignment | Pipes should be consistently spaced |### Info (style suggestions)| ID | Rule | Description ||----|------|-------------|| INFO001 | Long lines | Consider wrapping lines > 120 chars || INFO002 | Missing sections | Suggested sections for file type || INFO003 | Deprecated patterns | Outdated syntax or conventions |## File Format Standards### Skill Files (SKILL.md)Skills follow a specific format with YAML frontmatter and markdown body:```markdown---name: skill-namedescription: "Short description"category: extended [other-skills]invoked_by: [parent-skills]state_files: read: [files] write: [files]---# Skill TitleBrief overview paragraph.## Section HeadingContent...```**Required Frontmatter Fields:**- `name` — Skill identifier (must match directory name)- `description` — One-line description**Optional Frontmatter Fields:**- `category` — Skill tier/category- `invokes` — Skills this skill calls- `invoked_by` — Skills that call this- `state_files` — Files read/written**Required Sections:**- Title (H1) matching skill name- At least one H2 section### Prompt Files (*.prompt.md)Prompts are simpler, typically no frontmatter:```markdown## PurposeBrief description of what this prompt does.## UsageHow to invoke this prompt.## WorkflowSteps the prompt follows.```**Required Sections:**- At least one H2 section describing purpose### Agent Files (AGENTS.md)Agent instruction files for AI coding assistants:```markdown# Project Name## OverviewWhat this project does.## DevelopmentBuild and test commands.## ArchitectureKey components and structure.```**Required Sections:**- Title (H1)- At least Overview or Development section## Anti-Patterns (Forbidden)### ERR001: Code Fence Wrapper**Bad:**````markdown```markdown# My SkillContent here...```````**Good:**```markdown# My SkillContent here...```The file content should be raw markdown, not wrapped in a code fence.### WARN001: Excessive Blank Lines**Bad:**```markdown## Section 1Content## Section 2```**Good:**```markdown## Section 1Content## Section 2```Maximum of 2 consecutive blank lines.### WARN002: Trailing Whitespace**Bad:**```markdownSome text hereMore text```**Good:**```markdownSome text hereMore text```### WARN003: Heading Hierarchy Skip**Bad:**```markdown# Title### Subsection (skipped H2!)```**Good:**```markdown# Title## Section### Subsection```## Auto-Fix SupportThe following rules can be auto-fixed:| Rule | Auto-Fix Action ||------|-----------------|| ERR001 | Remove wrapping code fences || WARN001 | Collapse to max 2 blank lines || WARN002 | Strip trailing whitespace || WARN005 | Add newline at EOF |To apply auto-fixes:```/lint-instructions --fix [path]```## Output Format```markdown# Lint Report: .github/skills/my-skill/SKILL.md## Summary| Severity | Count ||----------|-------|| 🔴 Error | 1 || 🟡 Warning | 3 || 🔵 Info | 2 |## Findings### 🔴 ERR001: File wrapped in code fence**Lines 1, 47**File starts with ` ```markdown ` and ends with ` ``` `.Remove the code fence wrapper.**Auto-fix available:** Yes### 🟡 WARN001: Excessive blank lines**Line 23-26**4 consecutive blank lines found.**Auto-fix available:** Yes```## Standards ReferencesThis skill follows established markdown standards:1. **CommonMark Spec** — https://spec.commonmark.org/ - Canonical markdown parsing rules - Heading, list, code block definitions2. **GitHub Flavored Markdown (GFM)** — https://github.github.com/gfm/ - Tables, task lists, autolinks - Strikethrough, code fence info strings3. **YAML 1.2** — https://yaml.org/spec/1.2/ - Frontmatter parsing rules4. **EditorConfig** — https://editorconfig.org/ - Indentation, line endings, trailing whitespace## Integration with Other Skills### agent-ops-housekeepingDuring housekeeping, optionally run lint check:```Housekeeping includes:- Archive completed issues ✓- Validate issue schema ✓- Lint instruction files (optional)```### agent-ops-create-skillWhen creating new skills, validate format before completion:```Created skill: agent-ops-new-skillRunning format validation...✅ SKILL.md format valid```## ConfigurationOptional `.agent/lint-config.json` for project-specific rules:```json{ "rules": { "WARN001": "error", "INFO001": "off" }, "max_line_length": 100, "max_blank_lines": 1}```## Procedure1. **Discover files** — Find all instruction files in scope2. **Parse each file** — Extract frontmatter and body3. **Run validators** — Apply rules based on file type4. **Aggregate findings** — Group by severity5. **Report** — Output findings with fix suggestions6. **Auto-fix** (if requested) — Apply safe fixes## Forbidden Behaviors- Never modify files without `--fix` flag- Never change semantic content (only formatting)- Never remove comments or documentation- Never reorder sections (only format within sections)