Initial commit: antigravity-claudekit

skills/ck-gkg/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: ck-gkg
+description: >
+  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.
+
+```bash
+# 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
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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