amateur-astronomy-observation-advisor-agent-skill

Amateur Astronomy Observation Planning Advisor

A production-grade Claude Skill for planning amateur telescope observation sessions, grounded in established observational-astronomy methodology and shipping real, deterministic computational tools.

Category: Amateur Astronomy / Observational Science Status: Complete and runnable. Self-validating (python -m scripts.validate_skill) and skill-creator-valid (quick_validate.py).

Overview

A skill supporting amateur astronomers in planning telescope observation sessions. It operationalizes six named methodologies into concrete reference files, deterministic Python tools, JSON-Schema-validated outputs, and lifecycle hooks:

• Telescope optical-design trade-off framework (refractor / reflector / catadioptric; aperture-focal-length theory)
• Antoniadi/Pickering seeing scales + Bortle Dark-Sky Scale for sky-condition assessment
• Four-axis target-selection strategy with a composite suitability score (object type, sky position, moon phase, equipment match)
• Astrophotography stacking/exposure theory (SNR optimization, swamp-the-read-noise rule)
• Collimation and optical-performance evaluation (star testing)
• AAVSO-style citizen-science observation logging

Architecture

A modular skill registry with a chain-of-thought router in SKILL.md that classifies the user intent, loads exactly one domain reference, invokes the matching deterministic tool, and assembles a structured, schema-validated answer. Lifecycle hooks enforce pre-validation, guardrails, formatting, and graceful fallback. See assets/diagrams/skill_architecture.md for the full flow diagram.

amateur-astronomy-observation-advisor/
+-- SKILL.md                  # chain-of-thought router + tool registry + hooks
+-- references/               # domain knowledge (load on demand)
+-- scripts/                  # deterministic tools (real, executable Python)
+-- assets/
|   +-- schemas/              # JSON Schemas for every structured output
|   +-- templates/            # Markdown templates + pre-flight checklist
|   +-- diagrams/             # architecture diagram
+-- config/                   # type-safe config (schema + defaults + env overrides)
+-- evals/                    # test prompts and sample requests

Core capabilities

• Equipment-selection guidance (telescope aperture/focal-length trade-offs, mount types, eyepiece selection) via a weighted MCDA model
• Atmospheric-seeing (Antoniadi/Pickering) and transparency assessment for session planning
• Dark-sky / light-pollution assessment (Bortle scale) for site selection
• Target-selection strategy by object type, sky position, moon phase, and equipment
• Basic astrophotography technical guidance (exposure/stacking SNR, guiding, calibration frames)
• Collimation and telescope-maintenance principles (star testing)
• Observation-log / record-keeping methodology (AAVSO-style)

Tools (scripts/)

All tools are real, side-effect-free, and have JSON input schemas invokable through scripts/tool_registry.py:

Run python -m scripts.tool_registry --list, --schema <tool>, or --run <tool> --args '<json>'.

Quick start

# Self-validate the whole skill
python -m scripts.validate_skill

# Generate a session plan from a request
python -m scripts.observation_plan_generator --request evals/sample_request.json

# Quick tool calls
python -m scripts.moon_phase --date 2026-08-10T21:00:00
python -m scripts.bortle_estimator --nelm 6.5
python -m scripts.magnification_calc --aperture 203 --focal 1200 --eyepieces 25,14,9
python -m scripts.exposure_stack_calc --signal-rate 5 --sky-rate 80 --read-noise 2.5 --sub 60 --target-snr 50

# Run the full test suite (stdlib unittest, 61 tests)
python -m unittest discover -s tests -p "test_*.py" -v

# End-to-end smoke demo of every tool
python -m scripts.run_demo

Configuration

Defaults and feature flags live in config/default_config.json, validated against config/config.schema.json. Override any value with ASTRO_-prefixed environment variables (see config/README.md).

Project files

Knowledge provenance

Methodologies are distilled from the curated sources in SECOND-BRAIN-KNOWLEDGE-PAPER.md (Sherrod & Koed; Covington; Antoniadi; Pickering; Bortle; Berry & Burnell; Suiter; O'Meara; Harrington; Dickinson; AAVSO; et al.). The skill applies their operational principles rather than citing them as a flat reading list.

License

Provided as open-source under the MIT License (see LICENSE).