How to use the DetectAI agent skill: install and examples

What is an agent skill and what does DetectAI do?

An agent skill is a folder of instructions and supporting files that an AI agent loads when a request matches the skill's purpose. Once DetectAI is installed, the agent can examine a draft and report how much it looks machine-generated, and it explains which signals fired and why.

DetectAI answers two questions: how much does the text read as machine-generated, and does it carry an embedded mark? It uses four separate measures: a heuristic audit against a severity-tiered pattern catalog, deterministic statistical signals, an empirical Pangram score, and a keyless watermark scan. The measures often disagree, and the disagreement is useful information.

• Heuristic audit: flags known AI writing patterns and explains each flag.
• Statistical signals: entropy and burstiness measures, each labeled with its reliability.
• Pangram score: an AI percentage from a paid external detector, which needs a key.
• Watermark scan: looks for invisible characters, homoglyphs and bidi controls in the bytes of the text. It needs no key.

Install the DetectAI skill from the ZIP

Download the DetectAI ZIP from this page and unzip it. Place the resulting DetectAI folder in one of two locations. For a personal skill available in all your projects, use ~/.claude/skills/. For a skill that only applies to one project, use the .claude/skills/ folder inside that project.

If you use the Claude apps instead of a file system, you can upload the skill under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your project folder
• Claude apps: Settings → Capabilities → Skills, then upload the skill

What you need before you start

Detect and Watermark need no setup beyond installing the skill. The Watermark scan and the statistical signals run through bundled TypeScript tools (WatermarkScan.ts and StatSignals.ts), which require the Bun runtime.

The Pangram score is different. It needs a PANGRAM_API_KEY stored in ~/.claude/.env, network access to the Pangram service, and prepaid credits. Pangram is paid, at roughly $0.05 per 1,000 words. Key setup, credits and troubleshooting are covered in the skill's Setup.md file.

• Bun runtime for the bundled tools
• PANGRAM_API_KEY in ~/.claude/.env for Pangram scores only
• Network access for Pangram scores only
• Prepaid Pangram credits

How to trigger DetectAI with natural requests

You do not need to name the skill or a command. Ask in plain language, and the agent routes the request. The skill has three intents, each with its own trigger phrases.

Detect covers the pattern audit and statistical pass. Score covers the Pangram run. Watermark covers the invisible-character scan. If you ask whether text is both AI-generated and marked, the agent runs Score and Watermark together.

• Detect (no key): "scan for AI tells", "does this sound like AI", "audit this for AI-isms", "burstiness"
• Score (key needed): "is this AI generated", "AI detection score", "pangram", "compare these drafts"
• Watermark (no key): "is this watermarked", "scan for hidden invisible characters", "zero-width chars"

Examples of useful requests

Each example below maps a natural request to the check it triggers. The skill reports on the text and does not change it.

When you compare drafts, the skill ranks them relative to each other. Relative comparison is more informative than any single absolute number.

• "Scan this post for AI tells, don't change it" returns a P0/P1/P2 flag report. Each flag is marked as a clear problem or a judgment call.
• "Is this AI generated?" runs one Pangram check and gives the AI, AI-assisted and human percentages, with a note if the sample is short.
• "Which of these three drafts reads most human?" runs one Pangram call per draft and returns a ranked table.
• "Did my rewrite actually help?" scores the text before and after your edit, with known human-written passages in the same batch as a baseline.

Read the results without overreading them

DetectAI treats its signals as indicators, not proof. Heuristic flags can be wrong on short or edited text. Pangram gives a probability from one detector, and short samples are less reliable. A clean watermark scan does not mean the text is human-written, because the scan cannot detect sampling-time statistical watermarks.

Do not use these results as evidence of who wrote something or as grounds for misconduct. The skill also does not rewrite or "humanize" text, and warns against doing so to beat a detector.

• A watermark hit is byte-level evidence of an invisible character, whatever the other measures say.
• Short samples carry length caveats. Pangram reports are unreliable under about five sentences.
• Plagiarism and image detection are outside the skill's scope.

Run the watermark scan directly

The Watermark intent calls WatermarkScan.ts, which can output JSON with the --json flag. Each hit is reported with its codepoint, name and byte offset. Use this to check for hidden characters in a file or pasted text.