# agentsmd-audit

Audit a target repo's AGENTS.md file(s) for embedded secrets, structural completeness, and drift.

## What it does

Runs a single combined pass across every AGENTS.md file in a repo (root and any nested monorepo files): flags embedded secrets/credentials, checks structure against the agents.md common-sections checklist, and resolves referenced commands/paths against the actual repo to catch stale documentation. Outputs a compact findings report — findings only, grouped by dimension, each with Why and Fix. Never inspects provider-specific adapter files (CLAUDE.md, etc.) and never writes or fixes anything.

## Usage

```
/agentsmd-audit
```

Provide the path to the repo root to audit when invoking.

Also invoke it proactively after `agentsmd-author` creates or updates an AGENTS.md, or after a
hand-edit made outside `agentsmd-author` — the audit is what confirms the result is safe to commit.

## Files

| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `scripts/validate-secrets.sh` | Scans AGENTS.md files for embedded secrets, API keys, tokens, connection strings |
| `scripts/validate-structure.sh` | Checks for empty/placeholder content, common-sections checklist, nested-vs-root duplication |
| `scripts/validate-drift.sh` | Resolves referenced npm/make commands and file paths against the repo |
| `references/sources.md` | Provenance record — sources that informed this skill and which files each contributed to |
| `scripts/README.md` | Directory documentation for `scripts/` |
| `tests/README.md` | (source-only) Bats test dependency and run instructions |
| `tests/validate-secrets.bats` | (source-only) Bats test suite for `scripts/validate-secrets.sh` |
| `tests/validate-structure.bats` | (source-only) Bats test suite for `scripts/validate-structure.sh` |
| `tests/validate-drift.bats` | (source-only) Bats test suite for `scripts/validate-drift.sh` |

Rows marked **(source-only)** exist in the authoring source (`.apm/skills/agentsmd-audit/`) but are
not present in an installed plugin: the repo's `scripts/sync-plugin-content.sh` strips
`<category>/<name>/tests` when it generates the flat mirror, because these are dev-time fixtures no
plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install.