name: skillcraft
description: Lint, sync and scaffold agent-config files (SKILL.md, CLAUDE.md, AGENTS.md).
Use when checking, validating or regenerating agent-config files in a repository.
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.
1---2name: skillcraft3description: <!-- skillcraft:managed-source path=AGENTS.md -->4---5<!-- skillcraft:managed-source path=AGENTS.md -->67---8name: skillcraft9description: Lint, sync and scaffold agent-config files (SKILL.md, CLAUDE.md, AGENTS.md).10 Use when checking, validating or regenerating agent-config files in a repository.11---1213# skillcraft1415**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.1617## Install1819```bash20uv tool install skillcraft21# or: pip install skillcraft22```2324## Commands2526| Command | Purpose |27| --- | --- |28| `skillcraft lint [--check] [-f plain\|json\|github\|sarif]` | Run the rule set over discovered config files; exit 1 on any ERROR. |29| `skillcraft sync [--check] [--diff] [--adopt <file>]` | Regenerate managed targets from `AGENTS.md`; detect drift. |30| `skillcraft init [--name <name>]` | Scaffold a minimal `AGENTS.md` + `.skillcraft.toml`. |31| `skillcraft version` | Print the version. |3233## How it works3435- **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`.36- **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.37- **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`.38- **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`.3940## Rules4142| ID | Scope | Rule |43| --- | --- | --- |44| SC101 | SKILL | `name` is kebab-case, ≤64 chars |45| SC102 | SKILL | in a `skills/<name>/` folder, `name` matches the folder |46| SC103 | SKILL | `description` present, ≤1024 chars |47| SC104 | SKILL | body ≈ <5000 tokens (warn past 4000) |48| SC105 | SKILL | `description` ≥40 chars for triggerability (warn) |49| SC201 | CLAUDE | `@path` imports resolve, no cycles, ≤4 hops |50| SC202 | CLAUDE | line count <200 (warn), <500 (error) |51| SC203 | CLAUDE | `@imports` resolve inside the repo root (error) |52| SC204 | ALL | no skipped heading levels (warn) |53| SC301 | ALL | required frontmatter present iff the format requires it |54| SC302 | ALL | no merge-conflict markers in the body |55| SC304 | ALL | body ends with a trailing newline (warn) |56| SC401 | CURSOR | globs well-formed and the rule is reachable (error/warn) |57| SC402 | CURSOR | not both `alwaysApply: true` and `globs` (warn) |5859## Build & test6061```bash62uv sync63uv run ruff check64uv run pytest65uv run skillcraft lint # dogfood: lint skillcraft's own configs66uv run skillcraft sync --check # dogfood: no drift between AGENTS.md and targets67```6869## Layout7071```72src/skillcraft/ cli, ir, markers, tokens, config, discover73 lint/{runner,report} sync/engine scaffold/init74 plugins/{api,registry,builtin/{rules,converters}}75tests/ unit (ir, markers, rules, converters, sync, registry, config, discover) + cli e2e76```7778## License7980MIT.
dimanovikov