{"id":47301463,"url":"https://github.com/bitflight-devops/skilllint","last_synced_at":"2026-04-02T17:42:46.227Z","repository":{"id":341456488,"uuid":"1165773501","full_name":"bitflight-devops/skilllint","owner":"bitflight-devops","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-24T13:11:49.000Z","size":12379,"stargazers_count":3,"open_issues_count":7,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-24T19:56:59.699Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bitflight-devops.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-24T14:29:51.000Z","updated_at":"2026-03-24T13:11:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bitflight-devops/skilllint","commit_stats":null,"previous_names":["bitflight-devops/agentskills-linter","bitflight-devops/skilllint"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/bitflight-devops/skilllint","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitflight-devops%2Fskilllint","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitflight-devops%2Fskilllint/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitflight-devops%2Fskilllint/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitflight-devops%2Fskilllint/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitflight-devops","download_url":"https://codeload.github.com/bitflight-devops/skilllint/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitflight-devops%2Fskilllint/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31312336,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-17T03:05:14.366Z","updated_at":"2026-04-02T17:42:46.215Z","avatar_url":"https://github.com/bitflight-devops.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# skilllint\n\n[![PyPI version](https://img.shields.io/pypi/v/skilllint.svg)](https://pypi.org/project/skilllint/)\n[![Python versions](https://img.shields.io/pypi/pyversions/skilllint.svg)](https://pypi.org/project/skilllint/)\n[![License](https://img.shields.io/pypi/l/skilllint.svg)](https://github.com/bitflight-devops/skilllint/blob/main/LICENSE)\n[![CI](https://github.com/bitflight-devops/skilllint/actions/workflows/test.yml/badge.svg)](https://github.com/bitflight-devops/skilllint/actions/workflows/test.yml)\n\nStatic analysis linter for AI agent plugins, skills, and agents — for Claude Code, Cursor, Codex, and any [agentskills.io](https://agentskills.io)-compatible platform.\n\n---\n\n## What it does\n\n`skilllint` validates the structure and content of AI agent files: plugins, skills, agents, and commands. It catches broken references, missing frontmatter, oversized skills, invalid hook configurations, and more — before they cause silent failures at runtime.\n\n```\n$ skilllint check plugins/my-plugin\n\nplugins/my-plugin/skills/my-skill/SKILL.md\n  SK006  Token count 14823 exceeds recommended limit of 8192\n\nplugins/my-plugin/agents/my-agent.md\n  NR001  Namespace reference 'other-plugin:some-skill' — plugin directory not found\n\n2 errors in 2 files\n```\n\n---\n\n## Installation\n\n```bash\npip install skilllint\n```\n\nOr with [uv](https://docs.astral.sh/uv/):\n\n```bash\nuv add skilllint          # add to a project\nuv tool install skilllint # install as a global tool\n```\n\n**Requires Python 3.11–3.14.**\n\n---\n\n## Quick start\n\n```bash\n# Validate a plugin directory\nskilllint check plugins/my-plugin\n\n# Validate a single skill file\nskilllint check plugins/my-plugin/skills/my-skill/SKILL.md\n\n# Validate everything and show a summary\nskilllint check --show-summary plugins/\n\n# Auto-fix issues where possible\nskilllint check --fix plugins/my-plugin\n\n# Count tokens in any markdown file\nskilllint check --tokens-only .claude/CLAUDE.md\n```\n\nExit codes: `0` = all checks passed · `1` = validation errors · `2` = usage error\n\n---\n\n## Pre-commit hook\n\nAdd to `.pre-commit-config.yaml`:\n\n```yaml\nrepos:\n  - repo: https://github.com/bitflight-devops/skilllint\n    rev: v1.0.0\n    hooks:\n      - id: skilllint\n```\n\n---\n\n## Platform support\n\n`skilllint` ships with adapters for three platforms and supports third-party adapters via Python entry points:\n\n| Platform | Adapter ID | Bundled |\n|---|---|---|\n| [Claude Code](https://claude.ai/code) | `claude-code` | ✓ |\n| [Cursor](https://cursor.sh) | `cursor` | ✓ |\n| [OpenAI Codex](https://platform.openai.com/docs/codex) | `codex` | ✓ |\n| OpenCode, Gemini, and others | — | via entry points |\n\nRestrict validation to one platform:\n\n```bash\nskilllint check --platform claude-code plugins/my-plugin\n```\n\n---\n\n## What gets validated\n\n| Code | Category | Description |\n|---|---|---|\n| FM001–FM010 | Frontmatter | Required fields, valid values, schema compliance |\n| SK001–SK009 | Skill | Description quality, token limits, complexity, internal links |\n| AS001–AS006 | AgentSkills | Cross-platform open standard compliance |\n| LK001–LK002 | Links | Markdown link validity and broken reference detection |\n| PD001–PD003 | Progressive disclosure | Directory structure for references/, examples/, scripts/ |\n| PL001–PL006 | Plugin | Structure, manifest correctness, marketplace layout, subprocess safety |\n| HK001–HK005 | Hook | Script existence, configuration validity |\n| NR001–NR002 | Namespace refs | Cross-plugin skill/agent/command references |\n| SL001 | Symlinks | Symlink hygiene within plugin directory |\n| TC001 | Token count | Token count reporting and threshold enforcement |\n| PR001–PR005 | Plugin registration | Capability registration completeness and correctness in plugin.json |\n| PA001 | Plugin agent | Plugin-packaged agents: `hooks` / `mcpServers` / `permissionMode` unsupported per Anthropic (ignored at load; cite sub-agents doc) |\n\n---\n\n## CLI reference\n\n```\nUsage: skilllint [OPTIONS] COMMAND [ARGS]...\n\nCommands:\n  check   Validate Claude Code plugins, skills, agents, and commands.\n  rule    Show documentation for a validation rule.\n  rules   List all available validation rules.\n\nOptions:\n  --help  Show this message and exit.\n```\n\n### check\n\n```\nUsage: skilllint check [OPTIONS] [PATHS]...\n\nArguments:\n  paths              Paths to validate\n\nOptions:\n  --check            Validate only, don't auto-fix\n  --fix              Auto-fix issues where possible\n  --verbose, -v      Show detailed output\n  --no-color         Disable color\n  --tokens-only      Output token count only\n  --show-progress    Show per-file status\n  --show-summary     Show summary panel\n  --filter TEXT      Glob pattern to match files within a directory\n  --filter-type TEXT Filter type (skills | agents | commands)\n  --platform TEXT    Platform adapter\n  --help             Show this message and exit\n```\n\n### rules\n\n```\nUsage: skilllint rules [OPTIONS]\n\nOptions:\n  --platform, -p TEXT  Filter rules by platform\n  --category, -c TEXT  Filter rules by category\n  --severity, -s TEXT  Filter rules by severity (error, warning, info)\n  --help               Show this message and exit\n```\n\n### rule\n\n```\nUsage: skilllint rule [OPTIONS] RULE_ID\n\nArguments:\n  rule_id  Rule identifier (e.g., \"SK001\", \"FM002\", \"AS001\")  [required]\n\nOptions:\n  --help   Show this message and exit\n```\n\n### docs\n\nCache and query vendor documentation pages for offline use.\n\n```\nUsage: skilllint docs [OPTIONS] COMMAND [ARGS]...\n\nCommands:\n  fetch     Fetch a documentation page or return a cached copy.\n  latest    Find the most recent cached file for a page name.\n  sections  Print a table of sections in a cached markdown file.\n  section   Extract the text of a named section from a cached markdown file.\n  verify    Verify a cached file against its .meta.json integrity sidecar.\n```\n\n#### docs fetch\n\n```\nUsage: skilllint docs fetch [OPTIONS] URL\n\nArguments:\n  url                   Documentation URL to fetch or serve from cache.\n\nCache Options:\n  --ttl FLOAT           Cache time-to-live in hours before a refresh is attempted.  [default: 4.0]\n  --force               Skip the freshness check and always attempt a network fetch.\n\nOptions:\n  --help                Show this message and exit.\n```\n\nPrints the cached file path to stdout. Status messages go to stderr. Exits 1 when no\ncache exists and the network is unavailable.\n\n#### docs latest\n\n```\nUsage: skilllint docs latest [OPTIONS] PAGE_NAME\n\nArguments:\n  page_name             Filesystem-safe page name (e.g. 'claude-code--settings').\n\nOptions:\n  --help                Show this message and exit.\n```\n\nPrints the file path to stdout. Exits 1 when no cached file exists for that page name.\n\n#### docs sections\n\n```\nUsage: skilllint docs sections [OPTIONS] FILE_PATH\n\nArguments:\n  file_path             Path to the cached markdown file to index.\n\nOptions:\n  --help                Show this message and exit.\n```\n\nPrints a table of headings with their line ranges to stdout.\n\n#### docs section\n\n```\nUsage: skilllint docs section [OPTIONS] FILE_PATH HEADING\n\nArguments:\n  file_path             Path to the cached markdown file.\n  heading               Heading text or markdown anchor slug to locate.\n\nOptions:\n  --help                Show this message and exit.\n```\n\nPrints the full text of the matching section to stdout. Exits 1 when the heading is not found.\n\nHeading matching is case-insensitive and accepts two forms:\n\n- Heading text: `\"Hook input and output\"`\n- Markdown anchor slug: `\"hook-input-and-output\"`\n\nLeading `#` characters are stripped before comparison.\n\n#### docs verify\n\n```\nUsage: skilllint docs verify [OPTIONS] FILE_PATH\n\nArguments:\n  file_path             Path to the cached markdown file to verify.\n\nOptions:\n  --help                Show this message and exit.\n```\n\nExits 0 when the file is intact. Exits 1 when the file has been modified or when no\nsidecar exists.\n\nAll four command names are aliases for the same tool:\n\n```bash\nskilllint   # primary\nagentlint   # alias\npluginlint  # alias\nskillint    # alias\n```\n\n---\n\n## Vendor documentation cache\n\n`skilllint docs` provides an offline-first cache for vendor documentation pages. Pages are\nfetched once and stored locally; subsequent calls within the TTL window are served from\ndisk without a network request. When the TTL has expired but the network is unavailable,\nthe stale copy is served automatically.\n\nCached files are written to `.claude/vendor/sources/` with filenames in the format\n`{page-name}-{YYYY-MM-DD-HHMM}.md`. Each file is accompanied by a `.meta.json` integrity\nsidecar that records the SHA-256 digest, byte count, source URL, and fetch timestamp.\n\n```bash\n# Cache a documentation page (default TTL: 4 hours)\nskilllint docs fetch https://docs.anthropic.com/en/docs/claude-code/settings.md\n\n# Force a network refresh regardless of TTL\nskilllint docs fetch https://docs.anthropic.com/en/docs/claude-code/settings.md --force\n\n# Find the most recently cached copy of a page\nskilllint docs latest claude-code--settings\n\n# List all sections with line ranges\nskilllint docs sections .claude/vendor/sources/claude-code--settings-2025-01-01-1200.md\n\n# Extract a section by heading text or markdown anchor slug\nskilllint docs section .claude/vendor/sources/claude-code--settings-2025-01-01-1200.md \"Hook input and output\"\nskilllint docs section .claude/vendor/sources/claude-code--settings-2025-01-01-1200.md \"hook-input-and-output\"\n\n# Verify a cached file against its sidecar\nskilllint docs verify .claude/vendor/sources/claude-code--settings-2025-01-01-1200.md\n```\n\nSection extraction uses [marko](https://github.com/frostming/marko) for AST-based\nmarkdown parsing, so `#` characters inside fenced code blocks are never mistaken for\nheadings.\n\nThe same functionality is available as a standalone script that does not require\n`skilllint` to be installed:\n\n```bash\nuv run --script scripts/fetch_doc_source.py https://docs.anthropic.com/en/docs/claude-code/settings.md\n```\n\n---\n\n## Third-party adapters\n\nRegister a custom platform adapter via Python entry points in your `pyproject.toml`:\n\n```toml\n[project.entry-points.\"skilllint.adapters\"]\nmy-platform = \"my_package.adapter:MyPlatformAdapter\"\n```\n\nYour adapter must implement the `AdapterProtocol` interface from `skilllint.adapters.protocol`.\n\n---\n\n## Links\n\n- [GitHub repository](https://github.com/bitflight-devops/skilllint)\n- [Issue tracker](https://github.com/bitflight-devops/skilllint/issues)\n- [PyPI](https://pypi.org/project/skilllint/)\n- [agentskills.io](https://agentskills.io)\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitflight-devops%2Fskilllint","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitflight-devops%2Fskilllint","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitflight-devops%2Fskilllint/lists"}