clientory-ai-visibility-skill

AI Visibility Scanner for Law Firms — Agent Skill for Codex and Claude

scan-ai-visibility is an open-source AI Agent Skill for measuring whether ChatGPT/OpenAI, Claude/Anthropic, Gemini, xAI, Perplexity, OpenRouter, and compatible models mention and recommend a law firm.

It helps law firms and legal marketers run an AI visibility audit—also called generative engine optimization (GEO), answer engine optimization (AEO), LLM visibility, or AI share-of-voice analysis. The skill tests approved prospective-client questions with web-grounded model APIs, records who appears and where they rank, identifies competing firms, and produces evidence-based recommendations.

The skill follows the open Agent Skills specification, works with Codex and Claude Code, uses the user's own API keys, and requires only one configured provider. The current version supports law firms only.

What the skill measures

• Every prospective-client prompt tested
• Firm mentions by provider and overall coverage
• Best rank, average rank, and top-three appearances
• Mention quality: description, location, and service relevance
• Competing firms recommended instead
• Target and competitor share of voice
• Prompt-specific visibility gaps and supporting response excerpts
• Prioritized recommendations with evidence, actions, and next-scan targets

The report includes human-readable Markdown and structured JSON, so users can ask follow-up questions without paying for another scan.

Safety and user control

The workflow is designed to prevent surprise API usage:

1. Collect the law-firm profile one question at a time.
2. Configure one or more model providers using private local key storage.
3. Generate prospective-client questions without web search.
4. Show every question for approval, editing, addition, replacement, or removal.
5. Preview the exact number of web-grounded model requests and possible charges.
6. Run only after separate, explicit approval.
7. Produce detailed evidence and recommendations.

API keys are never requested in chat and are never written to reports.

Supported AI providers

• OpenAI
• Anthropic Claude
• Google Gemini
• xAI Grok
• Perplexity
• OpenRouter
• Custom OpenAI-compatible endpoints through a JSON provider definition

Web search is enabled by default for built-in providers. A single provider is enough to run the skill.

Install

Clone this repository first:

git clone https://github.com/lishangyanyan1992/clientory-ai-visibility-skill.git
cd clientory-ai-visibility-skill

Codex

Install as a personal Codex skill:

mkdir -p ~/.codex/skills
ln -s "$(pwd)/skills/scan-ai-visibility" ~/.codex/skills/scan-ai-visibility

Restart Codex, then invoke $scan-ai-visibility or ask: “Check my law firm's AI visibility.”

Claude Code

Install as a personal Claude Code skill:

mkdir -p ~/.claude/skills
ln -s "$(pwd)/skills/scan-ai-visibility" ~/.claude/skills/scan-ai-visibility

Restart Claude Code, then invoke /scan-ai-visibility or ask Claude to run a law-firm AI visibility scan. For a project-only installation, copy or link the skill to .claude/skills/scan-ai-visibility.

Other AI agents

Point any Agent Skills-compatible tool at:

skills/scan-ai-visibility/SKILL.md

The YAML frontmatter describes when the skill should activate. AGENTS.md and llms.txt provide concise discovery context for other AI agents and crawlers.

Configure an API provider

Create a key with a supported provider, then save it privately from your own terminal. Never paste an API key into an AI conversation.

python3 skills/scan-ai-visibility/scripts/clientory_scan.py configure-key openai

Replace openai with anthropic, gemini, xai, perplexity, or openrouter. Input is hidden and saved to ~/.config/clientory/credentials.env with user-only permissions. Environment variables are also supported and override the saved file.

Official key pages: OpenAI, Anthropic, Gemini, xAI, Perplexity, and OpenRouter.

Inspect configuration without exposing key values:

python3 skills/scan-ai-visibility/scripts/clientory_scan.py providers

Optional model overrides: OPENAI_MODEL, ANTHROPIC_MODEL, GEMINI_MODEL, XAI_MODEL, PERPLEXITY_MODEL, and OPENROUTER_MODEL.

Example report

A completed scan answers questions such as:

• Which prompts mentioned the firm, and how many providers mentioned it?
• Where did the firm rank best and worst?
• Which provider had the strongest coverage?
• Which competing law firms appeared most often?
• Which services have no AI visibility?
• What evidence should the firm strengthen next?

Recommendations are derived from the scan's prompt, provider, quality, and competitor evidence. Each recommendation includes a priority, rationale, supporting evidence, concrete actions, and a measurable target for the next scan. They are guidance, not a guarantee of model rankings or legal-marketing outcomes.

Direct CLI usage

Most users should invoke the Agent Skill and follow its conversational workflow. The same guarded workflow is available directly:

python3 skills/scan-ai-visibility/scripts/clientory_scan.py validate-profile \
  --profile examples/profile.json

python3 skills/scan-ai-visibility/scripts/clientory_scan.py prepare-prompts \
  --profile examples/profile.json \
  --output ./clientory-prompts.json \
  --provider openai

# Review and approve clientory-prompts.json before continuing.
python3 skills/scan-ai-visibility/scripts/clientory_scan.py scan \
  --profile examples/profile.json \
  --prompts ./clientory-prompts.json \
  --output-dir ./clientory-report

Each paid command first prints a usage preview and exits. Rerun with --yes only after explicit approval.

Accuracy limitations

• API-model results do not exactly reproduce consumer applications such as ChatGPT or claude.ai.
• Search results and model recommendations can change over time.
• Extracted competitor names are candidates and should be checked against raw response evidence.
• A score is a comparative measurement for the tested prompts, providers, models, and date—not a universal ranking.
• This tool measures marketing visibility; it does not provide legal advice.

Development

The runner uses the Python standard library and requires no third-party runtime packages.

python3 -m unittest discover -s tests -v
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py \
  skills/scan-ai-visibility

License

Apache-2.0. See LICENSE.