skillcraft

ESLint + Jest for agent-config files. skillcraft lints, syncs and scaffolds the fragmented ecosystem of SKILL.md, CLAUDE.md, AGENTS.md, .cursor/rules, .claude/rules and copilot-instructions. One canonical source, many managed targets, drift detection in CI.

Install

uv tool install skillcraft
# or: pip install skillcraft

Commands

Command	Purpose
skillcraft lint [--check] [-f plain|json|github|sarif]	Run the rule set over discovered config files; exit 1 on any ERROR.
skillcraft sync [--check] [--diff] [--adopt <file>]	Regenerate managed targets from AGENTS.md; detect drift.
skillcraft init [--name <name>]	Scaffold a minimal AGENTS.md + .skillcraft.toml.
skillcraft version	Print the version.

How it works

• Canonical source = AGENTS.md (vendor-neutral, schema-less). Richer metadata (name, description, scope, license, …) rides in invisible <!-- skillcraft:meta <json> --> comments — valid markdown to every consumer, machine-readable to skillcraft.
• IR: ConfigDoc. Every parser emits it, every renderer consumes it. Same-format parse→render is lossless; extra_frontmatter escape hatch guarantees no field is silently dropped.
• Sync. skillcraft sync renders each target from the canonical doc and writes it with a <!-- skillcraft:managed-source path=AGENTS.md --> marker. skillcraft sync --check exits 1 if any managed target drifted (CI). Unmanaged files are never overwritten; opt in with --adopt.
• Plugins. Subclass Rule or Converter, decorate with @register_rule / @register_converter, and (for external packages) declare an entry-point in skillcraft.rules / skillcraft.converters. See CONTRIBUTING.md.

Rules

ID	Scope	Rule
SC101	SKILL	name is kebab-case, ≤64 chars
SC102	SKILL	in a skills/<name>/ folder, name matches the folder
SC103	SKILL	description present, ≤1024 chars
SC104	SKILL	body ≈ <5000 tokens (warn past 4000)
SC105	SKILL	description ≥40 chars for triggerability (warn)
SC201	CLAUDE	@path imports resolve, no cycles, ≤4 hops
SC202	CLAUDE	line count <200 (warn), <500 (error)
SC203	CLAUDE	@imports resolve inside the repo root (error)
SC204	ALL	no skipped heading levels (warn)
SC301	ALL	required frontmatter present iff the format requires it
SC302	ALL	no merge-conflict markers in the body
SC304	ALL	body ends with a trailing newline (warn)
SC401	CURSOR	globs well-formed and the rule is reachable (error/warn)
SC402	CURSOR	not both alwaysApply: true and globs (warn)

Build & test

uv sync
uv run ruff check
uv run pytest
uv run skillcraft lint          # dogfood: lint skillcraft's own configs
uv run skillcraft sync --check  # dogfood: no drift between AGENTS.md and targets

Layout

src/skillcraft/   cli, ir, markers, tokens, config, discover
                  lint/{runner,report}  sync/engine  scaffold/init
                  plugins/{api,registry,builtin/{rules,converters}}
tests/            unit (ir, markers, rules, converters, sync, registry, config, discover) + cli e2e

License

MIT.