schliff: Instructions file for Codex

Schliff — agent instructions

Deterministic quality scorer for AI instruction files (Python, stdlib-only core, zero runtime dependencies). The engine lives in skills/schliff/scripts/; the web playground in playground/; the GitHub Action in action.yml.

Scope & composition

Use when you need to score or improve a SKILL.md, AGENTS.md, CLAUDE.md, or .cursorrules. Do not use it on a whole codebase — it grades one instruction file, not a repo. For a brand-new skill, use skill-creator instead; schliff improves existing files, it doesn't scaffold new ones.

• Input: one instruction-file path. Output: a deterministic per-dimension score plus a composite (text or --json); scoring writes nothing.
• Idempotent, no side effects — same input, same score, safe to re-run.
• Requires Python >= 3.10, no other runtime dependency; supported versions 3.10–3.13.

Setup

pip install -e .
pip install pytest ruff

Optional extras: pip install -e ".[judge]" (LLM-judge smoke-test only — core scoring must stay zero-dependency).

Build

pip install build
python -m build

Pure-Python wheel; nothing to compile.

Test

make test-unit          # pytest unit suite — run this before every commit
make lint               # ruff check skills/schliff/scripts/
make test-all           # unit + integration + self + proof suites

A single scorer test file runs fast: python3 -m pytest skills/schliff/tests/unit/test_operational_coverage.py -q.

Example: verify a scorer change end-to-end (score a real file with your edit):

python3 skills/schliff/scripts/cli.py score AGENTS.md --json

Expected output: JSON with composite_score, per-dimension scores, and format: agents.md. If operational_coverage is missing, your registry wiring is broken — check SCORER_REGISTRY["agents.md"].

Code style

• Ruff is the authority (pyproject.toml: E, F, W, I; line length 120). Run make lint before pushing — it gates Python and markdown (.markdownlint-cli2.jsonc), exactly as CI does.
• Core engine code (skills/schliff/scripts/) is stdlib-only — never add a runtime dependency there, because "pip install schliff, zero deps" is the product promise CI and the README both make.
• Scorers must be deterministic: no time, random, os.environ reads, or network in any scoring path, because same-input-same-score is the core guarantee. Tests pin this (test_purity_no_forbidden_imports).
• Prefer explicit error handling; no silent except: pass in scoring code.