file-friction
Files the friction worked around during a task as deduplicated GitHub issues so a later agent fixes the cause. Use when finishing /commit, before ending any task that hit a flaky or slow gate, a confu
SKILL.md.claude/skills/file-friction/SKILL.md
GitHubFile Friction
Agents work around friction instead of fixing it, and the workarounds compound
across every Claude Code and Codex session. This skill turns each workaround into
an issue that /triage can promote to ready-for-agent. It files issues only —
never fix the friction inside the current task unless it is in scope.
1. List candidates
Review this task's transcript, commands and SESSION_LOG.md entry. A candidate is
something you worked around, not something you fixed:
- A gate that failed for reasons unrelated to the change (flaky test, timeout, runner disk, drift).
- A step that was slow enough to change how you worked.
- A doc,
AGENTS.mdrule or skill that was wrong, stale, ambiguous or missing. - A tool, hook or script that failed or needed a retry, restart or manual step.
- A helper you rewrote because you could not find the shared one (see
docs/agents/primitives.md).
Drop anything already fixed in this task, caused by your own mistake, or purely environmental to one machine with no repo-side fix. If nothing qualifies, say "No friction filed" and stop.
2. Deduplicate
For each candidate, search open friction issues with two or three key terms:
gh issue list --label friction --state open --search "<terms>" --json number,title,url
If one matches, add a comment with the new evidence and the date instead of filing a duplicate. Start comments with the disclaimer below.
3. File
File at most 3 new issues per task; keep the most costly. Use this body:
gh issue create --label friction --label needs-triage --title "friction: <symptom in under 60 chars>" --body "$(cat <<'EOF'
> *This was generated by AI during friction capture.*
**Filed by:** <Claude Code | Codex> · <branch> · <YYYY-MM-DD>
**What happened**
<one or two sentences>
**Workaround used**
<what the agent did instead>
**Suggested fix**
<smallest change that removes the friction, with file paths>
**Evidence**
<exact command and trimmed output>
EOF
)"
The repository is public. Never include secrets, tokens, .env values, client
data, personal data, Sentry event payloads or anything from /private/. Paths,
commands and redacted error text are fine.
4. Record
Add friction: #<n>, #<m> (or friction: none) to this task's SESSION_LOG.md
entry and to the final summary for the user.