Display Name
Schliff
Category
Tooling
Sub-Category
General
Primary Link
https://github.com/Zandereins/schliff
Author Name
Franz Paul
Author Link
https://github.com/Zandereins
License
MIT
Other License
No response
Description
Schliff is the Ruff for SKILL.md, CLAUDE.md, and AGENTS.md — a deterministic quality scorer for AI instruction files. Static analysis only (no LLM, no network, no randomness) gives a reproducible 0-100 score over 7 weighted dimensions. Run it as a pre-commit hook or GitHub Action: schliff verify <file> --min-score 75 is a clean CI gate; schliff suggest returns ranked fixes. Scores five formats; stdlib-only, zero dependencies.
Validate Claims
The scoring engine is deterministic — schliff score path/to/file.md produces identical output across runs and machines, because the headline composite is computed from a canonical, versioned weight registry with no LLM in the loop. The scorers are readable Python in skills/schliff/scripts/scoring/ and the weights are an open dict, not a hidden judge prompt. Reproducibility evidence: 120 public instruction files (30 each across SKILL.md, CLAUDE.md, AGENTS.md, .cursorrules) were scored end-to-end with the committed pipeline in scripts/launch/ (collect → score → aggregate); the methodology, aggregate findings (mean composite 61.69, 59% below grade C), and limits are written up in docs/launch/state-of-ai-instructions.md. A worked before/after case study is committed at docs/case-studies/shieldclaw/ (baseline-score.json → optimized-score.json), where a real SKILL.md moved from 68.3 [C] to 94.6 [A] after adding an eval suite and closing edge-case gaps.
Specific Task(s)
pip install schliff — installs from PyPI, zero external dependencies (core)schliff demo — prints a deterministic score breakdown for a bundled bad SKILL.md in under 1 secondschliff score <path> — score any instruction file (SKILL.md, CLAUDE.md, AGENTS.md, .cursorrules, system prompt) with the same engine; format auto-detectedschliff verify <path> --min-score 75 — CI gate; exits non-zero below the thresholdschliff doctor — scans all installed Claude Code skills and reports composite scores- Read docs/launch/state-of-ai-instructions.md for the 120-file real-world quality audit
Optional Claude Code integration (after bash install.sh):
/schliff:init <path> — bootstrap an eval suite + baseline for a skill/schliff:auto — autonomous improvement loop until plateau
Specific Prompt(s)
Standalone (no Claude Code needed):
pip install schliff
schliff demo
schliff score ~/.claude/skills/hydra/SKILL.md
schliff suggest ~/.claude/skills/hydra/SKILL.md
With Claude Code (after bash install.sh in the repo):
/schliff:init path/to/SKILL.md
/schliff:auto
For a one-shot gap analysis instead of the full improvement loop:
/schliff:analyze
### Additional Comments
v8.2.0 live on PyPI. Core is Python >= 3.10, stdlib-only with zero external dependencies; the optional `schliff[evolve]` / `schliff[judge]` extras add an LLM client for an opt-in evolution/smoke-test loop that is never part of the deterministic score. 1231 tests in the suite; CI is green. Anti-gaming detection covers padding, keyword stuffing, repetition, and structure-mimicry instead of rewarding them, via a dedicated guard layer (skills/schliff/scripts/scoring/guards.py).
This is a matured resubmit. Prior submissions (#1078, #1154, and the most recent #1620) were all closed for non-content reasons (repo too young / active cooldown / timing). Since then the project shipped through v8.2.0, added a committed before/after case study (docs/case-studies/shieldclaw/: 68.3 [C] → 94.6 [A]), and published a reproducible 120-file deterministic quality audit of public AI instruction files (docs/launch/state-of-ai-instructions.md). Referencing #1620 here for dedupe transparency — this is not a forgotten duplicate.
Schliff (German: "the finishing cut") — "Den letzten Schliff geben" means to give something its final polish.
### Recommendation Checklist
- [x] I have checked that this resource hasn't already been submitted
- [x] It has been over one week since the first public commit to the repo I am recommending
- [x] All provided links are working and publicly accessible
- [x] I do NOT have any other open issues in this repository
- [x] I am primarily composed of human-y stuff and not electrical circuits
Display Name
Schliff
Category
Tooling
Sub-Category
General
Primary Link
https://github.com/Zandereins/schliff
Author Name
Franz Paul
Author Link
https://github.com/Zandereins
License
MIT
Other License
No response
Description
Schliff is the Ruff for SKILL.md, CLAUDE.md, and AGENTS.md — a deterministic quality scorer for AI instruction files. Static analysis only (no LLM, no network, no randomness) gives a reproducible 0-100 score over 7 weighted dimensions. Run it as a pre-commit hook or GitHub Action:
schliff verify <file> --min-score 75is a clean CI gate;schliff suggestreturns ranked fixes. Scores five formats; stdlib-only, zero dependencies.Validate Claims
The scoring engine is deterministic —
schliff score path/to/file.mdproduces identical output across runs and machines, because the headline composite is computed from a canonical, versioned weight registry with no LLM in the loop. The scorers are readable Python in skills/schliff/scripts/scoring/ and the weights are an open dict, not a hidden judge prompt. Reproducibility evidence: 120 public instruction files (30 each across SKILL.md, CLAUDE.md, AGENTS.md, .cursorrules) were scored end-to-end with the committed pipeline in scripts/launch/ (collect → score → aggregate); the methodology, aggregate findings (mean composite 61.69, 59% below grade C), and limits are written up in docs/launch/state-of-ai-instructions.md. A worked before/after case study is committed at docs/case-studies/shieldclaw/ (baseline-score.json → optimized-score.json), where a real SKILL.md moved from 68.3 [C] to 94.6 [A] after adding an eval suite and closing edge-case gaps.Specific Task(s)
pip install schliff— installs from PyPI, zero external dependencies (core)schliff demo— prints a deterministic score breakdown for a bundled bad SKILL.md in under 1 secondschliff score <path>— score any instruction file (SKILL.md, CLAUDE.md, AGENTS.md, .cursorrules, system prompt) with the same engine; format auto-detectedschliff verify <path> --min-score 75— CI gate; exits non-zero below the thresholdschliff doctor— scans all installed Claude Code skills and reports composite scoresOptional Claude Code integration (after
bash install.sh):/schliff:init <path>— bootstrap an eval suite + baseline for a skill/schliff:auto— autonomous improvement loop until plateauSpecific Prompt(s)
Standalone (no Claude Code needed):
With Claude Code (after
bash install.shin the repo):For a one-shot gap analysis instead of the full improvement loop: