agentleFS
lgtm-hqlgtm-hq/ai-skills/skills/lintro-verify/SKILL.md

lintro-verify

Skill1 starsChanged 11 days agoMITView on GitHub

Verify that a lintro tool implementation is complete and follows all project standards. Use after adding a new tool to lintro.

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this skill to verify that a lintro tool implementation is complete and follows all project standards.

    line 8
  2. Very specific:

    When asked to verify a tool (e.g., /lintro-verify tsc), run through all checklist items below.

    line 13
  3. Distinctive:

    Run these to verify implementation:

    line 227
  4. Distinctive:

    After reviewing, provide a summary:

    line 307

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Verify Lintro Tool Implementation

Use this skill to verify that a lintro tool implementation is complete and follows all project standards.

Usage

When asked to verify a tool (e.g., /lintro-verify tsc), run through all checklist items below.


1. Core Implementation

Plugin Definition

  • lintro/tools/definitions/<tool>.py exists
  • Uses @register_tool decorator from lintro.plugins.registry
  • Inherits from BaseToolPlugin
  • ToolDefinition includes:
    • name - tool identifier (lowercase)
    • description - clear description of what the tool does
    • file_patterns - list of glob patterns (e.g., ["*.ts", "*.tsx"])
    • tool_type - appropriate ToolType enum value
    • can_fix - boolean indicating if tool supports auto-fix
    • native_configs - list of config files the tool uses (e.g., ["tsconfig.json"])
    • version_command - command to check version (e.g., ["tsc", "--version"])
    • priority - execution priority (default 50)
  • check() method implemented
  • fix() method implemented (or raises NotImplementedError if can_fix=False)
  • Options defined with proper types and defaults

Parser

  • lintro/parsers/<tool>/ directory exists with:
    • __init__.py - exports parser and issue classes
    • <tool>_parser.py - parses tool output into issues
    • <tool>_issue.py - issue dataclass with to_display_row() method
  • Parser handles all output formats the tool produces
  • Parser handles edge cases (empty output, errors, warnings)

Enums (if needed)

  • Tool added to lintro/enums/tool_name.py if it has a ToolName enum

Version Management

  • Version added to the tool's source: lintro/_tool_versions.py (binary/cargo/rustup), package.json (npm), or pyproject.toml (bundled Python)
  • Install hint added to lintro/tools/core/version_checking.py get_install_hints() templates
  • Version is reasonably current (check latest: npm view <tool> version or brew info <tool>)

Version Consistency (CRITICAL)

  • All version sources are aligned:
    • The install-type version source (_tool_versions.py / package.json / pyproject.toml)
    • package.json version (for npm tools)
    • Plugin min_version in tool definition
    • lintro/tools/manifest.src.json entry present (no version key; the generator renders the version into the gitignored manifest.json)
  • Renovate custom manager exists in renovate.json for _tool_versions.py (binary tools only)
  • package.json uses caret (^) prefix with an exact pin (e.g., ^0.27.0) — it is the version source for npm tools
  • Plugin min_version equals or is less than the version source's value

Doctor Health Check

  • Tool added to TOOL_COMMANDS in lintro/cli_utils/commands/doctor.py
  • lintro doctor shows tool with correct version (no "No cmd defined")

Command Builder (if needed)

  • If tool needs special command building, added to lintro/tools/core/command_builders.py

CLI Option Verification

  • Run <tool> --help and compare against implemented set_options() parameters
  • Verify each option is a real CLI flag (not config-file-only)
  • Test --tool-options actually work: lintro check . --tools <tool> --tool-options "<tool>:option=value"
  • Document which settings are CLI-available vs config-file-only in docs

Native Config Integration

  • Run <tool> --init (if available) to see default config structure
  • If tool has config file with useful settings, check if lintro/utils/native_parsers.py should parse it
  • Verify native_configs in ToolDefinition lists all supported config files

2. Documentation

README.md

  • Tool added to Supported Tools table with badge, language, and fix support
  • Tool added to Optional External Tools list (for external tools) with install commands

docs/getting-started.md

  • Tool added to Optional External Tools section with install instructions
  • Usage example section added (if tool has unique features)

docs/configuration.md

  • Full configuration section added including:
    • Tool description
    • Installation instructions (all methods: brew, npm/bun, pip, etc.)
    • Native config file example
    • Available --tool-options table
    • Usage examples

docs/tool-analysis/{tool}-analysis.md

  • Tool analysis document created following the standard format:
    • Overview of what the tool does
    • Core Tool Capabilities (native features)
    • Lintro Implementation Analysis:
      • Preserved Features (what lintro exposes)
      • Limited / Missing (what's NOT available via lintro)
      • Enhancements (what lintro adds: timeout, normalization, etc.)
    • Usage Comparison (native vs lintro commands)
    • Configuration Strategy
    • Priority and Conflicts
    • Recommendations (when to use lintro vs native tool)

3. Tests

Unit Tests

  • tests/unit/tools/<tool>/ directory with:
    • test_options.py - definition attributes, default options, set_options validation
    • test_execution.py - check/fix with mocked subprocess
  • tests/unit/parsers/test_<tool>_parser.py - parser tests covering:
    • Single error/warning parsing
    • Multiple issues parsing
    • Empty output handling
    • Edge cases (different file extensions, paths, etc.)
    • to_display_row() output

Integration Tests

  • tests/integration/tools/test_<tool>_integration.py with:
    • pytest.mark.skipif for when tool not installed
    • Fixtures for test files (with issues and clean)
    • test_definition_attributes - name, can_fix
    • test_definition_file_patterns - correct patterns
    • test_check_file_with_issues - detects problems
    • test_check_clean_file - no false positives
    • test_check_empty_directory - handles gracefully
    • test_set_options - options work correctly

Test Samples

  • test_samples/tools/<language>/<tool>/ directory with:
    • <tool>_violations.<ext> - file with deliberate issues (verify tool detects them)
    • <tool>_clean.<ext> - valid file without issues (verify no false positives)
  • Violations file triggers actual tool errors when run directly: <tool> <violations_file>

4. CI/CD & Docker

Dockerfile.tools

  • Tool version verification added (e.g., tsc --version && \)

Dockerfile (runtime)

  • Tool binary/wrapper copied from builder stage
  • For Node.js tools: wrapper script created in /usr/local/bin/

scripts/utils/install-tools.sh

  • Tool added to help text description
  • Installation block added with version from _tool_versions.py
  • Tool added to "Installed tools" echo list
  • Tool added to tools_to_verify array

scripts/ci/tools-image-verify.sh

  • Tool version check added

.github/workflows/tools-image.yml

  • Verify trigger paths include relevant files (usually automatic via Dockerfile.tools)

5. User Experience

lintro list-tools

  • Tool appears with correct name, language, actions, priority, config type

Error Handling

  • Graceful handling when tool not installed
  • Clear error messages with install hints
  • No crashes on malformed tool output

Install Hints

  • All common installation methods documented (brew, npm/bun, pip, cargo, etc.)
  • Version placeholders work correctly in hints

6. Verification Commands

Run these to verify implementation:

# Unit tests
uv run pytest tests/unit/tools/<tool>/ tests/unit/parsers/test_<tool>_parser.py -v

# Integration tests (requires tool installed)
uv run pytest tests/integration/tools/test_<tool>_integration.py -v

# Test on sample files
uv run lintro check test_samples/tools/<language>/<tool>/ --tools <tool>

# Verify tool appears in list
uv run lintro list-tools | grep <tool>

# Full lint check
uv run lintro chk

# Full test suite
uv run pytest tests/ -v

Version Consistency Verification

# Check all version sources are aligned (replace <tool> with actual name)
echo "=== _tool_versions.py ===" && grep "<tool>" lintro/_tool_versions.py
echo "=== manifest.src.json ===" && grep -A3 '"<tool>"' lintro/tools/manifest.src.json
echo "=== package.json ===" && grep "<tool>" package.json
echo "=== Plugin min_version ===" && grep "min_version" lintro/tools/definitions/<tool>.py
echo "=== Renovate manager ===" && grep -A5 '"<tool>"' renovate.json | head -10
echo "=== Doctor TOOL_COMMANDS ===" && grep "<tool>" lintro/cli_utils/commands/doctor.py

CLI Option Verification Commands

# Compare native CLI options against lintro implementation
<tool> --help

# Check version currency
npm view <tool> version        # for npm packages
brew info <tool>               # for Homebrew packages
pip index versions <tool>      # for Python packages

# Test that tool-options actually work (should not error)
uv run lintro check test_samples/ --tools <tool> --tool-options "<tool>:timeout=60"

# Test each documented option (replace with actual options)
uv run lintro check . --tools <tool> --tool-options "<tool>:option_name=value"

# Generate default config to understand structure
<tool> --init  # if available

7. Common Issues to Check

  • No "Missing install hints for tools" warning when running lintro
  • Tool respects --tool-options passed via CLI
  • Tool uses native config file when present
  • Parser correctly maps severity levels
  • File paths in issues are correct (relative vs absolute)
  • Line/column numbers are 1-indexed (not 0-indexed)
  • Tool timeout is configurable and has reasonable default
  • CLI options actually exist - verify with <tool> --help (some tools only support options via config file)
  • Version is current - check if pinned version is significantly outdated
  • Config-file-only options are not exposed as --tool-options (will cause runtime errors)
  • Version consistency - the install-type version source and plugin min_version are aligned
  • Renovate manager - custom regex manager exists in renovate.json for external tools

Review Output Format

After reviewing, provide a summary:

## Tool Review: <tool_name>

### Status: PASS / FAIL / PARTIAL

### Checklist Summary
- Core Implementation: X/Y items
- Documentation: X/Y items
- Tests: X/Y items
- CI/Docker: X/Y items
- User Experience: X/Y items

### Missing Items
1. [item description]
2. [item description]

### Recommendations
1. [recommendation]
2. [recommendation]

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.