Skill Lint

Skill Lint

Overview

Audit skill/prompt files for structural issues, step continuity, cross-reference integrity, and JSON schema format coherence. Uses a two-phase approach: automated deterministic checks followed by LLM semantic analysis dispatched to the agent specified by --agent.

This is a rigid skill. Follow it exactly.

Usage: /skill-lint --agent

--agent is required. One of: codex, gemini, copilot, claude, cursor, kimi.

If --agent is omitted, announce: "Error: --agent is required. Usage: /skill-lint --agent " and stop.

Announce at start: "I'm using the skill-lint skill to audit [path] with [agent] as the LLM backend."

The Process

Step 1: Accept and Resolve Input Path

The skill accepts a directory or file path as its argument.

1. If directory: Use Glob to find SKILL.md, *.md, and other prompt definition files. Identify the skill structure (frontmatter, steps, JSON blocks).
2. If file: Read the single file directly.
3. Use Explore subagents to gather context needed for linting — read referenced files, check if cross-referenced tools/skills exist, understand the skill's domain.

You MUST read every file before linting it. Do NOT work from memory or assumptions.

Step 2: Phase 1 — Automated Deterministic Checks

Use Grep, Glob, and regex directly (no subagents) to verify mechanically checkable properties. These produce definitive pass/fail results.

Category A: Frontmatter Validation

• name field exists and is non-empty
• description field exists and is non-empty
• name matches the parent directory name (e.g., skill-lint/SKILL.md → name: skill-lint)
• No unknown frontmatter fields beyond name and description

Category B: Step Continuity

• Step numbers are sequential (no gaps: Step 1, Step 3 without Step 2)
• Sub-step numbers are sequential within their parent (1.1, 1.2, 1.3 — no gaps)
• Every step referenced elsewhere in the document (e.g., "see Step 3") actually exists
• No orphan sub-steps (e.g., Step 2.1 without a Step 2 header)

Category C: Cross-Reference Integrity

• Tool names referenced (e.g., "use the Read tool") match known Claude Code tools: Read, Write, Edit, Bash, Grep, Glob, Agent, AskUserQuestion, WebSearch, WebFetch, EnterPlanMode, ExitPlanMode, TaskCreate, TaskUpdate, NotebookEdit, Skill, SendMessage, ToolSearch
• Skill names referenced (e.g., "invoke amplify:write-plan") follow valid plugin:skill format
• No obvious typos in tool/skill references

Step 3: Phase 2 — LLM Semantic Checks

Dispatch semantic analysis to the agent specified by --agent. The checks are split into 5 groups, each with its own prompt template in the prompts/ directory adjacent to this SKILL.md.

Check Groups

| Group | Prompt Template | Categories | |-------|----------------|------------| | 1 | prompts/agent1-must-consistency.md | D: MUST/MUST NOT Consistency | | 2 | prompts/agent2-numeric-ungrounded.md | E1: Numeric as String + E2: Ungrounded Fields | | 3 | prompts/agent3-format-constraints.md | E3: Non-Interpretation Fields Without Format Constraints | | 4 | prompts/agent4-field-names.md | E4: Inconsistent Field Names Across Schemas | | 5 | prompts/agent5-enums-freetext.md | E5: Open-Ended Enums + E6: Structured Data as Free-Text |

Each agent MUST return findings as a JSON array with fields: category, fieldpath, currenttext, issue, suggested_fix, severity.

When --agent claude

Launch 5 internal Claude Code subagents in a single message for maximum parallelism. Each subagent receives the full file content and the check instructions from the corresponding prompt template.

| Subagent | Prompt Template | Model | Rationale | |----------|----------------|-------|-----------| | 1 | agent1-must-consistency.md | Sonnet | Needs full-file reasoning to detect contradictions and redundancy across distant sections | | 2 | agent2-numeric-ungrounded.md | Haiku | Pattern-matching with clear heuristics; high-volume, low-complexity | | 3 | agent3-format-constraints.md | Sonnet | Requires understanding of verbatim-transfer semantics and domain context | | 4 | agent4-field-names.md | Sonnet | Cross-schema semantic similarity analysis; needs nuanced judgment | | 5 | agent5-enums-freetext.md | Haiku | Pattern-based detection with clear signals |

When --agent is an external agent

For each of the 5 check groups:

1. Read the prompt template file from prompts/.
2. Substitute {FILE_CONTENT} with the actual content of the file being linted.
3. Write the composed prompt to a temporary file.
4. Invoke the external agent via a background Bash call (run_in_background: true, no timeout).

Launch all 5 background Bash calls in a single message for maximum parallelism. Wait for all 5 to complete (you will be notified automatically).

CLI invocation patterns:

| Agent | Command | |-------|---------| | codex | codex exec -q "$(cat )" | | gemini | gemini -p "$(cat )" --sandbox | | copilot | gh copilot explain "$(cat )" | | cursor | cursor agent "$(cat )" --print | | kimi | kimi "$(cat )" |

After all 5 complete, parse each result's stdout as a JSON array. If an agent wraps the JSON in markdown fences or prose, extract the JSON array from the output.

Category Reference

The full category definitions are in the prompt template files. For quick reference:

• D: MUST/MUST NOT Consistency — contradictory, vague, or redundant MUST rules
• E1: Numeric as String (High) — numeric placeholders wrapped in quotes
• E2: Ungrounded Fields (Medium) — generic placeholders without source attribution
• E3: Missing Format Constraints (Medium) — verbatim-transfer fields lacking format specs
• E4: Inconsistent Field Names (High) — same concept, different names across schemas
• E5: Open-Ended Enums (Low) — unclosed enumeration lists
• E6: Structured Data as Free-Text (High) — multiple sub-values crammed into one string field

Step 4: Compile Report

Merge Phase 1 and Phase 2 results into a single report using this exact format:

## Skill Lint Report: [path]

**Files analyzed:** [count]
**Issues found:** [count] ([N] automated, [M] semantic)
**LLM backend:** [agent name]

### Phase 1: Automated Checks

| # | Category | File | Location | Status | Detail |
|---|----------|------|----------|--------|--------|
| 1 | Frontmatter | SKILL.md | line 1-3 | FAIL | Missing `name` field |

### Phase 2: Semantic Checks

| # | Category | File | Field/Location | Severity | Detail |
|---|----------|------|----------------|----------|--------|
| 1 | E1: Numeric as String | SKILL.md | .count | High | ... |

### Finding Details

**Finding [N]: [Category]**
- **File:** [path]
- **Location:** [line range or field path]
- **Current text:** [exact current value]
- **Issue:** [one-line explanation]
- **Suggested fix:** [concrete replacement]

If no issues are found for a category, omit that category from the report. If no issues are found at all, say so explicitly.

Step 5: Severity Classification

Use this default severity table:

| Category | Default Severity | Rationale | |----------|-----------------|-----------| | A: Frontmatter Validation | High | Plugin discovery fails without correct frontmatter | | B: Step Continuity | Medium | Confuses the agent following the skill | | C: Cross-Reference Integrity | High | Agent attempts to use non-existent tools/skills | | D: MUST/MUST NOT Consistency | Medium | Contradictory rules cause unpredictable behavior | | E1: Numeric Quoted as String | High | Causes type errors in downstream consumers | | E2: Ungrounded Fields | Medium | Causes hallucinated values | | E3: Missing Format Constraints | Medium | Causes format drift across runs | | E4: Inconsistent Field Names | High | Causes integration failures | | E5: Open-Ended Enums | Low | Causes unpredictable but non-breaking values | | E6: Structured Data as Free-Text | High | Causes parsing failures downstream |

Remember

• Read the actual files. Do NOT work from memory or assumptions.
• Check EVERY field in EVERY schema. Do NOT sample.
• Report exact field paths using dot notation.
• If no issues are found for a category, omit that category from the report.
• If no issues are found at all, say so explicitly.
• Do NOT suggest fixes that change the semantic meaning of a field.
• When in doubt about whether something is an issue, report it with Low severity rather than omitting.
• Phase 1 checks are definitive (pass/fail). Phase 2 checks are advisory (may need human judgment).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: WeZZard
• Source: WeZZard/skill-kit
• License: MIT

Install and usage instructions live in the source repository linked above.