Skill Feedback — capture the fuel for skill improvement

This skill closes the loop opened by docs/SKILL_QUALITY_GATE.md. The Quality Gate tells you whether a skill is good; this skill tells you how to make it better next time by recording what happened in real usage and turning it into a feed for skill-forge.

Without a feedback capture, improvement is guesswork. With it, every near-miss trigger and every manual correction becomes a concrete edit to a skill's description / when_to_use / body.

When to use

• A skill should have triggered but did not (near-miss): the user's request was in-scope but the auto-load missed it.
• A skill triggered wrongly: the wrong skill loaded for the request.
• A skill produced a wrong / broken / low-quality output (output issue).
• The user manually corrected the skill's output (edited the result, or told you "no, do it differently").
• You want to review what has piled up before running skill-forge.

DO NOT USE FOR

• General chat feedback, venting, or notes unrelated to a specific skill — those belong in memory or the session log, not the skill feedback store.
• Capturing secrets or personal data — never log credentials or PII in entries.

Auto-capture (make it automatic)

For the loop to run without manual nudging, capture feedback proactively. Append the rule from AGENTS_FRAGMENT.md (repo root) to your opencode AGENTS.md. Then any near-miss / manual correction is logged automatically — no explicit "remember this" needed. Each consumer grows their own skills locally; see docs/SKILL_QUALITY_GATE.md Layer C.

How feedback is stored

Each entry is one JSON object on its own line in:

feedback/<skill-name>/YYYY-MM-DD.jsonl

Entry schema:

{
  "ts": "2026-08-26T14:03:00",
  "skill": "api-contract-testing",
  "type": "near_miss_trigger",
  "request": "проверь, что эндпоинты совпадают со спецификацией",
  "detail": "skill did not auto-load; user had to invoke it manually",
  "suggested_fix": "add casual-phrasing trigger 'проверь эндпоинты' to when_to_use",
  "source": "user"
}

type is one of: near_miss_trigger, wrong_trigger, output_issue, manual_correction, description_gap.

The script

scripts/feedback.py — pure Python 3 stdlib, no third-party packages. Run it from this skill folder (e.g. python3 scripts/feedback.py …); the script resolves the repo root on its own, so the feedback/ store always lands in the right place regardless of current directory.

Verification — capture evidence, not assertion

The loop is not "done" until the script proves the entry landed. After every add, capture two pieces of evidence:

1. The printed line — add writes ok: appended to <path> on success. That line names the exact file the entry went into, so you can confirm the store grew.
2. The exit status — 0 means the entry was written; 2 means the --type was rejected and nothing was saved. Treat any non-zero exit as a failure and fix the command before moving on.

Example evidence capture:

python3 scripts/feedback.py add \
  --skill api-contract-testing --type near_miss_trigger \
  --request "проверь, что эндпоинты совпадают со спецификацией" \
  --detail "skill did not auto-load; user had to invoke it manually" \
  --fix "add casual-phrasing trigger 'проверь эндпоинты' to when_to_use"
# expect: ok: appended to feedback/api-contract-testing/2026-08-26.jsonl
# expect: exit 0

report and export are read-only and always exit 0; run them before improving a skill to see the accumulated issues, and paste their output into the skill-forge session as the basis for trigger/description edits.

How it feeds the loop

1. During/after a session, capture near-misses and corrections via add (or ask the user "should I log this as skill feedback?").
2. Before improving a skill, run report to see its accumulated issues.
3. Feed the near-miss request strings into skill-forge's Optimize description (they become the missing trigger queries); feed manual_correction suggested_fix into the Improve step.
4. Re-run the Layer A/B audit (the docs/skill-quality-audit.md generator) to confirm the edit moved the needle.
5. Commit the skill change — and optionally the feedback store — so the loop is reproducible.

Privacy & hygiene

• The store lives in the repo under feedback/. Commit it only if you want the history shared; otherwise gitignore it.
• Never put secrets, tokens, or personal data in request / detail.
• Keep entries factual and short; one issue per entry.

Boundaries

• Do not use as a substitute for actually fixing a skill; record evidence, then use skill-forge.