- name
SKILL.md
El archivo de la skill permanece en el repositorio del publicador.
Pega el comando copiado en una terminal. Instala este SKILL.md en ese agente.
npx skills add notque/vexjoy-agent --skill comment-quality -a cursor -yPega el comando copiado en una terminal. Instala este SKILL.md en ese agente.
npx skills add notque/vexjoy-agent --skill comment-quality -a claude-code -yPega el comando copiado en una terminal. Instala este SKILL.md en ese agente.
npx skills add notque/vexjoy-agent --skill comment-quality -a codex -yPega el comando copiado en una terminal. Instala este SKILL.md en ese agente.
npx skills add notque/vexjoy-agent --skill comment-quality -a grok -yEnvía el mensaje copiado en un chat de Grok Bot. El Bot obtiene este SKILL.md de GitHub y lo añade a las skills que comparten todos tus Bots.
Install this skill: https://github.com/notque/vexjoy-agent/tree/HEAD/skills/code-quality/comment-qualityDel publicador
Review code comments for temporal references, development-activity language, and relative comparisons. Produces structured reports with actionable rewrites that explain WHAT the code does and WHY, only WHAT the code does and WHY. Supports .go, .py, .js, .ts, .md, and .txt files.
Goal: Identify all comments containing temporal, activity, or relative language.
Step 1: Determine scope
Read the repository CLAUDE.md first to pick up any project-specific comment conventions.
Scan only what was requested. If user specifies files, scan those files. If user specifies a directory, scan that directory. Honor the explicit scope -- even if you suspect other files have issues, honor the explicit scope and suggest expansion separately at the end.
If user explicitly requests auto-fix, enable it. Otherwise present findings for review. For large codebases, group findings by directory when reporting.
Step 2: Search for temporal patterns
Flag every instance of the following categories. No temporal word is "harmless" -- all temporal language ages poorly and must be rewritten regardless of how innocuous it seems:
Step 3: Filter false positives
Exclude from findings -- these are not developer comments and must remain untouched:
@generated markers (tooling markers)@deprecated annotations (keep the tag, flag only temporal explanation text after it)When a finding appears, inspect nearby comments in the same function or block -- temporal language tends to cluster.
Gate: All files in scope scanned. Findings list populated with file path, line number, and matched text. Every finding listed, not just the first few. Proceed only when gate passes.
Goal: Understand context for each finding to produce meaningful rewrites.
Step 1: Read surrounding code
For each finding, read the function, block, or section the comment describes. Understand what the code actually does. A rewrite without code context produces vague replacements that strip temporal words without adding substance.
Step 2: Classify the comment
| Finding | Type | Severity |
|---------|------|----------|
| "now uses JWT" | Temporal + Activity | High |
| "improved perf" | Activity | Medium |
| "Copyright 2024" | Legal (skip) | N/A |
Step 3: Determine replacement content
For each comment, identify:
Gate: Every finding classified with context understood. Proceed only when gate passes.
Goal: Generate specific, valuable replacement comments.
Step 1: Draft rewrites
For each finding, produce a structured entry with file path, line number, current text, suggested replacement, and reasoning:
**File: `path/to/file.ext`**
Line X - [Comment type]:
Current: // Authentication now uses JWT tokens
Suggested: // Authenticates requests using signed JWT tokens
Reason: "now uses" is temporal - describe current behavior only
Step 2: Validate rewrite quality
Each rewrite MUST pass these checks:
If a rewrite just removes the temporal word without adding substance, it fails validation. Simply deleting a word produces a useless comment -- // Updated error handling becoming // Error handling adds nothing. Rewrite with specific, descriptive content: // Handles database connection errors with exponential backoff retry.
Gate: All rewrites pass quality checks. No vague or empty replacements. Proceed only when gate passes.
Goal: Deliver structured, actionable report.
Step 1: Generate report
Report facts concisely with file paths and line numbers. Every finding must include the current text, suggested replacement, and reasoning -- a diagnostic-only count without rewrites creates work without providing solutions.
## Comment Quality Review
### Summary
- Files scanned: N
- Issues found: M
- Most common pattern: [temporal word]
### Findings
[All findings with file, line, current text, suggested text, reason]
### Recommendations
1. Apply suggested changes
2. Consider adding linter rules for temporal language prevention
Step 2: Apply fixes (if auto-fix enabled)
If user requested auto-fix, apply all rewrites using Edit tool. Verify each edit succeeded. Wait for explicit user permission before auto-fixing without explicit user authorization.
Step 3: Cleanup
Remove any scan results, intermediate reports, or helper files created during execution.
Gate: Report delivered. All findings accounted for. Task complete.
Cause: Files are clean or scope was too narrow Solution:
Cause: Large codebase with widespread temporal language Solution:
Cause: Comment only makes sense with development context that no longer exists Solution:
Load on demand when the current task matches the signal.
Review and fix temporal references in code comments.
---name: comment-qualitydescription: Review and fix temporal references in code comments.---# skills/code-quality/comment-quality/SKILL.mdPreguntas frecuentes
Descarga skills/code-quality/comment-quality/SKILL.md desde el publicador, o copia la ruta y abre el repositorio. PlugMCP lista la skill y no aloja el archivo.
El publicador lo mantiene en https://github.com/notque/vexjoy-agent.
Claude, Cursor, Codex y Grok Build pueden leer un SKILL.md que añadas desde el repositorio del publicador. Grok Bot lo instala cuando envías en un chat el enlace a la carpeta de la skill en GitHub.