entity-optimizer

# Entity Optimizer

Audits, builds, and maintains entity identity across search engines and AI systems. Entities — the people, organizations, products, and concepts that search engines and AI systems recognize as distinct things — are the foundation of how both Google and LLMs decide *what a brand is* and *whether to cite it*.

**Why entities matter for SEO + GEO:**

- **SEO**: Google's Knowledge Graph powers Knowledge Panels, rich results, and entity-based ranking signals. A well-defined entity earns SERP real estate.
- **GEO**: AI systems resolve queries to entities before generating answers. If an AI cannot identify an entity, it cannot cite it — no matter how good the content is.

## What This Skill Does

Audits entity presence across Knowledge Graph, Wikidata, Wikipedia, and AI systems; maps all 6 signal categories (47 signals); produces a gap analysis, building plan, and disambiguation strategy.

## Quick Start

Start with one of these prompts. Finish with a canonical entity profile and a handoff summary using the repository format in [Skill Contract](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md).

### Entity Audit

```
Audit entity presence for [brand/person/organization]
```

```
How well do search engines and AI systems recognize [entity name]?
```

### Build Entity Presence

```
Build entity presence for [new brand] in the [industry] space
```

```
Establish [person name] as a recognized expert in [topic]
```

### Fix Entity Issues

```
My Knowledge Panel shows incorrect information — fix entity signals for [entity]
```

```
AI systems confuse [my entity] with [other entity] — help me disambiguate
```

## Skill Contract

**Expected output**: an entity audit, a canonical entity profile, and a short handoff summary ready for `memory/entities/`.

- **Reads**: the entity name, primary domain, known profiles, topic associations, and prior brand context.
- **Writes**: a user-facing entity report plus a reusable profile that can be stored under `memory/entities/`.
- **Promotes**: canonical names, sameAs links, disambiguation notes, and entity gaps to `memory/hot-cache.md`, `memory/entities/`, and `memory/open-loops.md`.
- **Done when**: the 6 signal categories are each scored Pass/Fail/Partial, the AI-resolution test is run (or flagged as user-to-run), and a canonical profile plus top-5 priority actions are produced.

This skill is the sole writer of canonical entity profiles at `memory/entities/<name>.md`. Other skills write entity candidates to `memory/entities/candidates.md` only. When 3+ candidates accumulate, this skill should be recommended.

**Profile schema**: the frontmatter of every canonical entity profile follows the authoritative contract in [Entity-GEO Handoff Schema](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/entity-geo-handoff-schema.md). That schema defines which fields downstream skills (`geo-content-optimizer`, `schema-markup-generator`, `meta-tags-optimizer`, `ai-overview-recovery`) depend on. Do not omit required fields — the consumers will degrade gracefully to `DONE_WITH_CONCERNS` and surface an `open_loop` pointing back here.

- **Primary next skill**: use the `Next Best Skill` below once the entity truth is clear.

### Handoff Summary

> Emit the standard shape from [skill-contract.md §Handoff Summary Format](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/references/skill-contract.md).

## Data Sources

With tools: query Knowledge Graph API, ~~SEO tool, ~~AI monitor, ~~brand monitor. Without tools: ask the user for entity name/type, domain, profiles, topics, and disambiguation context. See [CONNECTORS.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/CONNECTORS.md).

**Zero-dependency local helper** (keyless): `python3 scripts/connectors/kg.py reconcile "<entity>"` resolves the name to a Wikidata QID with a confidence score (does the open KG that feeds Knowledge Panels & AI answers recognize it?); `kg.py entity <QID>` returns claims + sameAs. See [scripts/connectors/README.md](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/scripts/connectors/README.md).

## Decision Gates

**Stop and ask the user when:**
- No entity name is provided and none is inferable from project context — ask for the entity name and type before auditing.
- The entity is an individual (founder, author, public figure) who may be an EU/EEA/UK resident, before writing to `memory/entities/` — prompt: "You are about to create a canonical profile for a person. If this person is or may be an EU/EEA/UK resident, GDPR Art 6 requires a lawful basis: (1) consent, (2) legitimate interest, (3) contract, (4) other. For non-EU subjects, check local regimes (CCPA/CPRA, PIPEDA, LGPD, etc.). If unsure, skip and return NEEDS_INPUT." Only proceed once the user confirms a basis. Advisory only — not legal advice. Reference: [Memory Management — GDPR / Privacy Compliance](https://github.com/aaron-he-zhu/seo-geo-claude-skills/blob/main/cross-cutting/memory-management/SKILL.md).

**Continue silently (never stop for):**
- Missing ~~AI monitor or ~~knowledge graph tool access — mark those rows as user-to-run and proceed with user-provided observations.
- Individual signals being unknown — score them Partial with a verification action and continue.

## Instructions

When a user requests entity optimization:

### Step 1: Entity Discovery

Establish the entity's current state across all systems.

```markdown
### Entity Profile

**Entity Name**: [name]
**Entity Type**: [Person / Organization / Brand / Product / Creative Work / Event]
**Primary Domain**: [URL]
**Target Topics**: [topic 1, topic 2, topic 3]

#### Current Entity Presence

| Platform | Status | Details |
|----------|--------|---------|
| Google Knowledge Panel | ✅ Present / ❌ Absent / ⚠️ Incorrect | [details] |
| Wikidata | ✅ Listed / ❌ Not listed | [QID if exists] |
| Wikipedia | ✅ Article / ⚠️ Mentioned only / ❌ Absent | [no