Agent skill

mention-lint

Lint @-mentions for style consistency and correctness

View SKILL.md on GitHub Repository
Stars 107
Forks 15

Install this agent skill to your Project

npx add-skill https://github.com/jmagly/aiwg/tree/main/agentic/code/addons/aiwg-utils/skills/mention-lint

SKILL.md

@-Mention Linting

Validate @-mention style and fix common issues.

Usage

bash
/mention-lint                    # Lint current directory
/mention-lint --fix              # Auto-fix fixable issues
/mention-lint --strict           # Exit with error on any issue
/mention-lint --rules ML001,ML005  # Run specific rules only

Options

Option Default Description
--target . Directory to lint
--fix false Auto-fix fixable issues
--strict false Exit with error on any issue
--rules all Comma-separated rule IDs

Lint Rules

Rule Description Severity Auto-fix
ML001 @-mention path does not exist error no
ML002 @-mention uses wrong case warning yes
ML003 Missing required prefix (.aiwg/, src/, test/) warning yes
ML004 Uses deprecated path pattern warning yes
ML005 Invalid ID format (UC-NNN, ADR-NNN) warning yes
ML006 Duplicate @-mentions in same file info yes
ML007 @-mention in wrong section info no
ML008 Orphan @-mention (no back-reference) info no
ML009 Circular @-mention chain warning no
ML010 @-mention exceeds max depth (>3 hops) warning no

Output Example

src/services/auth/login.ts
  L3:  ML005 @.aiwg/requirements/UC-3-auth.md should be UC-003 (auto-fixable)
  L5:  ML001 @.aiwg/architecture/adrs/ADR-999.md does not exist

test/integration/auth.test.ts
  L2:  ML003 @auth/login.ts should be @$AIWG_ROOT/src/auth/login.ts (auto-fixable)

.aiwg/architecture/software-architecture-doc.md
  L45: ML008 References @.aiwg/requirements/UC-005.md but no back-reference

Summary: 4 issues (1 error, 2 warnings, 1 info)
         3 auto-fixable (run with --fix)

Rule Details

ML001: Path Does Not Exist

Error: @.aiwg/requirements/UC-999.md → file not found

Not auto-fixable. Remove reference or create file.

ML002: Wrong Case

Warning: @.aiwg/Requirements/UC-001.md should be @.aiwg/requirements/UC-001.md
Fix: Correct case to match filesystem

ML003: Missing Prefix

Warning: @auth/login.ts should be @$AIWG_ROOT/src/auth/login.ts
Fix: Add appropriate prefix

ML004: Deprecated Pattern

Warning: @requirements/UC-001.md should be @.aiwg/requirements/UC-001.md
Fix: Update to current pattern

ML005: Invalid ID Format

Warning: UC-3 should be UC-003 (3-digit format)
Warning: ADR-5-auth should be ADR-005-auth
Fix: Zero-pad numeric IDs

ML006: Duplicate Mentions

Info: @.aiwg/requirements/UC-001.md appears 3 times
Fix: Remove duplicates, keep first occurrence

CLI Equivalent

bash
aiwg mention-lint [--target <dir>] [--fix] [--strict]

Related Commands

  • /mention-wire - Add @-mentions
  • /mention-validate - Validate @-mentions exist
  • /mention-conventions - Display conventions

Lint @-mentions for: $ARGUMENTS

References

  • @$AIWG_ROOT/agentic/code/addons/aiwg-utils/README.md — aiwg-utils addon overview
  • @$AIWG_ROOT/docs/cli-reference.md — CLI reference for mention-lint command
  • @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/research-before-decision.md — Verify paths exist before referencing
  • @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/README.md — SDLC artifacts that use @-mention conventions

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

jmagly/aiwg

research-document

Generate summaries and literature notes from research papers

107 15
Explore
jmagly/aiwg

research-archive

Package research artifacts for long-term archival

107 15
Explore
jmagly/aiwg

research-cite

Format citations and generate bibliographies

107 15
Explore
jmagly/aiwg

induct-research

Induct research sources into a research repository. Point at an issue, a single file, a directory of papers, or a URI and the skill reads, annotates, and files structured induction tasks — one per source. Similar to address-issues but for research corpora instead of code backlogs.

107 15
Explore
jmagly/aiwg

research-provenance

Query provenance chains and artifact relationships

107 15
Explore
jmagly/aiwg

research-quality

Assess source quality using GRADE methodology

107 15
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results