# Gabrielfst30 Super Gabriel Claude Toolkit Natspec

> Gabrielfst30 Super Gabriel Claude Toolkit Natspec

- Skill: `tomevault-io/gabrielfst30-super-gabriel-claude-toolkit-natspec` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/gabrielfst30-super-gabriel-claude-toolkit-natspec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/gabrielfst30-super-gabriel-claude-toolkit-natspec/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/gabrielfst30-super-gabriel-claude-toolkit-natspec

---


# /natspec

Generates NatSpec-style documentation comments for complex implementations
in any language. Detects the file's language, adapts the comment syntax, and
documents all public/exported declarations.

## Reference

Read `references/natspec-patterns.md` for tag rules, format by language,
and examples before starting.

---

## Flow

### Step 1 — Identify the target

If the argument is a file → process only that file.

If the argument is a directory:
→ Glob for all source files recursively.
→ Ignore: `node_modules/`, `dist/`, `build/`, `.git/`, config files.

If no argument → ask the user: specific file or entire directory?

### Step 2 — Detect language and mode

**Language** (by file extension):

| Extension | Language | Comment syntax |
|---|---|---|
| `.ts`, `.tsx` | TypeScript | `/** ... */` (JSDoc) |
| `.js`, `.jsx` | JavaScript | `/** ... */` (JSDoc) |
| `.sol` | Solidity | `/// ...` (NatSpec native) |
| `.py` | Python | `"""..."""` (docstring) |
| `.rs` | Rust | `/// ...` (doc comments) |
| `.go` | Go | `// ...` (GoDoc) |
| Other | Generic | `/** ... */` |

**Mode** (by current coverage):

| Situation | Mode |
|---|---|
| No documentation at all | `full` — document everything |
| Partial documentation | `patch` — complete what's missing |
| Fully documented | `audit` — validate only |

### Step 3 — Execute in parallel

For each file in `full` or `patch` mode, spawn a `natspec-writer`:

```
Agent(
  subagent_type: "natspec-writer",
  prompt: "File: [path]. Language: [language]. Mode: [full|patch].
           Read the file, generate NatSpec for all public/exported functions,
           classes, interfaces, types, events, and errors.
           Reference: .claude/skills/natspec/references/natspec-patterns.md"
)
```

Independent files run in parallel. One agent per file.

### Step 4 — Validate in parallel

After all writers complete, spawn a `natspec-validator` per file:

```
Agent(
  subagent_type: "natspec-validator",
  prompt: "Validate NatSpec completeness in: [path]. Language: [language].
           Reference: .claude/skills/natspec/references/natspec-patterns.md"
)
```

### Step 5 — Consolidated output

```
NATSPEC COMPLETE

Files processed: N
  ✅ src/module/file.ts — 12 declarations documented, 0 issues
  ✅ contracts/Vault.sol — 8 declarations documented, 0 issues
  ⚠️ src/lib/api.ts — 5 declarations documented, 2 warnings
     └─ Line 47: @returns missing description
     └─ Line 89: @param has no description

Total: N functions | N classes | N types documented
```

---

## Special cases

**Private/internal functions:**
→ `@dev` only — `@notice` is optional (not ABI/API public).

**Inheritance / Override:**
→ Override with no added logic: use `@inheritdoc`.
→ Override with added logic: document normally + mention the override.

**Complex types (interfaces, enums, structs):**
→ Document the type with `@notice`.
→ Document each field/member with inline `@dev`.

**Async functions:**
→ `@returns` must describe what the Promise resolves to, not the Promise itself.

## Success Criteria
- [ ] All exported/public declarations have `@notice` and `@param`/`@returns`
- [ ] Private functions have `@dev` when logic is non-obvious
- [ ] Comment syntax correct for each file's language
- [ ] Validator reports PASSED for all files

---
> Source: [gabrielfst30/super-gabriel-claude-toolkit](https://github.com/gabrielfst30/super-gabriel-claude-toolkit) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-15 -->