Metadata-Version: 2.4
Name: ai-skill-lint
Version: 0.1.0
Summary: Linter for AI instruction files — skills, prompts, and agent specs
Project-URL: Homepage, https://github.com/rajusem/skill-lint
Project-URL: Repository, https://github.com/rajusem/skill-lint
Project-URL: Issues, https://github.com/rajusem/skill-lint/issues
Author: Raj Zalavadia
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,ai,claude,copilot,cursor,gemini,linter,prompts,skills
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# skill-lint

Linter for AI instruction files — skills, prompts, and agent specs.

skill-lint scans AI instruction files (CLAUDE.md, AGENTS.md, GEMINI.md, SKILL.md, .cursorrules, .github/copilot-instructions.md, .github/instructions/, and agent/skill directories) for issues that cause token waste, hallucination risk, and unpredictable agent behavior. 40 rules across 8 categories with fix suggestions.

## Quick Start

```bash
pip install ai-skill-lint   # or: pipx install ai-skill-lint

skill-lint .                                    # Scan current project
skill-lint /path/to/project                     # Scan a local directory
skill-lint https://github.com/org/repo          # Scan a GitHub repo
skill-lint . --format sarif --fail-on warning   # CI gate
skill-lint . -v                                 # Verbose
```

## What It Checks

| Category | Rules | Examples |
|----------|-------|---------|
| Token cost | 11 | Oversized files, duplicates, filler phrases, hedging |
| Description | 5 | Too long, missing trigger conditions |
| Hallucination risk | 4 | Vague instructions, no output format, prompt injection risk |
| Framing | 4 | Prohibition overuse, emphasis overuse, bare directives |
| Output quality | 3 | No examples, no verification, no role statement |
| Best practice | 5 | No model, no error handling, model-complexity mismatch |
| Structure | 7 | Broken refs, encoding, file too large |
| Cross-file | 1 | Contradictions between CLAUDE.md and skill files |

Each file scored 0-100 with actionable fix suggestions.

## CI Integration

```yaml
# GitHub Actions
- run: pip install ai-skill-lint
- run: skill-lint . --format sarif --fail-on warning > results.sarif
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif
```

### pre-commit

```yaml
repos:
  - repo: https://github.com/rajusem/skill-lint
    rev: v0.1.0
    hooks:
      - id: skill-lint
```

### Baseline (incremental adoption)

```bash
skill-lint . --save-baseline   # Save current findings
skill-lint . --diff            # Show only NEW issues
```

## Inline Suppression

```markdown
<!-- skill-lint: disable TCOST005 -->
<!-- skill-lint: disable TCOST003, HRISK001 -->
```

## Configuration

### Option 1: `.skill-lint.yaml`

```yaml
disable:
  - HRISK002
  - OQUAL001
fail_on: warning
```

### Option 2: `pyproject.toml`

```toml
[tool.skill-lint]
disable = ["HRISK002", "OQUAL001"]
fail_on = "warning"
```

Precedence: CLI flags > `.skill-lint.yaml` > `pyproject.toml`

## Custom Rules

Write your own rules by extending the `Rule` base class:

```python
from skill_lint.scanner import Rule, Issue, register_rule

class MyRule(Rule):
    id = "CUSTOM_001"
    description = "Check for company-specific patterns"

    def check(self, ctx):
        issues = []
        if "legacy API" in ctx.content:
            issues.append(Issue(
                category="best-practice",
                severity="suggestion",
                message="References legacy API",
                fix="Use the new v2 API instead",
                rule_id=self.id,
            ))
        return issues

register_rule(MyRule())
```

Custom rule IDs must use the `CUSTOM_` prefix. The `ctx` object provides: `content`, `lines`, `regions`, `filepath`, `root`, `tokens`, and `content_text` (code-fence-filtered).

## Philosophy

1. **Help, don't restrict** — every finding is a suggestion, not a gate
2. **Show, don't enforce** — display impact, let users decide
3. **Honest numbers** — no inflated claims; validated across 15+ repos

## License

[Apache-2.0](LICENSE)
