# code-documentation

code-documentation is a Claude Code skill that teaches an agent to write self-explanatory code and comment only on reasons, for refactoring or API documentation.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 4 installs · ★ 8 repo stars
- Author: ilude
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/ilude/claude-code-config/tree/HEAD/skills/code-documentation/SKILL.md
- Updated: 2025-12-30
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/ilude-code-documentation

## What it does

The skill lays down one rule and sticks to it: name things well, structure the code, and keep comments for the reasons a decision was made. Most of the guidance goes to the failure modes — lines that restate the code below them, stale notes, decorative banners, commented-out blocks and changelogs kept in source.

A four-step check settles whether a comment is warranted at all: is the code already clear, would a rename do the job, does the note explain why rather than what, will it still help whoever reads this file later. Docstring and JSDoc templates come with worked examples in Python and JavaScript/TypeScript, covering parameters, return values, thrown errors and a sample call.

What ships is text the model reads. So the change shows up in the code your agent writes, not in a report over an existing file. It activates on the topic itself: mention comments, docstrings or API documentation in the conversation and the guidance kicks in.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add ilude/claude-code-config --skill code-documentation -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/code-documentation/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/code-documentation/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add ilude/claude-code-config --skill code-documentation -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/code-documentation/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add ilude/claude-code-config --skill code-documentation -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/code-documentation/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install ilude/claude-code-config skills/code-documentation
```

2. **Manually: put the files in place**
- File: `.github/skills/code-documentation/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add ilude/claude-code-config --skill code-documentation -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/ilude/claude-code-config --path skills/code-documentation
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/code-documentation/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add ilude/claude-code-config --skill code-documentation -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/ilude/claude-code-config/tree/HEAD/skills/code-documentation/SKILL.md

## When to use it
- stop the agent from commenting every other line
- record why a fee is calculated this way
- document a public function's parameters and errors
- strip commented-out code and changelog notes from a file
- settle a team argument about when a comment is warranted

## Example prompts
- Go through `billing.py` and flag comments that just restate the next line.
- Write a docstring for `calculate_fee` covering arguments, return value and raised errors.
- Add JSDoc to `loadProfile` and spell out what each option does.

## Similar
- [lean-comments](https://affpapa.org/en/nevibecode/skills/lean-comments.md) — skill · 17 installs
- [code-documenter](https://affpapa.org/en/nevibecode/skills/code-documenter.md) — skill · 6200 installs
- [documentation-templates](https://affpapa.org/en/nevibecode/skills/documentation-templates.md) — skill · 305 installs
- [docs-guard](https://affpapa.org/en/nevibecode/skills/docs-guard.md) — skill · 4200 installs
- [storybook-component-documentation](https://affpapa.org/en/nevibecode/skills/storybook-component-documentation.md) — skill · 166 installs
- [jsdoc-typescript-docs](https://affpapa.org/en/nevibecode/skills/jsdoc-typescript-docs.md) — skill · 572 installs

## Other versions with the same name
- [code-documentation · bytedance](https://affpapa.org/en/nevibecode/skills/code-documentation.md) — 2000 installs
- [code-documentation · moizibnyousaf](https://affpapa.org/en/nevibecode/skills/moizibnyousaf-code-documentation.md) — 571 installs
- [code-documentation · aj-geddes](https://affpapa.org/en/nevibecode/skills/aj-geddes-code-documentation.md) — 502 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
