Who uses a steering file linter, and for what

Teams sharing AGENTS.md or CLAUDE.md

The problem. A shared instruction file is edited by everyone and owned by no one. It grows past the point where agents follow it well, collects rules that contradict each other, and drifts across the nested files in a monorepo. Different people use different agents, which read different files with different limits: Claude Code targets under 200 lines per CLAUDE.md and reads AGENTS.md only when there is no CLAUDE.md; Codex reads at most 32 KiB of AGENTS.md across all the files it finds.

What to check.

• What actually loads every session, per tool, and roughly what it costs: /asitis:md-budget totals Claude Code (CLAUDE.md, imports, rules, MEMORY.md, the skill listing), Codex, Gemini CLI, Cursor, Copilot, Windsurf and Cline.
• Contradictions and duplicates, within a file and across files that all load every session: /asitis:md-lint with no path lints every steering file in the project together.
• Broken relative links and @imports after someone moves a doc, and npm scopes such as @acme/ui that Claude Code would read as imports.
• That the shared-file setup works for everyone: a CLAUDE.md that imports @AGENTS.md, not one that asks Claude in words to read it. See AGENTS.md vs CLAUDE.md.

A routine that takes five minutes. Before merging a pull request that touches a steering file, paste the changed file into the checker or run /asitis:md-lint on it. Once a quarter, run /asitis:md-budget, delete what is no longer true, and move area-specific rules into path-scoped rules. The best practices guide has the details, and the token cost guide explains the numbers.

Also useful: the optional guard hook warns when Claude is about to rewrite a shared markdown file wholesale, convert its line endings or strip trailing spaces, so steering-file diffs stay small enough to review.

Skill authors publishing SKILL.md

The problem. A skill that works on your machine can fail quietly elsewhere. Frontmatter that does not parse means Claude Code loads the skill with no fields set. A name with capitals or underscores breaks the Agent Skills spec that Codex, Cursor, Copilot and Gemini CLI read. A description over 1,024 characters breaks the spec. Claude Code still loads such a skill, but the Claude API and claude.ai reject it, and they also reject a name containing "anthropic" or "claude" and XML tags in the name or description. And past 1,536 characters, Claude Code truncates what it shows of your description in the skill listing.

What to check before you publish.

• Frontmatter on line 1, closed, valid YAML, no byte order mark before it.
• name: lowercase letters, digits and single hyphens, at most 64 characters, matching the folder.
• description: present, at most 1,024 characters, with the trigger first; description plus when_to_use under 1,536.
• Body under 500 lines and under about 5,000 tokens, with detail moved into referenced files.
• No hidden comments or invisible characters you did not mean to ship. People will lint your skill before installing it; better that you do first.

How. In the checker, pick SKILL.md and enter the folder name so the name-folder match is checked. In Claude Code, run /asitis:md-lint .claude/skills/your-skill/SKILL.md, or lint a whole skills repository at once. Our guide is my SKILL.md valid explains each rule.

Security reviewers checking repositories

The problem. Steering files are loaded into an agent's context automatically and the agent is built to follow them. People review them rendered, where HTML comments, [//]: # comments, styled-away text and invisible Unicode do not show. A line hidden that way reaches the agent and skips the reviewer.

What the linter finds. Comments that read like instructions to an AI (asking to ignore other instructions, addressing the assistant, naming an assistant, asking for covert action or to hide something from the user, mentioning secrets or commands), unclosed comments that hide the rest of a file, text hidden with inline styles or the hidden attribute, zero-width characters, Unicode tag characters and bidirectional controls. Each finding shows the line as stored, with invisible characters written out as escapes.

What we saw in public repositories. On 6 October 2026 we ran the linter over the root AGENTS.md and CLAUDE.md files of the most-starred public GitHub repositories, 100 of each. It found no invisible characters, bidirectional controls, style-hidden text or unclosed comments. Three comments read like instructions: one was a maintainer's request that agents mark the pull request text they write (benign, and discussed in our hidden instructions guide), and two were false positives in our own patterns. Popular repositories are well reviewed; the risk is concentrated in less-watched places, such as skills copied from gists and pull requests that "tidy up" an instruction file.

How to use it in a review.

• For one file, paste or drop it into the checker. Nothing is uploaded, which matters when the repository is private.
• For a whole repository, open it in Claude Code with the plugin installed and run /asitis:md-lint; the plugin is read-only and can only read markdown inside the project folder.
• For any finding, check who added the line and whether it matches the visible instructions. The linter cannot judge intent.

Know the limits. The instruction patterns are English and heuristic. A malicious instruction written in plain sight is not hidden, so the linter will not flag it; reading the file is still the review. And a skill's scripts can do things its SKILL.md never mentions. For anything that must never happen, use Claude Code permission rules or a PreToolUse hook.

claude plugin marketplace add Katta041/asitis-agent-tools
claude plugin install asitis@asitis