LintLang CLI
A static linter for agent instructions: finds ambiguous tool descriptions and schema gaps before a run, with no model or network
- 144 ★ on the repository
- Last commit
- Apache-2.0
Minimal access
Why this level
- The utility reads project files and prints a report, and during a scan it calls no model and uses no network.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/lintlangDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewMinimal accessThe tool runs nothing and makes no network calls.
- The utility reads project files and prints a report, and during a scan it calls no model and uses no network.
This is third-party code. Review the repository files before installing.
What it does
LintLang checks the texts and interfaces an AI agent works from: system prompts, tool descriptions in MCP and function calling, parameter schemas, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `SKILL.md` and prompts embedded in Python code. The `uvx lintlang scan .` command walks a directory, finds such fragments in JSON, YAML, Markdown and Python and reports findings with a file, a line and a specific fix. The tool gives a line only where it can justify one. The rules catch similar tools without a difference in description (rule H1.6), retries and loops with no stop condition, missing required fields in schemas, several output formats in one prompt and long instruction lists with no priority. In `SKILL.md` it checks metadata, usage criteria and whether the skill name matches its folder. Scanning is local and deterministic: no model or network is called, and the same directory yields identical JSON and SARIF. That makes it usable in CI: the `--fail-on fail` flag blocks a build on HIGH and CRITICAL, and `lintlang init --github` creates a GitHub Actions workflow. Reports also come in GitLab Code Quality format.
Who it is for. Authors of skills and MCP servers and teams with large `AGENTS.md` files who want automatic instruction checks in CI and in the agent editor.
Good fit when
- Before publishing a skill you need to confirm the name matches the folder and metadata and usage criteria are set.
- An MCP server has many similar tools and the model confuses which to call: the utility shows pairs with no difference in description.
- You want to catch instruction problems in a pull request rather than after an agent failure and add a blocking check.
- A repository has long accumulated findings, and they must be recorded in a baseline so only new ones block.
- Claude Code or Cursor should give a hint after a file with instructions is edited.
Not a fit when
- You need to check how a model behaves at work: LintLang is static, it does not run the agent and sees no real tool calls.
- Semantic contradictions between two instructions are needed, such as 'always X' and 'never X': it does not find such conflicts.
- A human or model review of the text is needed: the rules check structure rather than quality of wording.
Example request
Run lintlang over the skill directory and fix the HIGH findings in the tool descriptions.Limitations
Python 3.10 or newer is required, and the only runtime dependency is `pyyaml`. A clean result means only that the selected static checks found no defects in the recognized content. If no recognized structures exist, the status is SKIPPED rather than PASS. The utility does not run a model, does not observe tool choice in live use and does not prove an agent safe. Findings are advisory by default: blocking is turned on with the `--fail-on` flag. Hooks in host agents cannot replace a CI check.
How to disable. Remove the package with `pip uninstall lintlang`, the `lintlang` workflow from `.github/workflows` and the hook entry from `.pre-commit-config.yaml`. Running through `uvx` installs nothing permanent.
FAQ
How do I run LintLang without installing it?
Run `uvx lintlang scan .` in the project root. You can also name a single file: `uvx lintlang scan SKILL.md`. For permanent installation there are `pip install lintlang` and `brew install hermes-labs-ai/tap/lintlang`.
What does the utility check in SKILL.md?
Metadata, usage criteria and whether the skill name matches the folder name. If the description does not say when to use the skill, it shows up in the findings.
How do I turn on blocking in CI?
Run `lintlang scan . --fail-on fail` so the build fails on HIGH and CRITICAL, or `--fail-on review` if MEDIUM should count too. `lintlang init --github --path .` creates a ready GitHub Actions workflow.
How do I connect LintLang to Claude Code?
The repository has a Claude Code plugin in `integrations/claude-code` and a `.claude-plugin/marketplace.json` manifest. After a file with instructions is edited the plugin shows guidance and does not rewrite the file.
What if many findings have accumulated?
Record them in a baseline with `lintlang scan . --write-baseline .lintlang-baseline.json`, then check with `--baseline`: only new or changed findings will block.
Discussion
No questions or reviews yet.
Related
CLI toolsAn ESLint-style linter whose rules are judged by a model: it finds in agent-written code what syntax checks miss and sets a verdict for CI
Validates Agent Skills packages: structure, links, token weight and instruction quality, with optional LLM-as-judge scoring
A local debugger for TypeScript agents: run step trees, CI trajectory checks and portable evidence bundles, with no account.
Reviews the git diff and the conversation with the agent: catches bugs and gaps between your request and the agent's result. CLI, skill, GitHub Action
A 0 to 10 score for CLAUDE.md and AGENTS.md: Reporails finds vague rules, repeats and broken imports
Corrections you give your agent turn into rule files in the repository and run with taskless check locally and in CI.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| LintLang (this card) | no | 144 | |
| agnix | yes | 471 | a linter for CLAUDE.md, AGENTS.md, SKILL.md and MCP configs with hundreds of rules and autofix; this one focuses on tool ambiguity, schemas and stop conditions |
| alint | no | 137 | a linter where a model checks the rules; here scanning is deterministic, with no model and no network |
README in short
The documentation briefly explains how the linter differs from model-based review and from generic linters and shows output on a sample. Then come a quickstart, CI with a baseline, a section with measurable test data and a list of agent and CI integrations.