Agent Note

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:

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@v1.
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:

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.