agentsmesh lint

Validate canonical files against target-specific constraints. Each target has its own linting rules — for example, Cursor requires .mdc format compliance, Claude Code validates settings.json schema, and all targets check for valid frontmatter.

Usage

agentsmesh lint [flags]

Flags

Flag	Description
--global	Lint canonical home config under ~/.agentsmesh/.
--targets <csv>	Limit linting to specific target IDs.

Examples

Lint for all configured targets

agentsmesh lint

Lint for specific targets

agentsmesh lint --targets cursor
agentsmesh lint --targets claude-code,gemini-cli

Lint home-level config

agentsmesh lint --global --targets claude-code

What lint checks

All targets

• Valid YAML frontmatter in all .md files
• No duplicate rule/command/agent names
• Required fields present (root: true in _root.md, description in agents)
• Valid targets values (must be known target IDs)
• Valid globs patterns (syntactically valid gitignore patterns)

Claude Code

• settings.json schema validation
• Valid permissionMode values (ask, default, none)
• Valid tool names in allowed-tools and permissions.yaml

Cursor

• .mdc frontmatter format compliance
• Valid trigger values for Cursor rules

MCP servers

• Valid JSON in mcp.json
• Required fields per server type (command for stdio, url for HTTP)

Hooks

• Valid hook event types (PreToolUse, PostToolUse, etc.)
• Required fields (matcher, type)
• Valid type values (command, prompt)

Cross-target diagnostics (warnings)

These checks run against every configured target and are emitted as warnings — they do not fail lint’s exit code, but they surface contract gaps that would silently bite at generation time.

• silent-drop-guard — flags canonical content (rules, commands, agents, skills, hooks, permissions, ignore) that a target would drop without trace because its capability for that feature is none (or partial in cases where the dropped subset is detectable). Lets you see what each target will actually emit before running generate.
• hook-script-references — when a hook command references a script path (e.g. ./scripts/pre-commit.sh), warns for every target that does not copy hook scripts into its generated tree (currently every target except Copilot). The script must already exist relative to the hook execution directory or the generated config will fail at runtime.
• rule-scope-inversion — flags canonical rules whose activation scope (globs: / alwaysApply:) contradicts a target whose projection rules force always-on (or vice versa), so you don’t end up with a rule that silently always activates on a target that should respect manual scoping (e.g. Cursor manual rules).

These run automatically. Existing configs may surface new warnings on first lint after upgrading — particularly hook-script-references for any non-Copilot target whose hook commands reference scripts.

Exit codes

Code	Meaning
0	No lint errors found.
1	One or more lint errors.

Integrating with CI

Add lint to your CI pipeline alongside check:

.github/workflows/ci.yml

- name: Lint AgentsMesh config
  run: agentsmesh lint

- name: Check AgentsMesh sync
  run: agentsmesh check

This catches both config errors and drift in the same pipeline.