Skip to content
Back to skills

Audit Carla Docs

ASecurity

Finds undocumented and rotting documentation in a CARLA checkout — unreleased features, Python bindings missing from the API reference, documented API that no longer exists, sensors and catalogue actors missing from their reference pages, broken links, and pages unreachable from the nav. Static only, no build or server. Use when the user asks to "audit the docs", "find undocumented features", "what needs documenting", or is preparing a release or a new default branch.

  • 14,604 stars
  • 0 votes
  • 0 copies
  • 2 views
  • Added November 9, 2026
ai-agentspythonrustbashapidocumentation

Works with

  • api

Security analysis

A100/100

Pro scans all 5 files and shows the line behind each finding

Scanned November 9, 2026

npx -y skills add carla-simulator/carla --skill audit-carla-docs --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Audit Carla Docs?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Audit Carla Docs
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/carla-simulator-audit-carla-docs/badge)](https://www.skillsdirectory.com/skills/carla-simulator-audit-carla-docs)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: audit-carla-docs
description: Finds undocumented and rotting documentation in a CARLA checkout — unreleased features, Python bindings missing from the API reference, documented API that no longer exists, sensors and catalogue actors missing from their reference pages, broken links, and pages unreachable from the nav. Static only, no build or server. Use when the user asks to "audit the docs", "find undocumented features", "what needs documenting", or is preparing a release or a new default branch.
license: MIT
compatibility: Any OS with python3 and a CARLA checkout on disk. Needs no built engine, no packaged server, and no running simulator.
metadata:
  group: docs
  prerequisites: scripts/check_env.sh
  reference: references/signals.md
---

# Audit CARLA documentation (static)

Reports what the repository documents badly or not at all, as a markdown list a
human triages. It **only reads files** — so it is fast, repeatable and safe, and
it is blind to anything that exists only at runtime. The companion runtime audit
covers that; this skill will not let you forget it.

> **Paths.** `scripts/…` and `references/…` are relative to the directory holding
> this SKILL.md, not to the user's working directory. Prefix them with its
> absolute path.

The deliverable is a **report**, never an edit. Deciding what to document, and
writing it, are separate jobs — see `document-carla-feature`.

## Instructions

```
Progress:
- [ ] Step 1: Check prerequisites (bash scripts/check_env.sh), clear FAILs
- [ ] Step 2: Run the audit, writing the report to a file
- [ ] Step 3: Read the summary table and triage by signal, not top to bottom
- [ ] Step 4: Tell the user a runtime (Tier B) audit is still owed
```

### Step 1: Check prerequisites

```bash
bash scripts/check_env.sh
```

Only two things are hard blockers: no CARLA checkout, and no `python3`. A missing
input file downgrades its signal to skipped rather than failing the run.

### Step 2: Run the audit

```bash
python3 scripts/audit_docs.py --root "${CARLA_ROOT:?}" --out
```

Writes `Docs/audit_carla_docs.md`. Drop `--out` entirely to print to stdout
instead; pass `--out <path>` to write somewhere else.

`--signal <name>` narrows the run, repeatable: `changelog`, `binding`, `stale`,
`catalogue-stale`,
`sensor`, `catalogue`, `link`, `orphan`. Narrow when iterating on one area; run them all before a
release.

### Step 3: Triage

The report opens with a count per signal. **Work by signal, not in file order** —
the five differ enormously in effort per finding, and mixing them wastes time:

| signal | what it means | typical effort |
|---|---|---|
| `changelog` | every unreleased feature, as a checklist | high — **you check each one by hand** |
| `binding` | class or member exposed to Python, absent from the ymls | medium — edit the `.yml`, regenerate |
| `stale` | documented API that no longer exists in the bindings | medium — usually a rename or a typo, not a deletion |
| `catalogue-stale` | a catalogue page names an actor nothing knows about | small — delete the entry and its image |
| `sensor` | sensor id absent from `ref_sensors.md` | medium |
| `catalogue` | vehicle/walker/prop absent from its catalogue page | medium |
| `link` | target page or anchor missing | low — usually a one-line fix |
| `orphan` | page not in the `mkdocs.yml` nav | low — nav entry, or delete the page |

Two cautions the report cannot resolve for you, both in
[references/signals.md](references/signals.md):

- The `changelog` section **makes no claim about whether anything is
  documented.** It lists every unreleased feature as an unticked checkbox; you
  decide. Judging coverage automatically was tried and was too generous to
  trust — see the reference.
- **`Docs/python_api.md` is generated** from `PythonAPI/docs/*.yml` by
  `PythonAPI/docs/doc_gen.py`. Fix a `binding` finding in the `.yml` and
  regenerate. Editing the `.md` is silently reverted by the next run.

### Step 4: Say what this audit could not see

Always close by telling the user a runtime audit is still owed, and why. The
script prints this too, but say it in your own summary — it is the single
easiest thing to forget, and the gap it leaves is invisible.

A static pass cannot see the blueprint library, the available maps, or
per-blueprint attributes: new vehicles, walkers and props are **content**, so
they appear in no source diff.

## Examples

**Example 1: preparing a branch for release**

User says: "audit the docs before we make ue58-dev the default"

```bash
bash scripts/check_env.sh
python3 scripts/audit_docs.py --root "${CARLA_ROOT:?}" --out
```

Result: `Docs/audit_carla_docs.md` with a count per signal. Report the totals, name the two
or three heaviest items, and state that a runtime audit is still owed.

**Example 2: checking one area while fixing it**

User says: "are there still broken links in the docs?"

```bash
python3 scripts/audit_docs.py --root "${CARLA_ROOT:?}" --signal link
```

Result: the link findings on stdout. No file is written; nothing is changed.

## Troubleshooting

**Error: `not a carla checkout (no CHANGELOG.md): <path>`**
Cause: `--root` or `CARLA_ROOT` points somewhere else.
Solution: pass `--root /path/to/carla`, or `export CARLA_ROOT=` before sourcing.

**A signal reports 0 findings and you expected some**
Cause: its input is missing, so it was skipped — `check_env.sh` prints a WARN per
missing input.
Solution: re-read the `check_env.sh` output; a skipped signal is not a clean one.

**`link` findings inside fenced code or HTML comments**
Cause: none — the audit strips both before scanning. A link reported as broken is
in live prose.

## Outputs

- `Docs/audit_carla_docs.md` (or stdout) — findings grouped by signal, with a
  count table and the runtime-audit warning. The audit excludes this file from
  its own link and orphan signals.

Files in this skill

  • SKILL.md5.8 KB
  • references/signals.md12.5 KB
  • scripts/audit_docs.py35.1 KB
  • scripts/check_env.sh1.4 KB
  • scripts/env.sh1.2 KB

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in ai-agents →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.