missing-description rule: what it flags and the fix

What it catches#

Required description field is missing.

A SKILL.md or subagent with no description, or an empty one. For a memory topic file this is a note, since Claude Code's own memory files carry a description but the docs do not require one.

Why it matters#

The description is what the agent reads to decide when to load a skill or delegate to a subagent.

Bad example#

---
name: api-client
---

# API client

Regenerate the TypeScript client from `openapi.yaml`...

The description is the only text an agent sees before deciding to load a skill. Claude Code substitutes the first non-empty body line, here the heading "API client", which says nothing about when to use it. Other tools skip the skill.

Good example#

---
name: api-client
description: Regenerate the TypeScript API client from openapi.yaml. Use after the OpenAPI spec changes or when the client is out of date.
---

How to fix#

Write one or two sentences: what the skill does, then when to use it, with the words a user would say. For a subagent, say what it is good at and when Claude should hand work to it.

Suppress or configure#

For one finding, put a comment on the line above it. The reason after -- is optional but worth writing:

<!-- asitis-disable-next-line missing-description -- why this one is fine -->

For a whole file:

<!-- asitis-disable-file missing-description -- why this file is an exception -->

For every file, turn it off or change its severity in .asitisrc.json:

{ "rules": { "missing-description": "off" } }

A .asitisrc.json overrides entry limits a change to some paths, and a baseline (asitis lint --format json --write-baseline) accepts today's findings so only new ones fail the build.

Source#

Claude Code docs: Skills, read on 14 October 2026.

missing-description