agent-friction-ledger
Capture recurring agent-development friction as a local, privacy-safe Markdown report. Use only when the user explicitly requests a friction review of blockers, misleading errors, missing documentation, incompatible tools, or manual workarounds that should improve a doc, tool, sk
Install
npx skills add https://github.com/markoblogo/abvx-agent-skills/tree/main/skills/agent-friction-ledger
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install markoblogo-abvx-agent-skills@llmmart
git clone https://github.com/markoblogo/abvx-agent-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole markoblogo/abvx-agent-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Agent Friction Ledger
Turn repeatable agent friction into a small, actionable local artifact. This skill is opt-in and never sends session data outside the workspace.
Trigger
Use only when:
- the user explicitly asks for a friction report or review.
Do not run merely because a task had normal shell output, a single failed command, or a clean completion.
Capture Rules
Record only friction that is actionable and evidenced by the current task:
- repeated blocker or retry loop;
- misleading, incomplete, or contradictory error;
- missing, stale, or hard-to-find documentation;
- tool, provider, environment, or version incompatibility;
- manual workaround that should become a durable improvement.
Do not record every tool call, full conversation, raw logs, private URLs, credentials, personal data, client data, or unrelated working-tree changes.
Workflow
- Name the task boundary and identify only the material friction events.
- For each event, record:
symptom -> attempted -> root cause -> resolution -> durable fix. - Mark confidence: confirmed, likely, or unresolved. Do not turn a guess into a root cause.
- Redact or omit sensitive content before writing.
- Write a local report to an ignored or private location only. Default to
.git/agent-friction/YYYY-MM-DD-<task>.mdunless the repo defines another approved ignored path. - Group action items under
docs,tooling,skill/process, andresearch. - Propose the smallest durable change, but do not apply it without normal task authorization.
Report Shape
# Agent Friction Report: <task>
## Scope
## Material Friction
### <short label>
- Symptom:
- Attempted:
- Root cause: <confirmed|likely|unresolved>
- Resolution:
- Durable fix:
## Action Items
### Docs
### Tooling
### Skill / Process
### Research
## Decision
- Keep local / propose follow-up / no durable change
Guardrails
- Local Markdown only. Never POST to a viewer, telemetry endpoint, or external API.
- Never write to a tracked repo path by default. If no ignored/private location exists, stop and ask before writing.
- A friction report is not permission to create a ticket, alter a skill, edit docs, or change a process.
- Prefer one concise report over a growing per-turn buffer.
- If the task contains regulated, personal, client, deal, financial, or credential data, record the abstract failure mode only.
Pair With
repo-debugging-ledgerfor hypothesis-driven technical diagnosis;durable-context-maintenancewhen an accepted fix belongs in repo context;token-usage-auditwhen the friction is context or tool-output waste;skillopt-evolve-skillsandbounded-evaluationwhen an accepted skill change needs validation.
Provenance
Adapted from aurorascharff/agent-friction-skill, narrowed to explicit, local-only, privacy-safe friction capture with proposal-gated follow-up.
Files (abvx-agent-skills)
-
agents
-
openai.yaml 357 B
Loading…
-
-
SKILL.md 3.3 KB
--- name: agent-friction-ledger description: Capture recurring agent-development friction as a local, privacy-safe Markdown report. Use only when the user explicitly requests a friction review of blockers, misleading errors, missing documentation, incompatible tools, or manual workarounds that should improve a doc, tool, skill, process, or evaluation. license: MIT metadata: abvx_status: experimental abvx_origin: adapted --- # Agent Friction Ledger Turn repeatable agent friction into a small, actionable local artifact. This skill is opt-in and never sends session data outside the workspace. ## Trigger Use only when: - the user explicitly asks for a friction report or review. Do not run merely because a task had normal shell output, a single failed command, or a clean completion. ## Capture Rules Record only friction that is actionable and evidenced by the current task: - repeated blocker or retry loop; - misleading, incomplete, or contradictory error; - missing, stale, or hard-to-find documentation; - tool, provider, environment, or version incompatibility; - manual workaround that should become a durable improvement. Do not record every tool call, full conversation, raw logs, private URLs, credentials, personal data, client data, or unrelated working-tree changes. ## Workflow 1. Name the task boundary and identify only the material friction events. 2. For each event, record: `symptom -> attempted -> root cause -> resolution -> durable fix`. 3. Mark confidence: confirmed, likely, or unresolved. Do not turn a guess into a root cause. 4. Redact or omit sensitive content before writing. 5. Write a local report to an ignored or private location only. Default to `.git/agent-friction/YYYY-MM-DD-<task>.md` unless the repo defines another approved ignored path. 6. Group action items under `docs`, `tooling`, `skill/process`, and `research`. 7. Propose the smallest durable change, but do not apply it without normal task authorization. ## Report Shape ```markdown # Agent Friction Report: <task> ## Scope ## Material Friction ### <short label> - Symptom: - Attempted: - Root cause: <confirmed|likely|unresolved> - Resolution: - Durable fix: ## Action Items ### Docs ### Tooling ### Skill / Process ### Research ## Decision - Keep local / propose follow-up / no durable change ``` ## Guardrails - Local Markdown only. Never POST to a viewer, telemetry endpoint, or external API. - Never write to a tracked repo path by default. If no ignored/private location exists, stop and ask before writing. - A friction report is not permission to create a ticket, alter a skill, edit docs, or change a process. - Prefer one concise report over a growing per-turn buffer. - If the task contains regulated, personal, client, deal, financial, or credential data, record the abstract failure mode only. ## Pair With - `repo-debugging-ledger` for hypothesis-driven technical diagnosis; - `durable-context-maintenance` when an accepted fix belongs in repo context; - `token-usage-audit` when the friction is context or tool-output waste; - `skillopt-evolve-skills` and `bounded-evaluation` when an accepted skill change needs validation. ## Provenance Adapted from `aurorascharff/agent-friction-skill`, narrowed to explicit, local-only, privacy-safe friction capture with proposal-gated follow-up. -
SKILL_CARD.md 1.4 KB
Loading…
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.