Agent Surface Auditor

Portable standalone audit skill for agent-facing surfaces such as llms.txt, agents.md, mcp-tools.md, OpenAPI docs, sitemaps, and related machine-readable discovery files.

This package is designed to be published as:

1. a folder inside github.com/Citedy/skills
2. a standalone repository such as github.com/Citedy/agent-surface-auditor
3. an OpenSkills/npm-distributed convenience package

What It Includes

• a self-contained Codex skill
• direct-fetch, Browserbase, and Cloudflare providers
• repo audit mode and live URL audit mode
• markdown report generation
• chat-ready summary output
• prompt-pack generation for Codex and Claude Code

Folder Layout

agent-surface-auditor/
├── README.md
├── SKILL.md
├── agents/openai.yaml
├── references/
├── scripts/
│   ├── run-audit.js
│   ├── render-report.js
│   ├── summarize-report.js
│   ├── generate-prompt-pack.js
│   ├── test-*.js
│   └── providers/
└── scripts/install.sh

Quick Install

From Citedy/skills Monorepo

git clone https://github.com/Citedy/skills.git
bash /path/to/skills/agent-surface-auditor/scripts/install.sh

From a Standalone Repo

git clone https://github.com/Citedy/agent-surface-auditor.git
bash /path/to/agent-surface-auditor/scripts/install.sh

From npm

Direct one-shot usage:

npx agent-surface-auditor run --mode url --url https://example.com --provider auto

Global install:

npm install -g agent-surface-auditor
agent-surface-auditor summary --report ./agent-surface-live.json

What install.sh Does

• links the skill into ~/.codex/skills/agent-surface-auditor
• installs a small wrapper command into ~/.local/bin/agent-surface-auditor

The wrapper runs the standalone audit entrypoint from this package.

The npm package also exposes the same command directly:

agent-surface-auditor run ...

Example Usage

Repo Audit

agent-surface-auditor run \
  --mode repo \
  --repo-root /absolute/path/to/repo \
  --config /absolute/path/to/config-example.json \
  --out ./agent-surface-repo.json

Live Audit

agent-surface-auditor run \
  --mode url \
  --url https://example.com \
  --provider auto \
  --config /absolute/path/to/config-example.json \
  --out ./agent-surface-live.json

Summary

agent-surface-auditor summary --report ./agent-surface-live.json

Markdown Report

agent-surface-auditor render --report ./agent-surface-live.json --out ./agent-surface-live.md

Prompt Pack

agent-surface-auditor prompts --report ./agent-surface-live.json --out-dir ./prompt-pack

Self-Test

agent-surface-auditor self-test

Provider Support

Direct Fetch

No credentials required.

Browserbase Fetch

Required env:

BROWSERBASE_API_KEY=

Cloudflare Browser Rendering

Required env:

CF_ACCOUNT_ID=
CF_API_TOKEN=

Alternative auth:

CLOUDFLARE_ACCOUNT_ID=
CLOUDFLARE_API_KEY=
CF_AUTH_EMAIL=

Self-Test

bash scripts/self-test.sh

That verifies:

• local install wiring
• summary script works
• provider auth self-tests work

Publishing Notes

This package is ready to be:

• copied into a standalone repo with scripts/export-standalone.sh
• linked into ~/.codex/skills
• published to npm for npx agent-surface-auditor ...
• exposed through OpenSkills metadata