Skip to content
Agentmart
Submit a tool

art-of-comment

Guide for editing existing and writing inline comments and JSDoc.

Skill by rakaadi

IndexedMIT★ 1
Write a review

Chalk Labs

Need help deploying art-of-comment?

Chalk Labs sets up agents like this inside real teams: connected to your tools, tested on your data, with a human in the loop where it matters.

Book a call

Install

Works with Claude Code, Claude apps, Codex, Cursor, Gemini CLI, GitHub Copilot, VS Code, OpenCode, Goose, Windsurf. Read the repository before you give any tool access to your data.

npx agentmarket install skill/rakaadi-art-of-comment

Asks which of your tools to add it to (Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI, Claude Desktop) and shows the change first. See https://agentmart.dev/cli.

Get the weekly diff

The weekly diff: one email a week with new agent tools, notable updates and grade changes, plus security alerts for tools you follow. Double opt-in, one-click unsubscribe.

We use your email only for this newsletter. Privacy

About

Guide for editing existing and writing inline comments and JSDoc. Use when generating comments for documenting new components or functions, non-obvious code behaviour, or complex logic.

Use cases: writing

No reviews yet. Installed it? Reviews come from verified installers only. How reviews work

Permissions

What this skill can do and what it asks for, from its SKILL.md and code. Checked Nov 1, 2026.

Tools
No tools found
Secrets
None asked for
Install scripts
None found

Network hosts it talks to 1

  • codeload.github.com · found in install command

Files it touches

  • ~/.claude/skills/art-of-comment

What's inside

Skill name
art-of-comment
Description
Guide for editing existing and writing inline comments and JSDoc. Use when generating comments for documenting new components or functions, non-obvious code behaviour, or complex logic.
License
MIT
Instructions
30 lines in SKILL.md · view on GitHub

Files (6)

  • SKILL.md
  • openai.yaml · agents/
  • example-design-signal.md
  • example-evidence-backed-comments.md
  • example-inline-comment-triage.md
  • example-reusable-interface-docs.md

SKILL.md (first lines)

# Overview

Every comment should earn its place. A good comment adds context the code alone cannot convey: why a decision was made, what trade-off was accepted, what side effect or constraint matters, or how a non-obvious piece fits the bigger picture. A comment that merely restates the code is noise and adds maintenance burden. When in doubt, prefer no comment over a redundant one.

## Guidelines

- **Comment only when needed.** Add comments or JSDoc only when the code alone does not make the intent clear. If the code is self-explanatory, prefer no comment.
- **Explain intent, rationale, or consequences.** Good comments add information the code cannot: why a decision was made, what trade-off was accepted, what side effect, exception, or constraint a caller should know about.
- **Do not restate the code.** If a comment only paraphrases names, conditions, or control flow, remove it. Use words that add meaning, not synonyms for the code.
- **Use JSDoc for reusable interfaces.** Functions, types, and constants used elsewhere should use `/** ... */` when hover documentation would help a caller understand purpose, important parameters, return semantics, side effects, or usage constraints.
- **Keep implementation detail out of interface docs.** Declaration-level comments should describe what the symbol promises or why it exists, not internal steps that only matter to the implementation.
- **Keep inline comments short.** Inline comments should usually fit in 1-2 lines and explain *why* or *why not*, not narrate *what* the next line does.
- **Document trade-offs and non-obvious behavior.** If the code accepts a compromise, workaround, minimum threshold, ordering rule, or other surprising behavior, explain the rationale briefly.
- **Treat hard-to-write comments as a design signal.** If a comment is difficult to make both simple and clear, the code or API may need to be renamed, split, or refactored instead of further explained.
- **Ground comments in evidence.** Do not invent rationale. Base comments on code behavior, library docs, project conventions, or explicit user requirements, and ask for clarification when intent is uncertain.
- **Keep comments consistent with surrounding docs.** Do not contradict nearby comments, and do not duplicate information already explained elsewhere unless repetition helps the caller at that exact point.
- **Update or remove stale comments.** An outdated comment is usually worse than no comment.

## Examples

Read the example file that matches the kind of comment you are writing or reviewing.

- `example-inline-comment-triage.md` — Inline comment keep/remove decisions, duplicate comments, and trade-off comments. Read when deciding whether an inline comment earns its place.
- `example-reusable-interface-docs.md` — Reusable interface JSDoc that documents the caller-facing contract without leaking internals. Read when writing declaration-level docs for shared symbols.
- `example-evidence-backed-comments.md` — Evidence-backed workaround and compatibility comments. Read when documenting a browser bug, platform limitation, or reproduction note.
- `example-design-signal.md` — Cases where better names remove the need for comments. Read when a comment seems to compensate for unclear naming or structure.

The stale-comment rule does not need a dedicated example. Apply it whenever you modify code with existing comments.

From rakaadi/agent-kit, MIT.

Signals

Stars
1
Forks
0
Open issues
1
Last commit (this folder)
Aug 9, 2026 (3 months ago)
Last release
Oct 13, 2026 (1 month ago)

From GitHub (fetched Oct 24, 2026).

Details

License
MIT
First seen
Oct 24, 2026
Last checked
Oct 24, 2026

Done for you

Rather not set it up yourself?

Chalk Labs scopes, builds and runs agents for your team: the task audit, the eval harness, the integrations and the weekly ops report. Fixed scope, priced before we start.

See how we build AI agents →Read the case studies

Chalk Labs is a two-founder AI and growth studio. We build AI agents, CRMs and MVPs for Web3 and AI companies, and have shipped 50+ product and token launches.

launches shipped
50+
launches shipped
media placements
500+
media placements
founders on every account
2
founders on every account

Press we've placed: Forbes · CoinDesk · Decrypt · Cointelegraph · The Block

Rahil Jain, Co-founder, Chalk Labs. Ex-Goldman Sachs engineer. You talk to the person who builds it.

Get art-of-comment running in your business

Tell us what you want to automate. A founder replies within one working day with a plan, not a pitch deck.

Goes to the Chalk Labs founders, not the newsletter. Privacy

Need help deploying art-of-comment?

CallGet help
Cite this page

art-of-comment skill. Agent Mart. https://agentmart.dev/skills/rakaadi-art-of-comment (last updated 2026-10-24)