art-of-comment
Guide for editing existing and writing inline comments and JSDoc.
Skill by rakaadi
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.
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.
About
Use cases: writing
Reviews
Write a reviewNo 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
- Repository
- github.com/rakaadi/agent-kit
- First seen
- Oct 24, 2026
- Last checked
- Oct 24, 2026
- Source
- GitHubgithub-graphql
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.
Cite this page
art-of-comment skill. Agent Mart. https://agentmart.dev/skills/rakaadi-art-of-comment (last updated 2026-10-24)