Skip to main content
affpapa.org
RU EN
skill CX Codex

note-it — Claude Code skill: what it does, how to install

Captures design decisions, spec deviations, and tradeoffs after code implementation, saving them into a structured HTML report in docs/.

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓ 
npx skills add smallnest/goal-workflow --skill note-it -a claude-code
Open on GitHub

What note-it does

The skill reviews completed code against the issue specification and writes an implementation report to docs/issue#XXXX.html. It pulls the issue number directly from the prompt, a Git branch name like feat/issue-42-*, or the previous /goal step. If the docs/ folder does not exist yet, the skill creates it automatically.

The output HTML file divides notes into four specific categories: design choices made for ambiguous requirements, deliberate deviations from the spec, evaluated tradeoffs, and open questions. When a report for that issue already exists, the skill asks whether to update or overwrite, defaulting to appending new items.

Missing PRD files at tasks/prd-*.md will not crash execution. In that scenario, the skill marks the absence inside the open questions section so you can verify requirements manually.

What it helps with

  • Record deviations from issue specs right after implementation
  • Document architectural choices and rejected alternatives in HTML
  • Collect open questions for manual review before /ship-it
  • Track design rationale when requirements are ambiguous or silent

Example prompts for the agent

  • /note-it #42
  • /note-it
  • Record implementation notes for this issue before shipping

How to install note-it

1Skills CLI (Vercel)

npx skills add smallnest/goal-workflow --skill note-it -a claude-code

2Manually: put the files in place

~/.claude/skills/note-it/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/note-it/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about note-it

How do I install note-it in Claude Code?

Run npx skills add smallnest/goal-workflow --skill note-it -a claude-code in your terminal.

What does note-it do?

It compares your implementation against the issue specification and generates an HTML report at docs/issue#XXXX.html covering design decisions, deviations, tradeoffs, and open questions.

What happens if a notes file for the issue already exists?

The skill asks whether to update or overwrite the file. By default, it updates the existing HTML file by appending new entries.

Source text

SKILL.md · MIT 
---
name: note-it
description: "Capture implementation notes after code implementation and review/fix. Records design decisions, deviations, tradeoffs, and open questions to docs/issue#XXXX.html. Triggers on: /note-it, 记录笔记, implementation notes."
user-invocable: true
---

# Implementation Notes

After completing implementation and review/fix for an Issue, capture a running implementation notes file that documents how the implementation diverges from or interprets the spec.

## Triggers

Use when:
- After `/goal` implementation and `/review-it` are both complete
- User says "记录笔记", "implementation notes", "note-it", "/note-it"
- Before `/ship-it` (as a final checkpoint)
- Any time the user wants to capture design rationale

## The Job

1. Determine the Issue number from context (branch name, `/goal` target, or user input)
2. Review the implementation against the Issue spec / PRD
3. Generate an HTML notes file at `docs/issue#XXXX.html`
4. Present a summary to the user

## Notes Structure

The HTML file must cover these four categories. If a category has nothing to report, write "None" with a brief explanation.

### 1. Design Decisions
Choices made where the spec was ambiguous or silent:
- What was the ambiguity?
- What choice did you make?
- What was the rationale?

### 2. Deviations
Places where you intentionally departed from the spec:
- What did the spec say?
- What did you implement instead?
- Why was the deviation necessary or better?

### 3. Tradeoffs
Alternatives you considered and why you picked what you did:
- What were the viable alternatives?
- What were the pros/cons of each?
- Why did the chosen approach win?

### 4. Open Questions
Anything you'd want confirmed or revised:
- What assumption are you unsure about?
- What should the user verify?
- What might need follow-up?

## Output

- **Format:** HTML
- **Location:** `docs/`
- **Filename:** `issue#XXXX.html` (where XXXX is the zero-padded Issue number, e.g., `issue#0042.html`)

## HTML Template

Use this exact HTML structure:

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Implementation Notes — Issue #XXXX</title>
  <style>
    * { margin: 0; padding: 0; box-sizing: border-box; }
    body {
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
      background: #FAF9F6;
      color: #1a1a1a;
      padding: 2.5rem 2rem;
      line-height: 1.7;
    }
    .container { max-width: 800px; margin: 0 auto; }
    h1 { font-size: 1.375rem; font-weight: 700; margin-bottom: 0.25rem; }
    .meta { color: #8B8680; font-size: 0.8125rem; margin-bottom: 2rem; }
    h2 {
      font-size: 1rem;
      font-weight: 600;
      margin-top: 2rem;
      margin-bottom: 0.75rem;
      padding-bottom: 0.375rem;
      border-bottom: 1px solid #E8E4DE;
      display: flex; align-items: center; gap: 0.5rem;
    }
    .dot {
      width: 8px; height: 8px; border-radius: 50%; display: inline-block;
    }
    .dot.design { background: #5B8A72; }
    .dot.deviation { background: #D97757; }
    .dot.tradeoff { background: #4A6FA5; }
    .dot.question { background: #D4A843; }
    .item {
      background: #FFFFFF;
      border: 1px solid #E8E4DE;
      border-radius: 8px;
      padding: 1rem 1.25rem;
      margin-bottom: 0.75rem;
      box-shadow: 0 1px 3px rgba(0,0,0,0.03);
    }
    .item h3 { font-size: 0.875rem; font-weight: 600; margin-bottom: 0.375rem; }
    .item p { font-size: 0.8125rem; color: #4A4540; margin-bottom: 0.375rem; }
    .label {
      display: inline-block;
      font-size: 0.6875rem;
      font-weight: 500;
      padding: 0.125rem 0.5rem;
      border-radius: 4px;
      margin-right: 0.375rem;
    }
    .label-design { background: #F5F8F6; color: #5B8A72; border: 1px solid #5B8A72; }
    .label-deviation { background: #FFF5F0; color: #D97757; border: 1px solid #D97757; }
    .label-tradeoff { background: #F0F4F8; color: #4A6FA5; border: 1px solid #4A6FA5; }
    .label-question { background: #FDF8F0; color: #D4A843; border: 1px solid #D4A843; }
    .none { color: #B0AAA4; font-style: italic; font-size: 0.8125rem; }
    .footer {
      text-align: center; margin-top: 2.5rem; color: #B0AAA4;
      font-size: 0.6875rem;
    }
  </style>
</head>
<body>
  <div class="container">
    <h1>Implementation Notes</h1>
    <p class="meta">Issue <a href="{{ISSUE_URL}}">#{{ISSUE_NUMBER}}</a> &mdash; {{ISSUE_TITLE}} &mdash; {{DATE}}</p>

    <h2><span class="dot design"></span> Design Decisions</h2>
    <!-- One .item per decision, or .none if none -->

    <h2><span class="dot deviation"></span> Deviations</h2>
    <!-- One .item per deviation, or .none if none -->

    <h2><span class="dot tradeoff"></span> Tradeoffs</h2>
    <!-- One .item per tradeoff, or .none if none -->

    <h2><span class="dot question"></span> Open Questions</h2>
    <!-- One .item per question, or .none if none -->

    <p class="footer">Generated by goal-workflow /note-it</p>
  </div>
</body>
</html>
```

## Example Item

```html
<div class="item">
  <h3><span class="label label-design">Decision</span> Used interface-based polymorphism instead of switch</h3>
  <p><strong>Ambiguity:</strong> The spec said "handle different types" without specifying how.</p>
  <p><strong>Choice:</strong> Defined a <code>Handler</code> interface with per-type implementations.</p>
  <p><strong>Rationale:</strong> Adding new types requires no changes to existing code (Open/Closed Principle). A switch would grow unboundedly.</p>
</div>
```

## How to Determine the Issue Number

1. If the user provides it directly (e.g., `/note-it #42`), use it
2. If on a branch named `feat/issue-42-*` or `fix/issue-42-*`, extract `42`
3. If the last `/goal` target was `#42`, use `42`
4. Otherwise, ask the user: "Which Issue number should I use for the notes file?"

## Edge Cases

| Scenario | Handling |
|----------|----------|
| No Issue number found | Ask the user to specify |
| `docs/` directory does not exist | Auto-create it |
| Notes file already exists for this Issue | Ask: "Update existing notes or overwrite?" — default to update (append new items) |
| No deviations or open questions | Write "None — implementation followed the spec as written." |
| Spec/PRD file not found | Note in Open Questions: "No PRD found at tasks/prd-*.md — verify against original requirements." |

## Checklist

Before saving:
- [ ] Issue number identified
- [ ] All four categories reviewed (even if some are "None")
- [ ] Design decisions explain rationale, not just what was done
- [ ] Deviations clearly contrast spec vs implementation
- [ ] Tradeoffs mention specific alternatives considered
- [ ] Open questions are actionable (user can answer yes/no or give direction)
- [ ] HTML is well-formed and renders correctly

© smallnest · MIT · smallnest/goal-workflow

Similar skills

Everything for Writing and docs →
process-mapping aj-geddes A skill that walks the agent through documenting a current workflow, spotting bottlenecks and designing an improved version. CX Codex +1 552installs html-plan plannotator Turns project notes and requirements into a self-contained HTML plan. Useful for organizing phases, dependencies, and owners without turning the doc into a dashboard. CX Codex +1 3,800installs flowchart-creator mhattingpete Turns a process into a single HTML file with an SVG flowchart. Handy when a workflow needs a picture instead of a paragraph. CX Codex +1 735installs system-atlas inkboard Builds an interactive isometric architecture map and a matching SYSTEM.md twin from one data file, keeping design reviews and question tracking in sync. CX Codex +1 505installs structured-artifact haowjy A skill for building structured HTML artifacts: the agent decides how to present the content first, then picks the tools. CX Codex +1 387installs scope jsmastery-pro The skill adds a /scope command that turns a product idea into a phased feature plan in docs/scope/, then reconciles that plan with what actually shipped. CX Codex +1 4,300installs

From the same set7

smell Scans a codebase and writes a markdown report on architectural violations, anti-patterns and algorithmic complexity hotspots. CX Codex +1 768installs prd Turns a feature description into a Product Requirements Document: asks clarifying questions, drafts user stories with acceptance criteria, saves the file under tasks/. CX Codex +1 531installs modern-go Rewrites Go sources to idioms and APIs that match the version declared in go.mod. Handy after a toolchain bump when the code still uses old patterns. CX Codex +1 518installs refactor Restructures code safely based on Martin Fowler's catalog without altering external behavior. Fixes code smells through small, verifiable steps. CX Codex +1 518installs code-to-spec Reads an existing project and rebuilds a SPEC document from its code, config and tests. Useful when there is no spec and you still need to understand the thing. CX Codex +1 470installs to-issues Decomposes PRDs and technical specs into thin, demoable vertical issues with explicit blocking edges for GitHub or local tracking. CX Codex +1 451installs

Project sponsors

Companies that keep this analytics open
Gold sponsor
Nutra.Club

Impressions, clicks and code copies — open statistics. We keep the numbers public for the same reason NeBlask itself is public. Become a sponsor