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 descriptionOptional Frontmatter Fields:- category — Skill tier/​category- invokes — Skills this skill calls- invoked_by — Skills that call this- state_files — Files read/​writtenRequired 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 WrapperBad:````markdownmarkdown# 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 2Maximum 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 Formatmarkdown# Lint Report: .github/​skills/​my-skill/​SKILL.md## Summary| Severity | Count ||----------|-------|| 🔴 Error | 1 || 🟡 Warning | 3 || 🔵 Info | 2 |## Findings### 🔴 ERR001: File wrapped in code fenceLines 1, 47File starts with ```markdown and ends with ```.Remove the code fence wrapper.Auto-fix available: Yes### 🟡 WARN001: Excessive blank linesLine 23-264 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)