astro-companion - SKILL.md Agent Skill

name: astro-companion description: "Millionaires study markets, billionaires study stars" - AI astrology companion with timing guidance, natal analysis, and cosmic calendar integration. aliases: - oracle triggers: "oracle, astrology, horoscope, birth chart, moon phase, mercury retrograde, transits, timing, cosmic, planetary, sign, rising, synastry, solar return, zodiac, natal, celestial, vibe, alignment, conjunction, retrograde, when should I, best day, best time, schedule around, tarot, numerology, chakra, harmonic"

Astro Companion — Operating Skill

Use this skill when the user asks for life guidance, timing advice, natal chart analysis, transit readings, calendar scheduling around planetary alignments, tarot, numerology, chakra, or any astrology-related query.

1. Runtime Paths

What	Path
Oracle env file	`~/.hermes/oracle/.env`
Profiles registry	`~/.hermes/oracle/profiles.json`
Per-user profile	`~/.hermes/oracle/profiles/<id>/profile.json`
Per-user consent	`~/.hermes/oracle/profiles/<id>/consent.yaml`
Browser star map	`~/.hermes/skills/oracle/astro-companion/ui/oracle_chart.html`

2. Startup Rules

On Oracle entry:

Load ~/.hermes/oracle/profiles.json
Get active profile
Use cached data if available - never fetch from API if data is already cached
Offer menu options

3. Caching (CRITICAL)

All Astrovisor data is cached. natal-mcp is preferred for transits (local, free).

Cache Locations

Data Type	Location	TTL
Full natal data	`profiles.json`	Forever
Transits	`profiles/<id>/cache/transits_YYYY-MM-DD.json`	1 hour
Solar returns	`profiles.json`	1 year
Numerology	`profiles.json`	1 year
Tarot	No cache (different each pull)	-

Cache Precedence

Check cache first - never hit API if data exists
Use natal-mcp for transits (local, no API cost)
Astrovisor for everything else

# Transits use cache + natal-mcp
get_transits_with_cache(datetime, lat, lon, location, tz)

# Other data uses profiles.json cache
cached_data = profiles['profiles'][0]['cached_data']

4. Astrovisor API Endpoints

Base URL: https://astrovisor.io Token: from ~/.hermes/oracle/.env (ASTROVISOR_TOKEN)

Natal & Core

Endpoint	Purpose
`POST /api/natal/chart`	Full natal chart (planets, houses, aspects, analysis)
`POST /api/natal/aspects`	Major aspects between planets
`POST /api/minor-aspects/calculate`	Minor aspects (quintile, septile, etc.)
`POST /api/harmonics/calculate`	Harmonic charts reveal hidden patterns

Solar Returns & Predictions

Endpoint	Purpose
`POST /api/solar/return`	Solar return for a year
`POST /api/solar/all-planetary-returns`	Saturn, Jupiter, etc returns
`POST /api/solar/profections`	Annual house profections
`POST /api/solar/lunations-overlay`	New/Full Moons mapped to SR houses
`POST /api/calendar/generate`	Daily predictions (background job)

Transits & Timing

Endpoint	Purpose
`POST /api/transits/calculate`	Current transits to natal chart

Numerology & Chakra

Endpoint	Purpose
`POST /api/numerology/calculate`	Life path, personal year, Pythagorean square
`POST /api/medical/chakra-analysis`	7-chakra energetic profile

Tarot

Endpoint	Purpose
`GET /api/tarot/divination/daily`	Card of the day
`GET /api/tarot/divination/single`	Random single card
`POST /api/tarot/divination/spread`	Multi-card spread

Standard Payload

{
  "name": "Shane",
  "datetime": "1991-08-21T16:20:00-04:00",
  "latitude": 41.4489,
  "longitude": -82.708,
  "location": "Sandusky, Ohio, USA",
  "timezone": "America/New_York",
  "house_system": "P"
}

5. Menu Options

AstroVisor - Calendar Review — Your schedule through the stars
Daily brief — Full cosmic weather for today
Weekly outlook — Best days for launches, relationships, communication, finances
Natal deep-dive — Your full birth chart analysis
Timing question — When to launch/sign/schedule/post
Tarot pull — Daily card OR 3-card spread (Past/Present/Future) - clarify which they want
Solar Returns — Year-ahead themes, house focus, key dates
Numerology — Life path, personal year, key numbers
Chakra analysis — 7-chakra energetic profile (cached, only hits API on request)
Help & About — Commands, features, engineering docs

Oracle Star Map: file:///Users/sc/.hermes/skills/oracle/astro-companion/ui/oracle_chart.html

6. natal-mcp Fallback

If Astrovisor rate-limits (429), use natal-mcp MCP server if configured.

natal-mcp provides: create_natal_chart, create_transit_chart, create_solar_return_chart

When user asks for Tarot, clarify:

"Would you like a daily card for guidance today, or a 3-card spread (Past/Present/Future) for deeper clarity?"

7. Safety Rules

Never present astrology as deterministic fact
Never diagnose medical/psychological conditions
If birth time unknown, lower certainty
Retrogrades = revision, not panic

8. Scripts

Script	Purpose
oracle_utils.py	API helpers, menu, cache helpers
oracle_astrology.py	Astrovisor calls
oracle_digest.py	Daily/weekly briefs
oracle_render.py	Terminal charts
oracle_launcher.py	Entry flow

Full docs: see references/ directory