Lint Agents

---
name: lint-agents
description: "Validates required frontmatter fields and body content in every agent and skill file in the pack by running scripts/lint-agents.sh. Interprets failures with specific fix instructions. Use before committing new or modified agents/skills, or as a CI gate. Trigger this when someone says: lint agents, validate agents, check agent files, run lint-agents, validate the pack, check if my agent is valid, did I write the skill correctly."
---

# Lint Agents

Run the Agent Pack linter to validate all agent and skill files, then interpret any failures with specific, actionable fix instructions.

## 1. Run the linter

```bash
bash scripts/lint-agents.sh
```

Capture the full output. If the script does not exist or is not executable, report:

> `scripts/lint-agents.sh` not found. Run `/setup-project` to scaffold the project structure, or check that you are in the correct repository root.

## 2. Parse the output

For each file reported in the output:

- **PASS** — note it as passing. No action needed.
- **FAIL** — identify the specific reason from the linter message and produce a targeted fix instruction (see below).

## 3. Produce fix instructions for each failure

Map linter failure messages to actionable fixes:

| Failure message | Fix |
|---|---|
| Missing required field: `name` | Add `name: <value>` to the frontmatter. For agents, this is the agent's identifier. For skills, it matches the slash command name. |
| Missing required field: `description` | Add `description: >` followed by a multi-line description, or `description: "..."` for a single-line value. The description is the routing contract — make it specific. |
| Unknown frontmatter field: `<field>` | Remove the `<field>` line. Only `name`, `description`, `tools`, `model`, `effort`, `permissionMode`, and `version` are valid for agents; only `name`, `description`, `license`, `compatibility`, `metadata`, and `allowed-tools` are valid for skills. |
| Description exceeds the limit (1536 characters for agents, 1024 for skills) | Shorten the description. Remove repeated information — trigger phrases, exclusions, and the core purpose should each appear once. |
| Missing body content | The file has frontmatter but no body. Add at minimum one section (`## ...`) explaining what the agent or skill does. |
| Body is too short | Expand the body. Agent files must contain behavioral instructions, not just a title. |

If the failure message does not match any of the above patterns, quote the exact linter message and ask the developer to compare their file against a well-formed example in the `skills/` or `agents/` directory.

## 4. Report

Output a structured summary:

```
## Lint Results

### Passing
- agents/csharp-engineer.md ✓
- skills/implement/SKILL.md ✓
[...]

### Failing
- agents/my-new-agent.md ✗
  **Reason:** Missing required field: `description`
  **Fix:** Add `description: >` followed by a clear routing description to the frontmatter.

[...]

### Summary
- Total files checked: N
- Passing: N
- Failing: N

### Gate result: [PASS | FAIL]
```

Gate is PASS only if zero files fail. A single failing file is a FAIL gate.

## Gotchas

- **Running from the wrong directory:** `scripts/lint-agents.sh` expects to be run from the repository root. If the working directory is wrong, the script will report file-not-found errors for every agent. Verify the working directory before diagnosing individual failures.
- **Newly added files not appearing:** The linter discovers files via glob. If a new agent or skill file was just created but is not in the expected directory (`agents/` or `skills/<name>/SKILL.md`), it will not be checked. Verify the file path matches the convention.
- **Fixing one failure revealing another:** After fixing a failure and re-running, a previously hidden failure in the same file may appear. This is normal — address failures one at a time or fix all visible issues before re-running.