opty

score, fix, and optimize AI agent configuration files

npx optymd scan

Why opty exists

AI coding agents read markdown files as their working instructions. Over months, these files grow stale. Duplicates creep in. Secrets get pasted for "just a second" and forgotten. Files swell past the context window until the agent can only read half of what you wrote.

opty is a linter for that problem. It scans the files, scores them on quality dimensions, fixes what is safely fixable, and keeps a backup of every change.

What it scans

file type	matches	scored on
agent	CLAUDE.md, agent.md	actionability, security, commands, architecture
soul	soul.md	persona clarity, behavioral rules, conciseness
skill	SKILL.md	trigger clarity, scope boundaries, actionability
memory	memory/*.md	recency, relevance, no duplicates
hook	hooks/*.md	trigger precision, side-effect warnings
tool	tools/*.md	arg clarity, failure modes

Commands

opty init <platform>: Scaffold a baseline config for claude or openclaw.
opty scan [path]: Detect files, surface issues, print a report.
opty score [path]: Calculate a quality score (0–100) and a grade (A–F).
opty fix --dry-run: Preview what will be fixed — nothing is written.
opty fix [path]: Apply safe fixes. A backup is written to .opty/backups/.
opty restore: Roll back the last fix from backup. Use --id <ts> for a specific snapshot.
opty verify [path]: Compare repo rules against git history and workflow evidence. --fail-on-violations exits 2 on violation.

Example report

$ opty scan .

  opty scan — claude
  _______________________________________________________

  5 files  |  Score: 72 / B  |  1 critical  4 warnings

  TRUNCATED FILES
  x  skills/bureau-dev/SKILL.md    2969 / 2000    (33% lost)

  DEAD REFERENCES
  !  skill.md            (referenced 2x)
  !  tailwind.config.js
  !  heartbeat.md

  NOTABLE FILES
  A  CLAUDE.md                       92    no issues
  B  skills/drizzle-ops/SKILL.md     74    no issues
  D  skills/bureau-dev/SKILL.md      47    2 minor

  BY TYPE
  agent    1 file    avg  ##########----  92
  skill    3 files   avg  ######--------  53
  config   1 file    avg  ########------  80

  FIX PRIORITY
  1. Trim 1+ files exceeding token limits
  2. Remove 4 dead file references
  3. Add scope boundaries to 2 skills

Scoring dimensions

Per-file — agent (CLAUDE.md)

actionability	22	ratio of actionable instructions
security	20	no leaked secrets
commands	15	build / test / dev documented
architecture	12	project structure documented
structure	10	headers, no placeholders
direction	8	clear directives, no contradictions
size fitness	8	within token budget
token efficiency	5	no duplicates or verbose phrases

Fleet-level — multiplicative factors

Each returns a 0.0–1.0 multiplier applied to the weighted file average:

role coverage — are required files present?
role separation — are files doing distinct jobs?
content coherence — no cross-file contradictions
codebase awareness — blind spots documented
reference integrity — no dead file references
token budget — within context window limits
skill routing — no conflicting skill trigger domains
injection control — files properly mapped to injection paths

Auto-fix behavior

opty fix applies only safe, reversible changes. Every run writes a timestamped backup to .opty/backups/. Undo with opty restore.

Replace leaked API keys with environment variable placeholders.
Replace connection strings with $DATABASE_URL.
Replace chmod 777 with chmod 755.
Remove duplicate paragraphs within a file.
Shorten verbose phrases ("in order to" → "to").

GitHub action

- uses: AytuncYildizli/opty/action@v1
  with:
    path: .
    fail-below: 50

Use mode: verify with fail-on-violations for CI rule enforcement:

- uses: AytuncYildizli/opty/action@v1
  with:
    path: .
    mode: verify
    fail-on-violations: true

Install

npm install -g optymd

Or one-off:

npx optymd scan
npx optymd scan CLAUDE.md