agentleFS
chuckplayerchuckplayer/claude-agent-pack/skills/lint-agents/SKILL.md

lint-agents

Skill8 starsChanged 35 days agoMITView on GitHub

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.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

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

    line 8
  2. Very specific:

    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 …

    line 40
  3. Distinctive:

    Fixing one failure revealing another: After fixing a failure and re-running, a previously hidden failure in the same file may appear.

    line 75

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 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 messageFix
Missing required field: nameAdd name: <value> to the frontmatter. For agents, this is the agent's identifier. For skills, it matches the slash command name.
Missing required field: descriptionAdd 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 contentThe file has frontmatter but no body. Add at minimum one section (## ...) explaining what the agent or skill does.
Body is too shortExpand 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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.