skillscheck 0.1.0__tar.gz

skillscheck-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+__pycache__/
+.swival/
+*~

skillscheck-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Frank Denis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

skillscheck-0.1.0/LOG.md

@@ -0,0 +1,277 @@
+# LOG
+
+## 2026-03-11: Agent Skills Specification Research
+
+**User asked:** Research which AI coding agents support the Agent Skills specification from agentskills.io, including what aspects they support, agent-specific extensions/deviations, and validation tools.
+
+**What I did:** Searched the web and fetched documentation from agentskills.io, GitHub repos (anthropics/skills, agentskills/agentskills), and official docs for Claude Code, OpenAI Codex, Gemini CLI, VS Code Copilot, Cursor, Windsurf, Roo Code, Kiro, Zed, Antigravity, Cline, and Qwen Code. Compiled detailed findings about spec support, frontmatter fields, discovery paths, agent-specific extensions, and validation tooling across 12+ agents.
+
+## 2026-03-11: Plan creation
+
+**User asked:** Write a plan for a Python app (uv) that validates a skills directory against the agentskills.io spec and agent expectations.
+
+**What I did:**
+- Fetched the complete Agent Skills specification from agentskills.io/specification
+- Explored ~/src/fastly-agent-skills (6 skills, existing validate.sh, claude-plugin/, gemini-extension.json)
+- Researched agent compatibility matrix (12+ agents)
+- Created PLAN.md with 4 check categories: spec compliance (frontmatter fields, naming, directory structure), quality (description, hygiene, links), agent compatibility (Claude Code plugin, Gemini extension, Codex, Copilot, Cursor, Windsurf, Roo Code), and progressive disclosure (token budgets, reference sizing)
+- Defined project architecture, CLI interface, output format, and implementation order
+
+## 2026-03-11: Plan revision from review feedback
+
+**User asked:** Addressed 5 findings (2 high, 3 medium) from plan review.
+
+**What I did:**
+- Finding 1 (high): Removed directory allowlist warning. The spec allows "any additional files or directories" — `scripts/`, `references/`, `assets/` are recognized as having special semantics, not enforced as the only allowed dirs.
+- Finding 2 (high): Replaced flat agent checklist with a plugin-style adapter architecture. Only Claude Code and Gemini CLI have concrete, documented rules → v1 adapters. Other agents (Codex, Copilot, Cursor, Windsurf, Roo Code) deferred to "future adapters" section with criteria for inclusion.
+- Finding 3 (medium): Added two-pass schema model. Base spec pass recognizes official fields. Agent extension pass recognizes per-adapter fields. Unknown fields get info-level notes (not warnings) since the spec doesn't forbid extras. `allowed-tools` now accepts string or list.
+- Finding 4 (medium): Replaced vague "markdown parses without errors" with concrete checks: frontmatter boundary validation, relative link extraction via regex, target existence verification. No markdown parser dependency.
+- Finding 5 (medium): Reordered implementation to build test fixtures of intentionally valid/invalid skills first (step 2), before any checks. `fastly-agent-skills` becomes one integration target (step 8), not the calibration source.
+
+## 2026-03-11: Second plan revision (3 findings + open question)
+
+**User asked:** Address 3 medium findings and one open question about exit codes.
+
+**What I did:**
+- Finding 1: `allowed-tools` list form now emits info note ("not portable base-spec syntax") when no active adapter authorizes it, instead of silently accepting both forms equally.
+- Finding 2: Link extraction narrowed to `[text](path)` and `![alt](path)` syntax only. Bare `path/file.md` scanning removed — too many false positives from prose/code. Fenced code blocks, inline code, and URLs are excluded.
+- Finding 3: Secret detection scoped to high-confidence filename patterns (`.env`, `.pem`, `.key`, `credentials.json`) and explicit token regexes (AWS `AKIA*`, GitHub `ghp_`/`gho_`/`ghs_`, PEM private key headers). Broad keyword scanning deferred to dedicated tools.
+- Open question: Added severity/exit-code table (error→1, warning→0, info→0; `--strict` promotes warnings to exit 1, info stays 0). Added JSON output structure with `skills` and `agents` as separate top-level keys.
+
+## 2026-03-11: Comprehensive test suite
+
+**User asked:** Create test fixtures and tests for all modules in the skillscheck project.
+
+**What I did:**
+- Created 12 static fixture directories under `tests/fixtures/` with SKILL.md files covering valid skills (minimal, full with references) and invalid skills (missing SKILL.md, uppercase name, hyphen-start name, consecutive hyphens, name-dir mismatch, missing description, description too long, bad frontmatter YAML, broken links, allowed-tools as list, unknown fields)
+- Created 6 test modules (124 tests total): `test_parser.py` (frontmatter splitting, skill parsing, discovery), `test_spec.py` (presence, name, description, optional fields, unknown fields, body, cross-skill checks), `test_quality.py` (description quality, file hygiene, link validation), `test_disclosure.py` (reference sizing, nesting), `test_agents.py` (Claude/Gemini adapters, adapter registry, cross-agent checks), `test_validator.py` (end-to-end validation, agent integration, result structure)
+- Fixed two bugs found during testing: (1) missing `Level` import in `skillscheck/agents/__init__.py` causing NameError in `cross_agent_check`, (2) `_check_consistency` in `skillscheck/agents/claude.py` crashing on non-dict JSON (AttributeError on list/string)
+- Added pytest as dev dependency and hatchling as build backend to `pyproject.toml`
+- All 124 tests pass
+
+## 2026-03-11: Implementation complete
+
+**User asked:** Build the application per the plan.
+
+**What I did:**
+- Implemented all modules: `models.py` (Diagnostic/SkillInfo/ValidationResult), `parser.py` (frontmatter splitting, skill discovery), `checks/spec.py` (1a-1g), `checks/quality.py` (2a-2c), `checks/disclosure.py` (4a-4c), `agents/claude.py` (3a), `agents/gemini.py` (3b), `agents/__init__.py` (adapter registry + cross-agent checks), `validator.py` (orchestrator), `cli.py` (click CLI with text/JSON output)
+- Integration test against ~/src/fastly-agent-skills: 6 skills validated, 0 errors, 3 warnings (2 secret token patterns in logging docs, 1 Claude plugin name mismatch), 2 info notes (token count, Gemini no context)
+- Exit codes work as designed: default exit 0 with warnings, `--strict` exit 1
+- 124 tests pass in 0.10s
+
+## 2026-03-11: Fix 4 findings (2 high, 2 medium)
+
+**User asked:** Fix adapter contract gaps, JSON output shape, allowed-tools list-form check, and code stripping.
+
+**What I did:**
+- Finding 1 (high, adapters): Claude adapter now validates version, description, author (must be object with name), keywords (must be string array), marketplace metadata.description, owner.name, plugin source, and description/version consistency. Gemini adapter now validates version and description fields.
+- Finding 2 (high, JSON shape): Introduced `SkillDiagnostics` dataclass with `spec`, `quality`, `disclosure` buckets. `ValidationResult.skills` is now `dict[str, SkillDiagnostics]`. JSON output emits `{"skills":{"name":{"spec":[...],"quality":[...]}}` so CI can distinguish spec-invalid from quality/disclosure findings.
+- Finding 3 (medium, allowed-tools): Added `allows_tools_list_syntax()` to adapter protocol. Info note now fires when no active adapter explicitly authorizes list syntax (Claude and Gemini both return False), instead of checking `bool(extension_fields)`.
+- Finding 4 (medium, code stripping): Extracted `mdutil.py` with `strip_code()` that removes fenced blocks, indented code blocks (4+ spaces/tab after blank line), AND inline code spans. Both `quality.py` and `disclosure.py` now use `mdutil.extract_local_link_targets()`.
+- Tests: 143 pass (up from 124). Added 19 new tests for expanded adapter validation, category buckets, and allowed-tools list-form with Claude active.
+
+## 2026-03-11: Fix 3 more findings (2 high, 1 medium)
+
+**User asked:** Fix `--agents all` false errors, plugin source path validation, and under-validated Claude fields.
+
+**What I did:**
+- Finding 1 (high): `--agents all` now filters to detected adapters (`a.detect(repo_root)`) instead of returning all adapters unconditionally. A Claude-only repo no longer gets Gemini missing-file errors.
+- Finding 2 (high): Marketplace plugin `source` paths are now resolved against repo root and validated as existing directories. `"source": "./missing-skills"` now emits `3a.marketplace-json.plugin-source-missing` error. Moved `root` parameter from unused `_check_plugin_json` to `_check_marketplace_json` where it's needed.
+- Finding 3 (medium): `plugin.json` now warns when `author` or `keywords` are missing (not just when present with wrong type). Author non-object and keywords non-list are now errors, not warnings. `marketplace.json` now flags non-object `metadata` (error: `3a.marketplace-json.metadata-type`) and non-object `owner` (error: `3a.marketplace-json.owner-type`) instead of silently skipping them.
+- Tests: 150 pass (up from 143). Added 7 new tests for missing author/keywords, non-object metadata/owner, source path resolution, and `--agents all` detection filtering.
+
+## 2026-03-11: /simplify code review cleanup
+
+**User asked:** Run /simplify to review code for reuse, quality, and efficiency.
+
+**What I did:** Three review agents identified findings across reuse, quality, and efficiency. Fixed all valid issues:
+- Removed unused imports: `SkillDiagnostics` from cli.py, `Path` from checks/spec.py
+- Used `CATEGORIES` constant in `SkillDiagnostics.to_dict()` instead of hardcoded field names
+- Merged identical `None`/`["all"]` branches in `get_adapters`
+- Deduplicated `SPEC_URL` — moved to `models.py`, imported by spec.py, quality.py, disclosure.py
+- Renamed `_ensure_skill` to `ensure_skill` (public API used by validator.py)
+- Extracted `load_json_object` helper into `agents/_util.py` to deduplicate JSON load/validate/type-check pattern across Claude and Gemini adapters
+- Refactored `cross_agent_check` to use a loop over config files and a loop over fields, eliminating copy-paste
+- Merged two `os.walk` passes in `discover_skills` into one
+- Fixed redundant fence-close condition in `mdutil._strip_fenced_blocks`
+- Used `stat().st_size` instead of reading entire files for token estimation in disclosure.py
+- All 152 tests pass
+
+## 2026-03-11: Humanize code and create TODO
+
+**User asked:** Make the code look like written by a human, remove redundant comments, create a TODO list.
+
+**What I did:**
+- Removed ~20 docstrings that just restated function names (e.g. `"""Parse a skill directory, extracting SKILL.md frontmatter and body."""` on `parse_skill()`)
+- Simplified formulaic module docstrings (e.g. `"""Main validation orchestrator."""` → describes the module's actual purpose)
+- Kept docstrings that carry genuine information (return tuple docs, discovery logic, frontmatter split semantics)
+- Created TODO.md with items grouped by category: agent adapters, checks, secret detection, CLI features, packaging/CI
+- All 152 tests still pass
+
+## 2026-03-11: Codex adapter
+
+**User asked:** Address the next TODO item (Codex adapter).
+
+**What I did:**
+- Researched OpenAI Codex's skills support by reading the openai/codex repo source: skill loader, model structs, TypeScript schemas, and example skills (babysit-pr, test-tui)
+- Codex discovers skills under `.codex/skills/` and `.agents/skills/`. Each skill can have an optional `agents/openai.yaml` sidecar with `interface`, `dependencies`, `policy`, and `permissions` sections
+- Implemented `CodexAdapter` in `skillscheck/agents/codex.py` (check ID prefix: `3d`):
+  - Detection: `.codex/` directory exists
+  - Per-skill validation of `agents/openai.yaml` when present: YAML parse, top-level field allowlist, interface field types, dependencies.tools structure (type/value required, known types: env_var/cli/mcp), policy.allow_implicit_invocation type check
+  - No Codex-specific frontmatter extensions (empty `known_frontmatter_fields`)
+- Registered adapter in `ALL_ADAPTERS` in `agents/__init__.py`
+- Added 23 new tests covering detection, valid/invalid YAML, type errors, unknown fields, dependencies, and policy
+- Updated existing `test_explicit_all` and added `test_auto_detect_codex`
+- All 175 tests pass (up from 152)
+
+## 2026-03-11: Codex adapter fixes (2 medium findings)
+
+**User asked:** Fix two gaps: (1) `permissions` accepted in schema but never validated, (2) detection missed `.agents/` directory.
+
+**What I did:**
+- Finding 1: Added `_check_permissions()` that validates the `permissions` section of `openai.yaml` — must be a mapping, known sub-keys (`network`, `file_system`, `macos`), each sub-key type-checked (network/macos must be mappings, file_system.read/write must be lists)
+- Finding 2: `detect()` now checks for `.codex/` or `.agents/` directory, matching both paths Codex uses for skill discovery
+- Added 10 new tests: 8 permissions tests (not-mapping, unknown fields, network/fs/macos type checks, valid) and 2 detection tests (.agents dir, both dirs)
+- All 185 tests pass (up from 175)
+
+## 2026-03-11: Copilot adapter research
+
+**User asked:** Research how VS Code Copilot / GitHub Copilot handles the Agent Skills specification from agentskills.io, covering discovery paths, sidecar files, frontmatter extensions, configuration files, and allowed-tools handling.
+
+**What I did:**
+- Fetched the agentskills.io specification, client implementation guide, and what-are-skills pages
+- Fetched VS Code Copilot docs: customization overview, agent-skills, prompt-files, custom-instructions, custom-agents, copilot-settings reference, concepts
+- Fetched GitHub Copilot docs: repository custom instructions, building extensions
+- Read the agentskills/agentskills skills-ref reference library source code (validator.py, parser.py, models.py)
+- Compiled comprehensive findings about Copilot's skill discovery, configuration settings, frontmatter extensions, file formats, and cross-client conventions
+
+## 2026-03-11: Copilot adapter implementation
+
+**User asked:** Address the next TODO item (Copilot adapter).
+
+**What I did:**
+- Copilot discovers skills from `.github/skills/` (native), plus configurable paths via `chat.agentSkillsLocations`. No sidecar config files (unlike Codex's `agents/openai.yaml`)
+- Copilot extends base spec frontmatter with three fields: `argument-hint` (string), `user-invocable` (boolean), `disable-model-invocation` (boolean)
+- Implemented `CopilotAdapter` in `skillscheck/agents/copilot.py` (check ID prefix: `3e`):
+  - Detection: `.github/skills/` directory exists
+  - Per-skill frontmatter validation: boolean fields type-checked, string fields type-checked
+  - Known frontmatter fields reported so spec checker doesn't flag them as unknown
+- Registered adapter in `ALL_ADAPTERS` in `agents/__init__.py`
+- Added 13 new tests: detection (present, absent, .github without skills), frontmatter field types, valid skills, multiple errors, multiple skills, auto-detect
+- Updated `test_explicit_all` and added `test_auto_detect_copilot`
+- All 198 tests pass (up from 185)
+
+## 2026-03-11: Fix Copilot adapter (1 high, 1 medium)
+
+**User asked:** Fix two findings: (1) `_check_frontmatter` crashes on `None` frontmatter, (2) adapter validates all skills instead of only Copilot skills under `.github/skills/`.
+
+**What I did:**
+- Finding 1 (high): `_check_frontmatter` now uses `skill.frontmatter or {}` instead of bare `skill.frontmatter`, matching the pattern used by `spec.py` and `quality.py`. Skills with parse errors no longer crash.
+- Finding 2 (medium): `check()` now filters skills by `dir_path` prefix — only skills under `<repo_root>/.github/skills/` are checked. Non-Copilot skills elsewhere in the repo are skipped.
+- Added 3 new tests: `test_none_frontmatter_no_crash`, `test_non_copilot_skill_ignored`, `test_copilot_skill_checked_non_copilot_skipped`
+- Updated `_make_copilot_skill` helper to place skills under `.github/skills/` instead of repo root
+- All 201 tests pass (up from 198)
+
+## 2026-03-11: Cursor adapter
+
+**User asked:** Implement the next TODO item (Cursor adapter).
+
+**What I did:**
+- Researched Cursor's Agent Skills support: discovers skills from `.cursor/skills/` (project) and `.agents/skills/` (cross-client), with `.cursor/` directory as detection signal
+- Cursor extends base spec frontmatter with `disable-model-invocation` (boolean) — same field Copilot uses, prevents auto-invocation by the agent
+- No sidecar config files (unlike Codex's `agents/openai.yaml` or Claude's `plugin.json`)
+- Implemented `CursorAdapter` in `skillscheck/agents/cursor.py` (check ID prefix: `3f`):
+  - Detection: `.cursor/` directory exists
+  - Per-skill frontmatter validation for skills under `.cursor/skills/` or `.agents/skills/`
+  - Legacy `.cursorrules` file detection — emits deprecation warning pointing to `.cursor/rules/`
+- Registered adapter in `ALL_ADAPTERS` in `agents/__init__.py`
+- Added 16 new tests: detection (present, absent, dir without skills subdir), frontmatter type checks, None frontmatter safety, `.agents/skills/` path support, non-Cursor skill filtering, `.cursorrules` deprecation warning, auto-detect integration
+- Updated `test_explicit_all` to include Cursor setup
+- All 217 tests pass (up from 201)
+
+## 2026-03-11: Implement all TODO checks and secret detection
+
+**User asked:** Implement all checks from the TODO list.
+
+**What I did:**
+- **Semver validation** (`1c.version.format`): Added `version` to `BASE_SPEC_FIELDS` and validates against semver regex (MAJOR.MINOR.PATCH with optional pre-release/build metadata) when present. Warning-level.
+- **SPDX license validation** (`1c.license.spdx`): Uses `packaging.licenses.canonicalize_license_expression()` to validate SPDX identifiers. Warning-level.
+- **Duplicate descriptions** (`1g.duplicate-description`): Extended `check_cross_skill` to track descriptions (case-insensitive) and warn when two skills share identical description text.
+- **Placeholder descriptions** (`1b.description.placeholder`): Added 10 regex patterns matching common placeholders ("TODO", "A skill that", "This skill", "...", "FIXME", "TBD", "PLACEHOLDER", "Description goes here", "Enter description", "Replace this"). Warning-level.
+- **Body heading check** (`1e.body.no-heading`): Checks if SKILL.md body starts with a markdown heading (`#`). Info-level note if not.
+- **Stale allowed-tools** (`1c.allowed-tools.unknown-tool`): Maintains a set of known tool names across agents (Claude Code, Codex, etc.) plus `mcp__*` prefix matching. Info-level note for unrecognized tools. Works with both string and list forms.
+- **Secret detection additions**: Added GitLab PAT (`glpat-`), Slack tokens (`xoxb-`, `xoxp-`, `xapp-`), base64-encoded private keys (`LS0tLS1CRUdJTi`), and `.env.local`/`.env.production`/`.env.staging`/`.env.development` filename patterns.
+- Added 30 new tests covering all new checks
+- All 248 tests pass (up from 218)
+
+## 2026-03-11: Fix 3 spec-model findings (2 high, 1 medium)
+
+**User asked:** Fix three findings where the tool contradicted the spec it cites.
+
+**What I did:**
+- Finding 1 (high, license): Removed SPDX-only validation of `license` field. The spec says "license name or reference to a bundled license file" and gives `Proprietary. LICENSE.txt has complete terms` as its own example — freeform strings are valid. No validation beyond type-checking is appropriate.
+- Finding 2 (high, allowed-tools): `_is_known_tool()` now strips parenthesized arguments before lookup (`Bash(git:*)` → `Bash`). The spec's own example `allowed-tools: Bash(git:*) Bash(jq:*) Read` previously produced false `unknown-tool` notes.
+- Finding 3 (medium, version): Removed `version` from `BASE_SPEC_FIELDS` and dropped the semver check. The spec lists only 6 top-level fields (name, description, license, compatibility, metadata, allowed-tools). The spec example puts version under `metadata`, not as a top-level field. Top-level `version:` is now correctly flagged as an unknown field by the two-pass model.
+- Replaced `TestVersionValidation` (5 tests) and `TestLicenseValidation` (3 tests) with `TestVersionField` (2 tests verifying unknown-field behavior) and `TestLicenseField` (3 tests verifying freeform acceptance). Added `test_parenthesized_tool_args_recognized`.
+- All 246 tests pass (down from 248 — net -2 from removing 8 wrong tests and adding 6 correct ones)
+
+## 2026-03-11: Windsurf adapter
+
+**User asked:** Implement the Windsurf adapter.
+
+**What I did:**
+- Researched Windsurf's Agent Skills support: discovers skills from `.windsurf/skills/` (project) and `.agents/skills/` (cross-client), with `.windsurf/` directory as detection signal
+- No Windsurf-specific frontmatter extensions beyond the base spec. No sidecar config files.
+- Legacy `.windsurfrules` file (pre-Wave 8) deprecated in favor of `.windsurf/rules/`
+- Implemented `WindsurfAdapter` in `skillscheck/agents/windsurf.py` (check ID prefix: `3g`):
+  - Detection: `.windsurf/` directory exists
+  - `.windsurfrules` deprecation warning
+  - Empty `known_frontmatter_fields` (no extensions)
+- Registered adapter in `ALL_ADAPTERS` in `agents/__init__.py`
+- Added 8 new tests: detection (present, absent), empty frontmatter fields, no list tools syntax, clean repo, `.windsurfrules` deprecation warning, auto-detect integration
+- Updated `test_explicit_all` to include Windsurf setup
+- All 254 tests pass (up from 246)
+
+## 2026-03-11: Roo Code skills research
+
+**User asked:** Research how Roo Code handles skills: discovery paths, SKILL.md frontmatter extensions, sidecar config files, deprecated paths, and detection markers.
+
+**What I did:**
+- Fetched Roo Code official docs: docs.roocode.com/features/skills, /features/custom-modes, /features/custom-instructions, /advanced-usage/available-tools/skill
+- Fetched DeepWiki analysis of Roo Code skill configuration
+- Fetched Kilo Code (Roo Code fork) technical explanation gist
+- Read actual source code from GitHub via `gh api`: `src/services/skills/SkillsManager.ts` (719 lines), `src/shared/skills.ts`, `packages/types/src/skills.ts`, `src/core/prompts/sections/skills.ts`, `src/core/tools/SkillTool.ts`, `src/core/prompts/tools/native-tools/skill.ts`, `src/services/skills/skillInvocation.ts`, `src/services/roo-config/index.ts`, `src/core/prompts/sections/custom-instructions.ts`
+- Compiled comprehensive findings covering all 5 questions
+
+## 2026-03-11: Roo Code and Swival adapters
+
+**User asked:** Implement the Roo Code adapter and the Swival adapter.
+
+**What I did:**
+- Implemented `RooAdapter` in `skillscheck/agents/roo.py` (check ID prefix: `3h`):
+  - Detection: `.roo/` directory, `.roomodes` file, or `.roorules` file
+  - Frontmatter extensions: `modeSlugs` (list of strings) and `mode` (string, deprecated)
+  - Validates `modeSlugs` must be list of strings, `mode` must be string
+  - Info-level note when deprecated `mode` field is used (recommends `modeSlugs`)
+  - Deprecation warnings for `.roorules` and `.clinerules` legacy files
+  - Skills checked under `.roo/skills/` and `.agents/skills/` paths
+- Implemented `SwivalAdapter` in `skillscheck/agents/swival.py` (check ID prefix: `3i`):
+  - Detection: `swival.toml` file or `.swival/` directory
+  - No Swival-specific frontmatter extensions
+  - Warns when description exceeds Swival's 1024-char limit
+  - Warns when body exceeds Swival's 20,000-char limit
+  - Skills checked under `skills/` path
+- Registered both adapters in `ALL_ADAPTERS` in `agents/__init__.py`
+- Added 33 new tests: Roo (19 tests — detection, frontmatter types, deprecated fields, path filtering, auto-detect) and Swival (14 tests — detection, limits, path filtering, auto-detect)
+- Updated `test_explicit_all` to include both new adapters
+- All 287 tests pass (up from 254)
+
+## 2026-03-11: Replace token estimation with tiktoken
+
+**User asked:** Use tiktoken for proper token counting instead of the `chars // 4` heuristic.
+
+**What I did:**
+- Added `tiktoken>=0.7` as a project dependency
+- Created `skillscheck/tokenutil.py` with `count_tokens(text)` and `estimate_file_tokens(path)` using the `cl100k_base` encoding (encoder shared across calls via module-level cache)
+- Updated `checks/spec.py` (body token estimation) and `checks/disclosure.py` (reference file sizing) to use the new functions instead of `len(text) // 4`
+- All 287 tests still pass — existing test data was constructed to be above/below thresholds regardless of counting method

skillscheck-0.1.0/Makefile

@@ -0,0 +1,25 @@
+.PHONY: all install test lint format check clean dist
+
+all: check test
+
+install:
+	uv sync
+
+test:
+	uv run python -m pytest tests/ -v
+
+lint:
+	uv run ruff check skillscheck/ tests/
+
+format:
+	uv run ruff format skillscheck/ tests/
+
+check: lint
+	uv run ruff format --check skillscheck/ tests/
+
+clean:
+	rm -rf dist/ __pycache__ skillscheck/__pycache__ tests/__pycache__ .pytest_cache
+	find . -name '*.pyc' -delete
+
+dist: clean
+	uv build

skillscheck-0.1.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: skillscheck
+Version: 0.1.0
+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 SKILL.md files
+
+A CLI tool that validates agent skill directories against the [agentskills.io specification](https://agentskills.io/specification) and checks compatibility with AI coding agents (Claude Code, Gemini CLI, Codex, Copilot, Cursor, Roo Code, Windsurf, Swival).
+
+## Installation / Usage
+
+```sh
+uvx skillscheck /path/to/skills-repo
+```
+
+### Options
+
+- `--format json`: JSON output for CI pipelines
+- `--strict`: treat warnings as errors (exit 1)
+- `--agents claude,gemini,codex,copilot,cursor,roo,windsurf,swival`: run specific agent adapter checks (auto-detects if omitted, or `all`)
+- `--check spec,quality,disclosure,agents`: run specific check categories
+
+### Check categories
+
+- `spec`: core specification compliance (frontmatter fields, naming, directory structure)
+- `quality`: description quality, file hygiene, broken links, secret detection
+- `disclosure`: progressive disclosure (reference file sizing, nesting depth)
+- `agents`: agent-specific config validation (Claude plugin.json, Gemini extension.json, Codex openai.yaml, Copilot/Cursor/Roo/Windsurf/Swival conventions)
+
+### Exit codes
+
+| Condition                | Exit code |
+| :----------------------- | :-------- |
+| No errors                | 0         |
+| Errors found             | 1         |
+| `--strict` with warnings | 1         |