antigravity-claudekit/skills/ck-gkg/SKILL.md

name, description

name	description
ck-gkg	Queries and explores Google Knowledge Graph for entity information and relationships. Activate when user says 'look up entity', 'knowledge graph search', 'get entity details', 'find information about a person or organization', or 'Google Knowledge Graph'. Accepts entity names, types, and relationship queries.

Overview

Interfaces with the Google Knowledge Graph Search API to retrieve structured entity data including descriptions, types, images, and related entities for people, places, organizations, and concepts.

When to Use

• Retrieving structured factual data about a named entity (person, org, place, concept)
• Enriching application data with authoritative entity metadata
• Verifying entity existence and canonical identifiers (MID)
• Building entity-linked features (auto-complete, entity cards, disambiguation)
• Cross-referencing entities across data sources using Knowledge Graph IDs

Don't Use When

• Task needs real-time news or current events (Knowledge Graph has limited freshness)
• Searching for web pages rather than entities (use a web search API)
• Querying proprietary or internal data — KG only covers public knowledge
• Deep relationship traversal across many hops (use a graph database instead)

Steps / Instructions

1. Set Up API Access

Required: Google Cloud project with Knowledge Graph Search API enabled.

# Environment variable (never hardcode)
export GOOGLE_API_KEY="your-key-here"

Enable API in Google Cloud Console:

APIs & Services → Library → Knowledge Graph Search API → Enable

2. Basic Entity Search

import requests
import os

def search_knowledge_graph(query: str, types: list[str] | None = None, limit: int = 5):
    url = "https://kgsearch.googleapis.com/v1/entities:search"
    params = {
        "query": query,
        "key": os.environ["GOOGLE_API_KEY"],
        "limit": limit,
        "indent": True,
    }
    if types:
        params["types"] = types  # e.g., ["Person", "Organization"]

    response = requests.get(url, params=params)
    response.raise_for_status()
    return response.json()

# Usage
results = search_knowledge_graph("Python programming language", types=["SoftwareApplication"])

3. Parse the Response

def extract_entities(kg_response: dict) -> list[dict]:
    entities = []
    for item in kg_response.get("itemListElement", []):
        result = item.get("result", {})
        entities.append({
            "name": result.get("name"),
            "description": result.get("description"),
            "detailed_description": result.get("detailedDescription", {}).get("articleBody"),
            "types": result.get("@type", []),
            "mid": result.get("@id"),           # Google MID: /m/05z1_
            "url": result.get("url"),
            "image": result.get("image", {}).get("url"),
            "score": item.get("resultScore"),
        })
    return entities

4. Entity Type Filters

Common KG entity types:

Person          — individuals, public figures
Organization    — companies, nonprofits, governments
Place           — cities, countries, landmarks
Event           — historical or recurring events
CreativeWork    — books, films, music, software
Thing           — generic fallback type

5. Handle Multi-Entity Disambiguation

def disambiguate_entity(name: str, context_hint: str) -> dict | None:
    results = search_knowledge_graph(name, limit=10)
    entities = extract_entities(results)

    # Score by context relevance
    for entity in entities:
        desc = (entity.get("description") or "").lower()
        if context_hint.lower() in desc:
            return entity

    # Fall back to highest-scored result
    return entities[0] if entities else None

6. Rate Limits and Caching

• Free tier: 100,000 requests/day
• Cache responses for repeated entity lookups
• Use MID as cache key for stable entity references

from functools import lru_cache

@lru_cache(maxsize=500)
def cached_entity_lookup(query: str) -> str:
    results = search_knowledge_graph(query, limit=1)
    return str(results)

Notes

• API key must be restricted to Knowledge Graph API in Google Cloud Console
• MID identifiers are stable — use them for entity cross-referencing
• Knowledge Graph data is Wikipedia/Wikidata-sourced; verify critical facts
• Response scores are relative within a single query, not absolute quality metrics