---
name: ao-lint-instructions
description: "Validate and lint AO instruction files (skills, prompts, agents). Checks formatting, structure, and consistency."
category: extended
invokes: [ao-state]
invoked_by: [ao-housekeeping, ao-create-skill]
state_files:
  read: []
  write: []
---

# Instruction File Linter

Validate AO markdown-based instruction files for formatting, structure, and consistency.

## Supported File Types

| Type | Pattern | Location |
|------|---------|----------|
| Skill | `SKILL.md` | `.ao/skills/*/` |
| Prompt | `*.prompt.md` | `.github/prompts/`, `.ao/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-name
description: "Short description"
category: extended
invoked_by: [parent-skills]
state_files:
  read: [files]
  write: [files]
---

# Skill Title

Brief overview paragraph.

## Section Heading

Content...
```

**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
## Purpose
Brief description of what this prompt does.

## Usage
How to invoke this prompt.

## Workflow
Steps 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

## Overview
What this project does.

## Development
Build and test commands.

## Architecture
Key components and structure.
```

**Required Sections:**
- Title (H1)
- At least Overview or Development section

## Anti-Patterns (Forbidden)

### ERR001: Code Fence Wrapper

**Bad:**
````markdown
```markdown
# My Skill
Content here...
```
`````

**Good:**
```markdown
# My Skill
Content here...
```

The file content should be raw markdown, not wrapped in a code fence.

### WARN001: Excessive Blank Lines

**Bad:**
```markdown
## Section 1

Content


## Section 2
```

**Good:**
```markdown
## Section 1
Content

## Section 2
```

Maximum of 2 consecutive blank lines.

### WARN002: Trailing Whitespace

**Bad:**
```markdown
Some text here
More text
```

**Good:**
```markdown
Some text here
More text
```

### WARN003: Heading Hierarchy Skip

**Bad:**
```markdown
# Title
### Subsection (skipped H2!)
```

**Good:**
```markdown
# Title
## Section
### Subsection
```

## Auto-Fix Support

The 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: .ao/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 References

This skill follows established markdown standards:

1. **CommonMark Spec** — https://spec.commonmark.org/
   - Canonical markdown parsing rules
   - Heading, list, code block definitions

2. **GitHub Flavored Markdown (GFM)** — https://github.github.com/gfm/
   - Tables, task lists, autolinks
   - Strikethrough, code fence info strings

3. **YAML 1.2** — https://yaml.org/spec/1.2/
   - Frontmatter parsing rules

4. **EditorConfig** — https://editorconfig.org/
   - Indentation, line endings, trailing whitespace

## Integration with Other Skills

### ao-housekeeping

During housekeeping, optionally run lint check:

```
Housekeeping includes:
- Archive completed issues ✓
- Validate issue schema ✓
- Lint instruction files (optional)
```

### ao-create-skill

When creating new skills, validate format before completion:

```
Created skill: ao-new-skill
Running format validation...
✅ SKILL.md format valid
```

## Configuration

Optional `.agent/ops/lint-config.json` for project-specific rules:

```json
{
  "rules": {
    "WARN001": "error",
    "INFO001": "off"
  },
  "max_line_length": 100,
  "max_blank_lines": 1
}
```

## Procedure

1. **Discover files** — Find all instruction files in scope
2. **Parse each file** — Extract frontmatter and body
3. **Run validators** — Apply rules based on file type
4. **Aggregate findings** — Group by severity
5. **Report** — Output findings with fix suggestions
6. **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)

## Related Skills

- `ao-housekeeping` — includes format validation
- `ao-create-skill` — validates new skill format
- `ao-docs` — checks documentation quality
