init_skill

Overview

This skill initializes warehouse schema discovery and generates a team-editable reference at .astro/warehouse.md for instant lookups. Run it once per project and refresh when the schema or codebase context changes. It produces a version-controllable snapshot that combines warehouse metadata with code-derived descriptions and useful warnings.

How this skill works

The skill reads the local warehouse configuration to get databases to inspect, then launches parallel discovery tasks—one per database—to enumerate schemas, tables, columns, and row counts. In parallel it scans the codebase (dbt yml, declarative SQL frontmatter, AGENTS/CLAUDE docs) to extract table and column descriptions, primary keys, and business context. Results are merged into .astro/warehouse.md (or ~/.astro/agents/warehouse.md with --global), with quick reference mappings, categorical value families, large-table warnings, and an option to append a Quick Reference to CLAUDE.md.

When to use it

• Initial project setup to enable fast concept→table lookups without querying the warehouse.
• After schema changes: tables added, removed, renamed, or column types changed.
• Before onboarding analysts so they have a single source of truth for table metadata.
• When preparing dashboards or metrics to identify large tables and key columns.
• When you want to enrich warehouse metadata with descriptions from dbt and SQL files.

Best practices

• Run /data:init once to create .astro/warehouse.md, then use /data:init --refresh after schema or code changes.
• Commit .astro/warehouse.md to version control so team edits and context are preserved.
• Choose --global only for multi-project agents that need a shared warehouse reference.
• Review and add business context to the Quick Reference table; the refresh preserves user edits.
• Use the pre-populated concept cache (concept import/learn) to speed up agent lookups.

Example use cases

• Generate a searchable, versioned schema reference during project bootstrapping.
• Detect and flag tables >100M rows so analysts remember to apply date filters.
• Pre-populate concept→table mappings to improve agent accuracy for complex queries.
• Discover categorical value families for common filter columns (STATUS, TYPE, OPERATOR).
• Append Quick Reference to CLAUDE.md so model mappings are available in conversational contexts.