Askl

askl

askl is a standalone command-line linter for the Agent Skills specification. It scans every SKILL.md under a repository's skill roots, validates frontmatter and referenced Markdown files, and reports issues with exact file and line positions.

Running it

askl                       # lint the default skill roots
askl --format json         # machine-readable output
askl --list-rules          # show every registered rule

Default skill roots (relative to the current working directory): .agent/skills, .agents/skills, .claude/skills, agents/skills, skills.

Exit codes: 0 clean, 1 a rule reported an error (or a warning with --deny-warnings), 2 a usage or config problem (bad --rule value, invalid config file).

Fixing a reported issue

1. Read the diagnostic: <file>:<line> error <message> (<rule>).
2. Open <file> at <line> and address <message> directly — every rule message states exactly what must change.
3. Re-run askl to confirm the fix and check for any remaining issues.

Common fixes:

• valid-frontmatter: add the missing name/description field, fix the YAML, or shorten a field past its length limit.
• name-matches-directory: rename the skill's name field or its directory so they match.
• no-broken-local-references / no-deep-references: fix the Markdown link target, or move the referenced file to at most one directory below SKILL.md.
• no-empty-skill-body: add instructions after the closing ---.
• skill-index-budget: shorten name/description across the flagged skills, since the message reports a combined total, not one file's size.

Suppressing a specific diagnostic

Only suppress a diagnostic when the rule's rationale genuinely does not apply to that line — never to silence an unaddressed real issue. Add an HTML comment to the SKILL.md source:

<!-- askl-disable-next-line no-windows-paths -->
See [the Windows helper](scripts\help.ps1).

<!-- askl-disable-next-line <rule> --> suppresses <rule> for the line that follows the comment; <!-- askl-disable <rule> --> suppresses it for the whole file regardless of where the comment sits. Both accept a space-or-comma-separated list of rule names, and omitting the list suppresses every rule.

Configuring rules

askl reads the nearest .asklrc.jsonc (or .asklrc.json), searching from the current directory upward:

{
	"roots": [".agents/skills"],
	"rules": {
		"no-unknown-frontmatter-fields": "error",
		"skill-index-budget": ["warn", { "maxCharacters": 8000 }],
	},
}

--roots and --rule <name>=<off|warn|error> on the command line override the config file for a single invocation.