MCPInstall

note-it

by smallnestDocs & Writing

Capture implementation notes after code implementation and review/fix. Records design decisions, deviations, tradeoffs, and open questions to docs/issueXXXX.html. Triggers on: /note-it, 记录笔记, implementation notes.

Installs
469
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/smallnest/goal-workflow --skill note-it
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads note-it automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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:

<!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

<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

ScenarioHandling
No Issue number foundAsk the user to specify
docs/ directory does not existAuto-create it
Notes file already exists for this IssueAsk: "Update existing notes or overwrite?" — default to update (append new items)
No deviations or open questionsWrite "None — implementation followed the spec as written."
Spec/PRD file not foundNote 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

FAQ

What does the note-it skill do?

Capture implementation notes after code implementation and review/fix. Records design decisions, deviations, tradeoffs, and open questions to docs/issueXXXX.html. Triggers on: /note-it, 记录笔记, implementation notes.

How do I install note-it?

Run npx skills add https://github.com/smallnest/goal-workflow --skill note-it in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/note-it/ (personal) or .claude/skills/note-it/ (project).

Which AI agents can use note-it?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is note-it safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains note-it?

It is published by smallnest in smallnest/goal-workflow. It has 469 recorded installs.

More from smallnest/goal-workflow

View all →

smell

smallnest/goal-workflow

Detect software architecture bad smells, algorithmic complexity hotspots, and anti-patterns in a codebase. Produces a detailed markdown report identifying violations of architectural principles, design patterns, code quality, and performance complexity. Triggers on: smell, code smell, architecture smell, find anti-patterns, detect bad smells, complexity analysis, 代码坏味道, 架构坏味道, 反模式, 找出坏味道, 复杂度分析.

Code Quality & Workflow775 installs

prd

smallnest/goal-workflow

Generate a Product Requirements Document (PRD) for a new feature. Use when planning a feature, starting a new project, or when asked to create a PRD. After PRD is confirmed, use /prd-to-spec (optional) for technical design, then /to-issues to create implementable tickets. Triggers on: create a prd, write prd for, plan this feature, requirements for, spec out, 写PRD, 需求文档, 需求分析, 规格说明.

Code Quality & Workflow534 installs

humanize-it

smallnest/goal-workflow

对指定文档进行去 AI 味的改写。自动选择最合适的人性化策略（humanizer-zh / humanize-chinese / technical-writing）， 迭代改写直到效果达标或迭代 42 次为止。适用于中文文本的去 AI 化处理，包括通用文章、技术文档、学术论文等。 Use when user says: "humanize this", "去AI味", "降AIGC", "人性化改写", "改成人话", "去除AI痕迹", "humanize document", "make text human-like", "去机器味", "降低AI率", "过AIGC检测"

Docs & Writing534 installs

insight-diagram

smallnest/goal-workflow

为任意项目生成 UML 图、架构图和流程图。分析代码库后让用户选择要生成的图表类型，使用 architecture-diagram skill 渲染为 HTML+SVG，保存到 docs/ 目录。适用于任何软件项目的文档可视化。

Docs & Writing524 installs

refactor

smallnest/goal-workflow

Expert code refactoring based on Martin Fowler's catalog — improve maintainability without changing behavior. Covers code smells, composing methods, moving features, organizing data, simplifying conditionals, method calls, and generalization. Triggers on: refactor, 重构, clean up, improve code, code smell, extract method, rename, simplify.

Code Quality & Workflow524 installs

modern-go

smallnest/goal-workflow

Modernize Go code by applying version-appropriate idioms and APIs (gofix-style transformations). Scans go.mod for the Go version, then transforms Go source files to use modern patterns—from Go 1.0 through 1.26+. Use when the user says "现代化","现代Go语言", "地道的", "idiomatic", "modernize", "modern-go", "update Go code", "gofix", or wants to upgrade Go idioms.

Productivity & Automation523 installs

Popular docs & writing skills

View category →

grill-with-docs

mattpocock/skills

A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.

Docs & Writing1.2M installs

lark-markdown

open.feishu.cn

飞书 Markdown：查看、创建、上传、编辑和比较飞书中的原生 Markdown 文件。当用户要操作飞书 Markdown 文件，或比较其远端版本及本地草稿时使用。纯本地 Markdown 文件操作不触发本 skill。不负责将 Markdown 导入为飞书在线文档，也不负责文件搜索、权限、评论、移动、删除等云空间管理操作。

Docs & Writing778.7K installs

writing-beats

mattpocock/skills

Writing, exploit; assemble raw material into a journey of beats, grounding each term before a beat leans on it.

Docs & Writing490.7K installs

writing-shape

mattpocock/skills

Writing, exploit: shape raw material into an article, paragraph by paragraph.

Docs & Writing490.2K installs

writing-fragments

mattpocock/skills

Writing, explore: mine raw fragments, no structure yet.

Docs & Writing489.6K installs

writing-for-agents

mattpocock/skills

Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.

Docs & Writing479.3K installs