# Record Usage Issues > >- - **Type:** Skill - **Install:** `agentstack add skill-openghz-record-usage-issues-record-usage-issues` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [OpenGHz](https://agentstack.voostack.com/s/openghz) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [OpenGHz](https://github.com/OpenGHz) - **Source:** https://github.com/OpenGHz/record-usage-issues ## Install ```sh agentstack add skill-openghz-record-usage-issues-record-usage-issues ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Record Usage Issues ## What this is for You are operating inside a project that someone else built and handed off. While you carry out the user's actual tasks, you will sometimes hit friction: a command in the README doesn't work, a script crashes, the docs describe behavior that doesn't match reality, a dependency is missing, a default is wrong, or you find a genuine bug. The author can't see any of this. The purpose of this skill is to leave a paper trail: a single append-only Markdown file that the user can mail back so the author can fix and improve the project. Think of yourself as a field tester filling out a defect log while you work — not stopping the job, just noting what tripped you up and how you got around it. **This skill is opt-in.** Only record issues when the user has explicitly asked you to — by invoking the skill, or by telling you to log/collect the problems you run into with the project. Do not start a log on your own initiative just because you hit a bug; if the user never asked, simply deal with the problem as part of the task. Once the user *has* turned recording on, treat it as standing for the rest of the session: keep logging the qualifying problems you encounter without asking again each time. The value of the log is **signal density**. A focused list of real, reproducible problems is worth far more to the author than a noisy diary of every minor thing. Optimize for "would the author want to fix this?" ## When to log (and when not to) **Log it** when the problem is the *project's* fault and the author would plausibly want to fix it: - A documented command, flag, or example fails or does something different than documented. - A script/tool throws an error, crashes, hangs, or returns a wrong result. - Setup/install steps are missing, out of order, or don't work as written. - Behavior contradicts the README, comments, schema, or other docs. - A confusing API, unclear error message, missing file, or wrong default that cost you time. - Any outright bug, even one you found a workaround for. **Don't log** noise that isn't actionable for the author: - Your own slips that you immediately corrected (a typo in a path, forgetting to `cd`). - Pure environment issues unrelated to the project (your network was down) — unless the project should have handled it more gracefully, in which case log *that* angle. - The same issue twice — if you already logged it this session, don't duplicate it. If it recurred in a meaningfully different place, add a short note to the existing entry instead. When unsure, lean toward logging but keep it short. A borderline entry the author skims past is cheap; a real bug that went unrecorded is expensive. ## Where to write Append to a file named **`AGENT_ISSUES.md`** at the **root of the project you're currently working in** — the directory holding the README / package manifest / `.git`. If you genuinely can't identify a project root, use the current working directory. Use the **same file for the entire session** so all entries collect in one place. If the file doesn't exist yet, create it with this header first, then add your entry: ```markdown # Agent Issue Log Problems and bugs recorded automatically by agents while using this project. Each entry below is one issue: what was being attempted, what went wrong, and the workaround used. Send this file back to the project author so they can fix and improve things. --- ``` ## Entry format Each issue is **one section**, appended to the end of the file. Use this exact template so the entries stay uniform and easy for the author to triage in bulk: ```markdown ## [] - **Severity:** blocker | major | minor | nit - **Doing:** what you were trying to do, including the exact command/action if any - **Symptom:** what actually happened — paste the key error text or wrong output - **Workaround:** what you did to get past it, or "none — blocked" if you couldn't - **Location:** the file / path / module / command involved (e.g. `scripts/setup.sh:42`) - **Suggested fix:** a brief idea if you have one (optional — omit if you don't) ``` Get a real timestamp from the shell rather than guessing — e.g. run `date '+%Y-%m-%d %H:%M'` and use the result. Keep each field to a sentence or two; this is a triage note, not a report. Paste only the *relevant* lines of an error, not a whole stack trace, unless the stack trace is the point. **Severity guide** — pick from the author's point of view: - `blocker` — stops the project from being usable for its purpose; no reasonable workaround. - `major` — important feature broken or docs badly wrong, but you found a workaround. - `minor` — annoyance, small inconsistency, or unclear message that cost some time. - `nit` — cosmetic or trivially-fixable (typo in output, slightly stale doc line). ## How to log without derailing the task Recording an issue should be a quick side-step, not a detour. The user asked for something else; keep doing that. When you hit a qualifying problem: 1. Append the entry (create the file with its header first if needed). 2. Mention it to the user in one short line — e.g. *"(Logged the failing `make build` step to AGENT_ISSUES.md.)"* — so they know it's being captured. 3. Continue with the original task using whatever workaround you found. Don't ask the user for permission to log each issue, and don't pause the main task to investigate a bug more deeply than the task requires — note what you observed and move on. The author, not you, will do the deep fix later. ## Example After a documented setup command failed, the appended entry looks like: ```markdown ## [2026-06-19 14:32] `pip install -r requirements.txt` fails on pinned numpy - **Severity:** major - **Doing:** Following README "Quickstart" step 2 to install dependencies. - **Symptom:** Build error — `numpy==1.21.0` has no wheel for Python 3.12; pip tries to compile from source and fails on `longintrepr.h`. - **Workaround:** Installed `numpy>=1.26` instead; the rest of the project ran fine against it. - **Location:** `requirements.txt:3`, README "Quickstart" step 2 - **Suggested fix:** Loosen the numpy pin or document a supported Python version. ``` One section, self-contained, immediately actionable for the author — that's the bar for every entry. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [OpenGHz](https://github.com/OpenGHz) - **Source:** [OpenGHz/record-usage-issues](https://github.com/OpenGHz/record-usage-issues) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-openghz-record-usage-issues-record-usage-issues - Seller: https://agentstack.voostack.com/s/openghz - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.