human-comment
Write useful code comments and documentation in a natural developer voice, with lowercase prose and no decorative or generic AI-style filler. Use when the user invokes /human-comment, asks to add explanatory comments, document code with human-sounding comments, or rewrite robotic comments into short natural notes. Applies only to requested code and documentation; not a blanket instruction to comment every implementation.
- License 许可
- MIT
- 最近更新
- 2026-10-23
- Stars
- ★ 5
- Forks
- 0
01 前言 Front Matter
- name
- human-comment
- description
- Write useful code comments and documentation in a natural developer voice, with lowercase prose and no decorative or generic AI-style filler. Use when the user invokes /human-comment, asks to add explanatory comments, document code with human-sounding comments, or rewrite robotic comments into short natural notes. Applies only to requested code and documentation; not a blanket instruction to comment every implementation.
- allowed-tools
- Read Grep Glob Edit Write
02 资源文件 1
- 参考文档evals/evals.json2.8 KB
03 SKILL.md 正文
Human Comment
Leave the note a teammate would need to understand the code. Use lowercase prose, plain language, and enough explanation to be useful. Human-sounding means specific and accurate, not slang, deliberate typos, or a manufactured personality.
Scope
- Read the requested code and its surrounding context before commenting. Explain observed behavior, not a guessed intention.
- Add or rewrite comments and documentation only within the requested scope. Keep executable code, identifiers, imports, and behavior unchanged.
- Leave unrelated existing comments alone. Do not perform a repository-wide cleanup unless asked.
- Treat an explicit request for this skill as opting into comments for that task rather than applying
no-commentby default. Follow higher-priority instructions; if an applicable project rule forbids the requested comments and cannot be overridden, surface the conflict instead of silently ignoring it. - Use the user's requested language. Otherwise follow nearby useful documentation; if there is none, use the language of the request. Do not translate code identifiers.
Voice
Write lowercase prose, including the start of a sentence. Preserve exact spelling inside the prose when it carries meaning: getUserByID, UserID, Buffer, DateTime, SameSite, paths, URLs, literal values, and error strings.
// menggunakan getUserByID agar pemeriksaan akses tidak terlewati di jalur lain sebelum lookup selesai
Lowercase is a writing style, not a text transform over the file. Never lowercase executable code or machine-readable comment syntax. Preserve licenses, copyright notices, shebangs, build tags, source-map directives, linter suppressions, type-checker pragmas, and documentation tags or types exactly. Keep @param {UserID} userID intact; lowercase only its human-readable description.
Use the language of a developer leaving a useful note. Avoid "this function is responsible for", "it is important to note", "robust", "seamless", and other wording that adds no concrete fact. Do not introduce first-person stories, jokes, or claims about who wrote the code.
What earns a comment
A comment can explain why or how. Prefer information the reader cannot get by glancing at the next statement:
- a non-obvious algorithm or transformation;
- a business rule, unit, boundary, or assumption;
- a security constraint, race condition, or compatibility workaround;
- a side effect, failure mode, or public API contract.
Do not force a comment onto every function, block, or line. Skip trivial narration such as // menambah count above count++. A short explanation of a meaningful block is fine even when it describes what the block does. The goal is understanding, not a blanket ban on explaining behavior.
// menggunakan bcrypt terhadap password
That style is fine when the block hashes the password. Call hashing hashing, not encryption; bcrypt does not provide reversible encryption. If the actual block compares a password against an existing hash, describe comparison instead.
Prefer a short line. Use more lines only when the requested documentation needs them to explain a real contract or subtle behavior. Brevity should not erase information the reader needs.
No decoration
Do not add emoji, repeated-character separators, boxes, all-caps headings, section banners, "fase 1", "step 2", or end markers. A comment should carry information, not label visible control flow.
Instead of a banner announcing password processing, write the relevant note directly:
// hash password sebelum disimpan
Do not replace a decorative banner with an equally empty lowercase label such as // proses utama. Replace it with a specific explanation, or remove it if nothing useful remains.
Documentation
Use the language's existing documentation syntax when documentation is requested, such as JSDoc, PHPDoc, docstrings, or Rust doc comments. Required delimiters and tags are syntax, not decoration.
Document what a caller needs to know: input meaning or units, return behavior, edge cases, mutation, side effects, and errors actually visible in the implementation. Do not repeat the signature with filler like @param price the price.
/** returns null when UserID has no matching record; does not create one */
Do not invent guarantees such as constant-time comparison, atomic writes, automatic retries, or validation that the implementation does not provide. When context is missing, omit the claim or ask for the missing information.
Procedure
- Read the target and enough surrounding code to understand its behavior.
- Identify where an explanation would help, or which existing comments were requested for rewriting.
- Write natural lowercase prose while preserving exact technical tokens and machine-readable comments.
- Review the diff: only scoped comments or documentation changed; no decorative filler, unsupported claims, or incidental code formatting.
- Run existing relevant checks when available. If a directive or doctest was touched, verify its behavior rather than assuming comments are inert.
Final check
- Does each new comment teach something concrete?
- Does the description match the actual code?
- Is prose lowercase without corrupting identifiers or directives?
- Are language and wording natural for the surrounding work?
- Are executable code and unrelated comments unchanged?
If the code needs no explanation, say so rather than adding noise to satisfy a comment quota.
04 同仓库更多 Skills
writing-guidelines
Review docs/prose for Writing Guidelines compliance. Use when asked to "review my docs", "check writing style", "audit prose", "review docs voice and tone", or "check this page against the writing handbook".
writing-for-agents
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
wrangler
Cloudflare Workers CLI for deploying, developing, and managing Workers, KV, R2, D1, Vectorize, Hyperdrive, Workers AI, Containers, Queues, Workflows, Pipelines, and Secrets Store. Load before running wrangler commands to ensure correct syntax and best practices. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.
workers-best-practices
Reviews and authors Cloudflare Workers code against production best practices. Load when writing new Workers, reviewing Worker code, configuring wrangler.jsonc, or checking for common Workers anti-patterns (streaming, floating promises, global state, secrets, bindings, observability). Biases towards retrieval from Cloudflare docs over pre-trained knowledge.
web-perf
Analyzes web performance using Chrome DevTools MCP. Measures Core Web Vitals (LCP, INP, CLS) and supplementary metrics (FCP, TBT, Speed Index), identifies render-blocking resources, network dependency chains, layout shifts, caching issues, and accessibility gaps. Use when asked to audit, profile, debug, or optimize page load performance, Lighthouse scores, or site speed. Biases towards retrieval from current documentation over pre-trained knowledge.
using-agent-skills
Discovers and invokes agent skills. Use when starting a session, or when you need to decide which skill or workflow applies to the piece of work at hand. This is the meta-skill that governs how all other skills are discovered and invoked.