skills.rest
Gambitnl
GambitnlCOMMUNITY
Explore all skills by this author →
GitHub

Code Commentary

Enforce plain-English file, section, and block comments across code.

Updated Nov 23, 2025
Search Tags:#documentation#collaboration#maintainability#code comments#developer tooling#plain english
One-click install
npx skills add https://github.com/Gambitnl/Aralia --skill code-commentary
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: Code Commentary
Source: https://github.com/Gambitnl/Aralia/tree/main/public/agent-docs/skills/code_commentary
Command: npx skills add https://github.com/Gambitnl/Aralia --skill code-commentary

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill ensures that all code is accompanied by clear, plain-English comments, making it understandable for the project owner and future developers who do not read code.

Core Features & Use Cases

  • Universal Commenting Standard: Enforces consistent commenting practices across all code files.
  • Three Layers of Commentary: Guides developers on commenting at the file, section, and block levels.
  • Debt and Shortcut Flagging: Provides clear methods (// DEBT:, // HACK:, // TODO(next-agent):) to mark areas needing future attention.
  • Preservationist Rules: Outlines principles for making changes with minimal impact and maintaining structural integrity.
  • Red Flags Checklist: Helps identify and rectify common anti-patterns like excessive any types or console.log statements.
  • Use Case: When writing a new feature, use this skill to ensure every part of the new code is explained, making it easy for the project owner to review and understand without needing to dive into the code logic itself.

Quick Start

Apply the code commentary skill to document the newly written TypeScript file located at '/src/utils/helpers.ts'.

Frequently Asked Questions about Code Commentary

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I enforce a universal code commenting standard across my project?▼

You can enforce a universal code commenting standard by applying rules for file headers, section separators, and block-level comments, ensuring plain-English explanations of functionality, rationale, and dependencies.

What is the best way to document code for non-technical project owners?▼

Documenting code for non-technical project owners requires plain-English comments explaining functionality and rationale, allowing them to review features without needing to read or understand the underlying code logic.

How do I flag technical debt and shortcuts in code comments?▼

You can flag technical debt and shortcuts in code comments by using specific tags like `// DEBT:`, `// HACK:`, and `// TODO(next-agent):` to clearly mark areas needing future attention or refactoring.

Does this code documentation approach work for existing codebase edits?▼

Yes, this code documentation approach works for existing codebase edits by applying preservationist rules that guide developers to make changes with minimal impact while maintaining the structural integrity of the file.

How do I identify maintainability red flags when writing code comments?▼

You identify maintainability red flags by using a dedicated checklist to detect and rectify common anti-patterns, ensuring the codebase remains clean and understandable for future collaboration.

Related Skills

Explore More Software Engineering Skills→
thoughtbotthoughtbot
17

explain

Analyze Rails source code and execution paths to explain logic and architecture.

Official
Intermediate
VoDaiLoczVoDaiLocz
24

lint-and-validate

Automate linting and static analysis of code in CI pipelines.

Community
Intermediate
elijahmurrayelijahmurray
2

pr-review

Check out pull request branches, review code changes, and apply feedback.

Community
Basic
CloudyWingCloudyWing

translate-zh-en

Translate technical documentation between Traditional Chinese and English while preserving code blocks.

Community
Intermediate