global-commenting
Write minimal, evergreen code comments that explain complex logic without documenting obvious behavior or temporary changes. Use this skill when adding comments to PHP files, TypeScript/JavaScript files, or any code files, when documenting complex algorithms or business logic, when adding PHPDoc blocks or JSDoc comments, when writing self-documenting code with clear naming, or when reviewing existing comments for relevance and necessity. Focus on keeping code self-explanatory through clear structure and naming rather than relying heavily on comments.
Best use case
global-commenting is best used when you need a repeatable AI agent workflow instead of a one-off prompt. It is especially useful for teams working in multi. Write minimal, evergreen code comments that explain complex logic without documenting obvious behavior or temporary changes. Use this skill when adding comments to PHP files, TypeScript/JavaScript files, or any code files, when documenting complex algorithms or business logic, when adding PHPDoc blocks or JSDoc comments, when writing self-documenting code with clear naming, or when reviewing existing comments for relevance and necessity. Focus on keeping code self-explanatory through clear structure and naming rather than relying heavily on comments.
Write minimal, evergreen code comments that explain complex logic without documenting obvious behavior or temporary changes. Use this skill when adding comments to PHP files, TypeScript/JavaScript files, or any code files, when documenting complex algorithms or business logic, when adding PHPDoc blocks or JSDoc comments, when writing self-documenting code with clear naming, or when reviewing existing comments for relevance and necessity. Focus on keeping code self-explanatory through clear structure and naming rather than relying heavily on comments.
Users should expect a more consistent workflow output, faster repeated execution, and less time spent rewriting prompts from scratch.
Practical example
Example input
Use the "global-commenting" skill to help with this workflow task. Context: Write minimal, evergreen code comments that explain complex logic without documenting obvious behavior or temporary changes. Use this skill when adding comments to PHP files, TypeScript/JavaScript files, or any code files, when documenting complex algorithms or business logic, when adding PHPDoc blocks or JSDoc comments, when writing self-documenting code with clear naming, or when reviewing existing comments for relevance and necessity. Focus on keeping code self-explanatory through clear structure and naming rather than relying heavily on comments.
Example output
A structured workflow result with clearer steps, more consistent formatting, and an output that is easier to reuse in the next run.
When to use this skill
- Use this skill when you want a reusable workflow rather than writing the same prompt again and again.
When not to use this skill
- Do not use this when you only need a one-off answer and do not need a reusable workflow.
- Do not use it if you cannot install or maintain the related files, repository context, or supporting tools.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/global-commenting/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How global-commenting Compares
| Feature / Agent | global-commenting | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Write minimal, evergreen code comments that explain complex logic without documenting obvious behavior or temporary changes. Use this skill when adding comments to PHP files, TypeScript/JavaScript files, or any code files, when documenting complex algorithms or business logic, when adding PHPDoc blocks or JSDoc comments, when writing self-documenting code with clear naming, or when reviewing existing comments for relevance and necessity. Focus on keeping code self-explanatory through clear structure and naming rather than relying heavily on comments.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
Related Guides
SKILL.md Source
# Global Commenting This Skill provides Claude Code with specific guidance on how to adhere to coding standards as they relate to how it should handle global commenting. ## When to use this skill - When adding comments to PHP, TypeScript, JavaScript, or any code files - When documenting complex business logic or algorithms that aren't immediately obvious - When writing PHPDoc blocks for PHP classes, methods, or functions - When adding JSDoc or TSDoc comments for TypeScript/JavaScript functions - When explaining the "why" behind non-obvious code decisions - When refactoring code to be more self-documenting and reduce comment necessity - When reviewing existing comments to ensure they're evergreen and still relevant - When removing outdated comments about temporary fixes or recent changes - When documenting complex array shapes or data structures in PHPDoc - When choosing between adding a comment vs. refactoring for clarity ## Instructions For details, refer to the information provided in this file: [global commenting](../../../agent-os/standards/global/commenting.md)
Related Skills
global-validation
Implement server-side validation with allowlists, specific error messages, type checking, and sanitization to prevent security vulnerabilities and ensure data integrity. Use this skill when creating or editing form request classes, when validating API inputs, when implementing validation rules in controllers or services, when writing client-side validation for user experience, when sanitizing user input to prevent injection attacks, when validating business rules, when implementing error message display, or when ensuring consistent validation across all application entry points.
global-tech-stack
Understand and adhere to the project's technology stack including Laravel, PHP, React, PostgreSQL, Pest, Tailwind CSS, and all configured tools and services. Use this skill when making architectural decisions, when choosing libraries or packages, when configuring development tools, when setting up testing frameworks, when implementing authentication, when integrating third-party services, when configuring CI/CD pipelines, when setting up local development environments, or when ensuring consistency with the established tech stack across all parts of the application.
global-error-handling
Implement user-friendly error handling with specific exception types, centralized error handling, graceful degradation, and proper resource cleanup. Use this skill when implementing error handling in controllers, services, or API endpoints, when creating custom exception classes, when writing try-catch blocks, when handling external service failures, when implementing retry strategies, when displaying error messages to users, when cleaning up resources in finally blocks, or when implementing fail-fast validation and error detection.
global-conventions
Follow consistent project structure, version control practices, environment configuration, code review processes, and development conventions across the entire application. Use this skill when organizing project files and directories, when writing commit messages or creating pull requests, when managing environment variables and configuration, when participating in code reviews, when defining testing requirements, when using feature flags, when maintaining changelogs, when documenting setup instructions, or when establishing consistent development practices across the team.
global-coding-style
Maintain consistent code formatting, naming conventions, type safety, and automated code quality standards across PHP and TypeScript/JavaScript. Use this skill when writing or editing any PHP files (.php), TypeScript/JavaScript files (.ts, .tsx, .js, .jsx), when implementing type declarations and return types, when running code formatters (Laravel Pint, Ultracite) or linters, when running static analysis tools (Larastan), when naming variables, functions, classes, or files, when applying DRY principles, when removing dead code, or when preparing code for review or commit.
global-standards
Project-wide coding standards and conventions specialist. Use PROACTIVELY when writing code, making architectural decisions, or establishing project conventions. Covers coding style, commenting, error handling, validation, tech stack consistency, and project conventions across all languages and frameworks.
azure-quotas
Check/manage Azure quotas and usage across providers. For deployment planning, capacity validation, region selection. WHEN: "check quotas", "service limits", "current usage", "request quota increase", "quota exceeded", "validate capacity", "regional availability", "provisioning limits", "vCPU limit", "how many vCPUs available in my subscription".
raindrop-io
Manage Raindrop.io bookmarks with AI assistance. Save and organize bookmarks, search your collection, manage reading lists, and organize research materials. Use when working with bookmarks, web research, reading lists, or when user mentions Raindrop.io.
zlibrary-to-notebooklm
自动从 Z-Library 下载书籍并上传到 Google NotebookLM。支持 PDF/EPUB 格式，自动转换，一键创建知识库。
discover-skills
当你发现当前可用的技能都不够合适（或用户明确要求你寻找技能）时使用。本技能会基于任务目标和约束，给出一份精简的候选技能清单，帮助你选出最适配当前任务的技能。
web-performance-seo
Fix PageSpeed Insights/Lighthouse accessibility "!" errors caused by contrast audit failures (CSS filters, OKLCH/OKLAB, low opacity, gradient text, image backgrounds). Use for accessibility-driven SEO/performance debugging and remediation.
project-to-obsidian
将代码项目转换为 Obsidian 知识库。当用户提到 obsidian、项目文档、知识库、分析项目、转换项目 时激活。 【激活后必须执行】： 1. 先完整阅读本 SKILL.md 文件 2. 理解 AI 写入规则（默认到 00_Inbox/AI/、追加式、统一 Schema） 3. 执行 STEP 0: 使用 AskUserQuestion 询问用户确认 4. 用户确认后才开始 STEP 1 项目扫描 5. 严格按 STEP 0 → 1 → 2 → 3 → 4 顺序执行 【禁止行为】： - 禁止不读 SKILL.md 就开始分析项目 - 禁止跳过 STEP 0 用户确认 - 禁止直接在 30_Resources 创建（先到 00_Inbox/AI/） - 禁止自作主张决定输出位置