# Sufsufik > SUFSUFIK — Skill Usage Feedback. A skill-fixing skill. When a SKILL is at fault (wrong or stale instructions, a bundled script that crashes, a missing step) log the defect, the workaround you used, and what would have PREVENTED it; /suf-fix later turns that into a permanent fix — a code guard, or a new hook — so nobody needs the workaround again. Use when a skill misbehaves, when you have to work around a skill's instructions, when asked to review or drain the skill-feedback queue, or on /suf-fix. Do NOT use for your own mistakes, missing features, or environment problems. - Skill: `emircbngl/sufsufik` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add emircbngl/sufsufik` - Raw SKILL.md: https://api.skillmd.com/api/skills/emircbngl/sufsufik/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: emircbngl (https://skillmd.com/u/emircbngl) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/emircbngl/sufsufik --- # SUFSUFIK — a skill-fixing skill Skills carry defects that only surface in real use, and the agent that hits one invents a workaround and moves on. That workaround is the problem: the next agent pays the same cost, and if anyone writes it down it rots into a lie the moment the skill is fixed. So this is not a bug tracker. It is a two-stage fixer: 1. **Log** the defect *with the workaround and what would have prevented it* — you just hit it, so you know best. 2. **`/suf-fix`** turns that into a **permanent fix that makes the workaround unnecessary** — a code guard, a refusal, or a new hook. Emir runs it when he has time. The name is a joke — `suf` is the acronym, the rest is Emir having fun. Run it directly — there is deliberately no shell variable: ```bash python3 ~/.claude/skills/sufsufik/scripts/suf.py [args] ``` Do **not** wrap it as `SUF="python3 …"` and then call `$SUF log`. zsh (the macOS default shell) does not word-split unquoted parameter expansions, so the whole string is taken as a single command *name* and fails with `no such file or directory: python3 …` — the tilde is expanded, so it reads like a missing file rather than a quoting bug. A variable or shell function is also useless to an agent: each tool call starts a fresh shell, so anything set in one call is gone in the next. The full invocation works in every shell, on every call. Entries are native Obsidian notes (one md file per defect, frontmatter = properties) in `wiki/meta/skill-feedback/`. Emir reads and hand-edits them there. Anyone else: set `SUF_HOME` to any directory; same md files, no Obsidian needed. ## The bar — what counts **Log it** when the SKILL is at fault: - its instructions are wrong, stale, or name a file/flag/tool that no longer exists - a bundled script crashes or produces a wrong result - a step is missing, or you had to work around the skill to get the job done - **the skill's own gate/scan computed the wrong scope** (`SCOPE-BUG` — the class that let github-push scan 0 blobs and call it clean) **Do not log**: your own mistake · a feature you wish it had (a wish, not a defect) · the environment, credentials, network, or a third-party tool failing · anything you cannot reproduce. A queue of vague, unreproducible complaints is worse than no queue — it buries the real defects. ## Logging ```bash python3 ~/.claude/skills/sufsufik/scripts/suf.py log --skill --kind SCOPE-BUG \ --what "one concrete sentence: what the skill does wrong" \ --repro "the exact command or steps that trigger it" \ --expected "..." --observed "..." \ --workaround "what you did instead to get unblocked" \ --prevention "what would have made this impossible" ``` `--repro` is **required and refused if thin**. This is the whole quality bar: an entry nobody can reproduce cannot be fixed and will clog the queue forever. If you genuinely cannot reproduce it, do not log it. **Evidence/what/repro describe commands, so they contain backticks and `$(...)` — pass them from a file, not inline.** Any text arg accepts `@FILE` (read the field from that file) or `-` (read from stdin); the file's contents are NOT shell-interpreted, so backticks never command-substitute. Write the text to a file, then: `python3 ~/.claude/skills/sufsufik/scripts/suf.py close --status fixed --evidence @/tmp/ev.txt`. Inline `--evidence "... \`cmd\` ..."` will run `cmd` in your shell before suf sees it. **`--prevention` is the most valuable field you can write.** You just hit the defect and found the way around it, so you know better than anyone what would have stopped it — and `/suf-fix` starts from your hypothesis. Aim at the strongest rung you can: - make it structurally impossible (*"resolve the branch before pushing, instead of assuming HEAD"* — that one sentence is the whole github-push fix) - or a guard that refuses the bad state loudly (*"refuse on a detached HEAD"*) - or a hook, when the skill can be bypassed entirely - **not** "document the workaround" — that is what we are eliminating. `kind`: `STALE-REFERENCE` · `WRONG-INSTRUCTION` · `MISSING-STEP` · `SCRIPT-ERROR` · `SCOPE-BUG` · `OTHER`. A byte-identical `--what` dedupes and bumps `seen`. A *near*-duplicate (same defect, different wording — measured against existing entries for the skill) is **refused** with the candidate's id, so one defect does not become two entries; pass `--force-new` if it really is a distinct defect that just shares vocabulary. `--skill` resolves against `~/.claude/skills`, installed plugins, **and any `.claude/skills/` in the working directory or its ancestors** — so a repo-local skill the harness offered you is a known skill and needs no flag. `--force` exists only for a skill none of those reach (e.g. one bundled with the app rather than installed on disk); using it means the entry cannot be fingerprinted, so `recheck` can never sweep it — prefer a resolvable name. ## Draining (`/suf-fix`, or by hand) ```bash python3 ~/.claude/skills/sufsufik/scripts/suf.py triage # ranked JSON: reproducible first python3 ~/.claude/skills/sufsufik/scripts/suf.py show python3 ~/.claude/skills/sufsufik/scripts/suf.py close \ --status fixed|wontfix|unreproducible --evidence "what you RAN" ``` The fixer's job is **prevention, not ticket closing** — the workaround must end up unnecessary. Full protocol in `/suf-fix`; the shape: 1. **Reproduce first.** Doesn't reproduce → `close --status unreproducible`. Never fix what you can't trigger; you'd be guessing. 2. **Fix at the strongest rung you can reach**: structurally impossible > a guard that refuses > a hook (ask Emir first — it fires in every future session) > fixing the prose > documenting the workaround (which is not a fix at all). Prose drifts; mechanisms don't. 3. **Re-run the repro to prove it.** That output is the `--evidence`. And if the fix touched a gate or a scan, test the **scope**, not just the check. 4. `close --status fixed` — marks the workaround `invalid`, killing the note that would otherwise outlive the bug. 5. `python3 ~/.claude/skills/sufsufik/scripts/suf.py recheck` afterwards, so sibling entries against the patched skill flip to `needs-recheck`. `close` refuses thin evidence. Closing on an opinion is how a queue starts lying. ## `recheck` — why this tool exists Each entry records a hash of the skill's whole directory at observation time. When the skill changes, `recheck` flips the entry to `needs-recheck` and marks its workaround **`unknown`**. Not `invalid` — and the difference is the point. A file changing does not prove a workaround wrong; asserting that would be claiming something you did not observe. Only re-running the repro settles it. The real incident: "always pass `--ref main`" was true in the morning and false by the afternoon, and nothing noticed. ## Notes - `list`/`triage` exit 2 when open entries exist, 0 when clean. - A defect that reappears after being closed reopens automatically. - Hand-editing an entry in Obsidian is expected and safe: unknown frontmatter keys and your own body sections are preserved, and a stale write is refused rather than overwriting your edit.