---
name: agent-note
description: >
  Use this skill when the user wants to set up Agent Note, inspect Agent Note
  history, understand why a line changed, troubleshoot PR Report or Dashboard
  output, or exclude generated files from AI Ratio. Do not use it for generic
  git history, generic commit writing, or non-Agent-Note review tasks.
license: MIT
---

# Agent Note

Agent Note records the AI conversation, changed files, and AI Ratio for each
commit by storing data in git notes.

## When To Use This Skill

Use this skill when the user asks to:

- Set up Agent Note in a repository.
- Remove Agent Note hooks and config from a repository.
- Check whether Agent Note is recording correctly.
- Inspect recent Agent Note history.
- Show the Agent Note data behind a commit.
- Explain why a file line changed using Agent Note.
- Enable or troubleshoot the PR Report.
- Enable or troubleshoot the Dashboard.
- Exclude generated files or bundles from AI Ratio.

## Do Not Use This Skill For

- Generic git history, git blame, or commit-writing tasks without Agent Note.
- Running internal Agent Note renderers directly for normal users.
- Editing git notes as if they were a task database.
- Proving implementation correctness. Agent Note records intent and evidence;
  review still needs the diff and tests.

## Public Commands

Only present these commands as normal user actions:

```text
agent-note init
agent-note deinit
agent-note status
agent-note log
agent-note show
agent-note why
```

Do not make `agent-note pr`, `agent-note hook`, `agent-note record`,
`agent-note commit`, or `agent-note push-notes` the user's primary action.
Those commands are internal or automation-facing.

## Setup Workflow

1. Inspect the repository before editing files.
2. Identify the target coding agent: Claude Code, Codex CLI, Cursor, or Gemini
   CLI.
3. Run `npx agent-note init --agent <name>` for the selected agent.
4. If the user wants the shared Dashboard, use
   `npx agent-note init --agent <name> --dashboard`.
5. Review the generated agent config, GitHub workflow, and git hook changes
   before asking the user to commit.

## Deinit Workflow

Use `agent-note deinit` when the user wants to remove Agent Note from a
repository.

1. Identify the target coding agent or agents.
2. Run `npx agent-note deinit --agent <name>` for those agents.
3. Use `--remove-workflow` only when the user also wants generated PR Report
   and Dashboard workflows removed.
4. Use `--keep-notes` when the user wants to keep notes auto-fetch config.
5. Review changed hook, workflow, and agent config files before committing.

## PR Report Workflow

PR Report is normally produced by the GitHub Action generated by
`agent-note init`. Do not ask the user to run the local PR renderer directly.

When troubleshooting:

1. Check that the workflow uses `wasabeef/AgentNote@v0`.
2. Check workflow permissions for Pull Request writes.
3. Check that `refs/notes/agentnote` was pushed and fetched.
4. Check whether the report says "No tracked commits" versus a true `0%` AI
   Ratio.

## Dashboard Workflow

Dashboard is enabled with `dashboard: true` in the Agent Note action, usually
generated by `agent-note init --dashboard`.

When troubleshooting:

1. Check the Dashboard workflow run.
2. Check GitHub Pages deployment.
3. Check `dashboard/notes/*.json` data.
4. Check the PR number in the Dashboard URL.

## Why Workflow

Use `agent-note why <target>` when the user asks why a line changed.

Supported target styles include:

```text
src/app.ts:42
src/app.ts:42-55
src/app.ts#L42
src/app.ts#L42-L55
@src/app.ts#L42
https://github.com/owner/repo/blob/main/src/app.ts#L42
file:///workspace/repo/src/app.ts#L42
vscode://file/workspace/repo/src/app.ts:42:7
```

Summarize the evidence level clearly. Agent Note can show the commit and
related prompts for a line, but exact line-to-prompt attribution may not exist.

## AI Ratio Workflow

If generated files make AI Ratio misleading, add precise patterns to
`.agentnoteignore`.

Explain that ignored files still appear in Agent Note history, PR Report, and
Dashboard. They are only removed from AI Ratio math.

## Safety Rules

- Prefer read-only checks before editing workflow or hook files.
- Preserve existing hooks and workflows; update carefully instead of replacing.
- Never infer AI-authored files from shell-only evidence.
- Tell the user before pushing notes to a public repository if prompts or
  responses may contain secrets.
- Ask before committing changes when repository instructions require it.