Comments Extraction Skill
Extract comment locations from git-changed files for analysis by the comment-cleaner agent.
What This Skill Does
- Detects files changed in a git scope (branch or unstaged)
- Extracts all comments with line numbers and context
- Outputs structured JSON for downstream processing
- Supports multiple programming languages
When to Use
Activate this skill when:
- Preparing for comment cleanup operations
- Auditing code documentation coverage
- Analyzing comment patterns in a codebase
- Working with the comment-cleaner agent
Supported Languages
| Extension |
Single-line |
Multi-line |
.py, .sh, .rb, .yml, .yaml |
# |
N/A |
.js, .ts, .tsx, .jsx, .go, .rs, .java, .kt, .swift, .c, .cpp, .h, .hpp |
// |
/* */ |
.html, .xml, .vue, .svelte |
N/A |
<!-- --> |
.css, .scss, .less |
N/A |
/* */ |
.php |
//, # |
/* */ |
Usage
Extract Comments from Git Scope
# Default: files changed since branch diverged from main
rp1 agent-tools comment-extract branch main
# Only unstaged files (pre-commit use case)
rp1 agent-tools comment-extract unstaged main
# Extract from commit range with line-scoped filtering
rp1 agent-tools comment-extract "abc123..def456" main --line-scoped
Output Format
{
"success": true,
"tool": "comment-extract",
"data": {
"scope": "branch",
"base": "main",
"filesScanned": 12,
"linesAdded": 150,
"comments": [
{
"file": "src/auth.py",
"line": 45,
"type": "single",
"content": "# Check if user is active",
"contextBefore": "def validate_user(user):",
"contextAfter": " if user.is_active:"
}
]
}
}
Output Fields
| Field |
Description |
success |
Whether extraction completed successfully |
tool |
Tool name (comment-extract) |
data.scope |
The scope used (branch, unstaged, or commit range) |
data.base |
Base branch for comparison |
data.filesScanned |
Number of files processed |
data.linesAdded |
Total lines added in diff |
data.lineScoped |
Whether line-scoped filtering was applied |
data.comments |
Array of comment objects |
data.comments[].file |
Relative file path |
data.comments[].line |
Line number (1-indexed) |
data.comments[].type |
Comment type (single or multi) |
data.comments[].content |
The comment text |
data.comments[].contextBefore |
Line before the comment |
data.comments[].contextAfter |
Line after the comment |
Error Handling
The tool handles:
- Git command failures (not a repo, invalid branch)
- Missing files (deleted in working tree)
- Binary files (automatically skipped)
- Encoding issues (UTF-8)
Error output format:
{
"success": false,
"tool": "comment-extract",
"data": {
"scope": "branch",
"base": "main",
"filesScanned": 0,
"linesAdded": 0,
"comments": []
},
"errors": [{ "message": "Not a git repository" }]
}
Integration
This skill is used by the comment-cleaner agent to:
- Get a manifest of all comments in scope
- Avoid reading entire files for comment detection
- Process comments efficiently with context
Limitations
- Does not detect comments inside string literals (best effort)
- Multi-line string docstrings in Python are not extracted (intentional - docstrings are kept)
- Very large files (>10000 lines) are skipped to prevent memory issues
1---2name: code-comments3description: Extract comment locations from code files for analysis. Use when cleaning comments, auditing code documentation, or analyzing comment patterns. Supports Python, JavaScript, TypeScript, Go, Rust, Java, C/C++, Ruby, PHP, Shell scripts. Trigger terms - comments, extract comments, code comments, comment analysis, documentation audit, comment cleanup.4---5
6# Comments Extraction Skill
7
8Extract comment locations from git-changed files for analysis by the comment-cleaner agent.
9
10## What This Skill Does
11
12- Detects files changed in a git scope (branch or unstaged)
13- Extracts all comments with line numbers and context
14- Outputs structured JSON for downstream processing
15- Supports multiple programming languages
16
17## When to Use
18
19Activate this skill when:
20
21- Preparing for comment cleanup operations
22- Auditing code documentation coverage
23- Analyzing comment patterns in a codebase
24- Working with the comment-cleaner agent
25
26## Supported Languages
27
28| Extension | Single-line | Multi-line |
29|-----------|-------------|------------|
30| `.py`, `.sh`, `.rb`, `.yml`, `.yaml` | `#` | N/A |
31| `.js`, `.ts`, `.tsx`, `.jsx`, `.go`, `.rs`, `.java`, `.kt`, `.swift`, `.c`, `.cpp`, `.h`, `.hpp` | `//` | `/* */` |
32| `.html`, `.xml`, `.vue`, `.svelte` | N/A | `<!-- -->` |
33| `.css`, `.scss`, `.less` | N/A | `/* */` |
34| `.php` | `//`, `#` | `/* */` |
35
36## Usage
37
38### Extract Comments from Git Scope
39
40```bash
41# Default: files changed since branch diverged from main
42rp1 agent-tools comment-extract branch main
43
44# Only unstaged files (pre-commit use case)
45rp1 agent-tools comment-extract unstaged main
46
47# Extract from commit range with line-scoped filtering
48rp1 agent-tools comment-extract "abc123..def456" main --line-scoped
49```
50
51### Output Format
52
53```json
54{
55 "success": true,
56 "tool": "comment-extract",
57 "data": {
58 "scope": "branch",
59 "base": "main",
60 "filesScanned": 12,
61 "linesAdded": 150,
62 "comments": [
63 {
64 "file": "src/auth.py",
65 "line": 45,
66 "type": "single",
67 "content": "# Check if user is active",
68 "contextBefore": "def validate_user(user):",
69 "contextAfter": " if user.is_active:"
70 }
71 ]
72 }
73}
74```
75
76### Output Fields
77
78| Field | Description |
79|-------|-------------|
80| `success` | Whether extraction completed successfully |
81| `tool` | Tool name (`comment-extract`) |
82| `data.scope` | The scope used (`branch`, `unstaged`, or commit range) |
83| `data.base` | Base branch for comparison |
84| `data.filesScanned` | Number of files processed |
85| `data.linesAdded` | Total lines added in diff |
86| `data.lineScoped` | Whether line-scoped filtering was applied |
87| `data.comments` | Array of comment objects |
88| `data.comments[].file` | Relative file path |
89| `data.comments[].line` | Line number (1-indexed) |
90| `data.comments[].type` | Comment type (`single` or `multi`) |
91| `data.comments[].content` | The comment text |
92| `data.comments[].contextBefore` | Line before the comment |
93| `data.comments[].contextAfter` | Line after the comment |
94
95## Error Handling
96
97The tool handles:
98
99- Git command failures (not a repo, invalid branch)
100- Missing files (deleted in working tree)
101- Binary files (automatically skipped)
102- Encoding issues (UTF-8)
103
104Error output format:
105
106```json
107{
108 "success": false,
109 "tool": "comment-extract",
110 "data": {
111 "scope": "branch",
112 "base": "main",
113 "filesScanned": 0,
114 "linesAdded": 0,
115 "comments": []
116 },
117 "errors": [{ "message": "Not a git repository" }]
118}
119```
120
121## Integration
122
123This skill is used by the `comment-cleaner` agent to:
124
1251. Get a manifest of all comments in scope
1262. Avoid reading entire files for comment detection
1273. Process comments efficiently with context
128
129## Limitations
130
131- Does not detect comments inside string literals (best effort)
132- Multi-line string docstrings in Python are not extracted (intentional - docstrings are kept)
133- Very large files (>10000 lines) are skipped to prevent memory issues
majiayu000