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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
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. Use when this capability is needed.4---56# Comments Extraction Skill78Extract comment locations from git-changed files for analysis by the comment-cleaner agent.910## What This Skill Does1112- Detects files changed in a git scope (branch or unstaged)13- Extracts all comments with line numbers and context14- Outputs structured JSON for downstream processing15- Supports multiple programming languages1617## When to Use1819Activate this skill when:2021- Preparing for comment cleanup operations22- Auditing code documentation coverage23- Analyzing comment patterns in a codebase24- Working with the comment-cleaner agent2526## Supported Languages2728| 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` | `//`, `#` | `/* */` |3536## Usage3738### Extract Comments from Git Scope3940```bash41# Default: files changed since branch diverged from main42rp1 agent-tools comment-extract branch main4344# Only unstaged files (pre-commit use case)45rp1 agent-tools comment-extract unstaged main4647# Extract from commit range with line-scoped filtering48rp1 agent-tools comment-extract "abc123..def456" main --line-scoped49```5051### Output Format5253```json54{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```7576### Output Fields7778| 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 |9495## Error Handling9697The tool handles:9899- 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)103104Error output format:105106```json107{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```120121## Integration122123This skill is used by the `comment-cleaner` agent to:1241251. Get a manifest of all comments in scope1262. Avoid reading entire files for comment detection1273. Process comments efficiently with context128129## Limitations130131- 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 issues134135---136> Converted and distributed by [TomeVault](https://tomevault.io/claim/rp1-run) — claim your Tome and manage your conversions.137<!-- tomevault:4.0:skill_md:2026-04-11 -->
tomevault-io