Metadata-Version: 2.4
Name: skillscheck
Version: 0.9.3
Summary: Validate agent skills against the agentskills.io specification
Project-URL: Repository, https://github.com/swival/skillscheck
Project-URL: Issues, https://github.com/swival/skillscheck/issues
Author-email: Frank Denis <github@pureftpd.org>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,cli,linter,skills,validation
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: click>=8.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: tiktoken>=0.7
Description-Content-Type: text/markdown

# skillscheck

A linter for agent skill definitions. It validates skill directories against the [agentskills.io specification](https://agentskills.io/specification) and tests compatibility with every major AI coding agent: Claude Code, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Roo Code, Swival, and Windsurf.

If you publish skills for AI agents, skillscheck catches problems before your users do. It checks frontmatter fields, naming conventions, directory structure, description quality, secret leaks, broken links, token budgets, and the agent-specific config files that each platform expects. When it finds something wrong, it tells you exactly what and where, with a check ID you can look up.

Also available as a [VSCode extension](https://marketplace.visualstudio.com/items?itemName=jedisct1.agent-skill-lint) ("Agent Skill Lint") for real-time feedback while editing.

## Installation

```sh
uvx skillscheck /path/to/skills-repo
```

No configuration files needed. Point it at a directory containing skills and it figures out the rest.

## What it checks

skillscheck organizes its diagnostics into four categories.

**Spec compliance** validates the core structure mandated by the agentskills.io specification: frontmatter presence and syntax, required fields like `name` and `description`, naming rules (lowercase, no leading or trailing hyphens, no consecutive hyphens), directory-name consistency, body length and token counts, allowed-tools validation against known tool names, and cross-skill duplicate detection.

**Quality** looks at things the spec does not cover but that matter in practice. It warns when descriptions are too short or lack "use when" hints that help agents trigger the skill correctly. It flags user-centric phrasing, keyword-stuffed descriptions, leaked secrets (AWS keys, GitHub tokens, private keys, `.env` files), binary files, and oversized assets. It detects extraneous files (README, LICENSE, Makefile) at the skill root and orphaned files in scripts/references/assets that are not referenced from SKILL.md. It walks every local markdown link and verifies the target exists, including fragment anchors, and catches unclosed code fences.

**Progressive disclosure** checks that reference files stay within reasonable token budgets and that the reference tree does not nest too deeply, following the specification's guidance on keeping skills scannable.

**Agent compatibility** is where skillscheck goes furthest. Each of the eight supported agents has its own adapter that understands the platform's conventions:

- **Claude Code** validates `plugin.json` and `marketplace.json` structure and cross-checks fields for consistency
- **Cursor** validates `.cursor/skills/` frontmatter fields and warns on deprecated `.cursorrules`
- **Gemini CLI** checks `gemini-extension.json` fields, metadata, and context file existence
- **GitHub Copilot** validates frontmatter fields in `.github/skills/` skill definitions
- **OpenAI Codex** validates `agents/openai.yaml` sidecars, interface, dependencies, and permissions
- **Roo Code** validates `.roo/skills/` frontmatter fields, warns on deprecated `.roorules` and `.clinerules`
- **Swival** checks description and body length limits
- **Windsurf** warns on deprecated `.windsurfrules`

Cross-agent checks detect name, version, and description mismatches between agent config files (e.g. `plugin.json` vs `gemini-extension.json`).

skillscheck auto-detects which agents are relevant based on the repository structure, or you can specify them explicitly.

## Options

```text
--agents claude,codex,copilot,cursor,gemini,roo,swival,windsurf
```

Run checks for specific agents. By default, skillscheck auto-detects which agents apply based on the files it finds. Pass `all` to check every agent regardless.

```text
--check agents,disclosure,quality,spec
```

Run only specific check categories.

```text
--fix
```

Auto-fix issues that have safe mechanical fixes: lowercasing names, collapsing consecutive hyphens, renaming directories to match the name field.

```text
--format json
```

Produce JSON output for CI pipelines and editor integrations.

```text
--strict
```

Treat warnings as errors and exit with code 1.

## Exit codes

| Condition                | Exit code |
| :----------------------- | :-------- |
| No errors                | 0         |
| Errors found             | 1         |
| `--strict` with warnings | 1         |

## CI integration

skillscheck works well in CI pipelines. Use `--format json` to get structured output and `--strict` to fail the build on warnings. A typical GitHub Actions step:

```yaml
- name: Lint skills
  run: uvx skillscheck ./skills --strict
```
