agentleFS
Sign inStart free
butterbase-aibutterbase-ai/butterbase-skills/skills/journey-schema/SKILL.md

journey-schema

Skill535 starsChanged 5 months agoMITView on GitHub

Use as the schema build stage of the Butterbase journey, after journey-plan and journey-preflight. Implements the Tables section of 02-plan.md by delegating to schema-design, previewing the diff (manage_schema dry_run) and applying it (manage_schema apply). In hackathon_mode, also folds in the RLS stage by invoking journey-rls inline before returning.

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 0 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If docs/butterbase/03-preflight.md is missing, older than 24 hours, or 00-state.md has app_id: null, invoke …

    line 17
  2. Very specific:

    Refresh docs: Call butterbase_docs with topic: "schema".

    line 26
  3. Very specific:

    Read the Tables section of 02-plan.md.

    line 28
  4. Very specific:

    After it returns, optionally run a sanity manage_schema action: get and show the user the live shape.

    line 30
  5. Very specific:

    Hackathon mode only: if 00-state.md has hackathon_mode: true, also invoke butterbase-skills:journey-rls inline now.

    line 31

≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Journey: Schema

Stage 3a of the guided journey. Apply the declarative table definitions from the plan.

When to use

  • Dispatched by journey when current_stage: schema.
  • Directly via /butterbase-skills:journey-schema.

Preflight

If docs/butterbase/03-preflight.md is missing, older than 24 hours, or 00-state.md has app_id: null, invoke butterbase-skills:journey-preflight first. Wait for it to return successfully before proceeding.

Inputs

  • docs/butterbase/02-plan.md — the Tables section.
  • docs/butterbase/00-state.md — for app_id, hackathon_mode.

Procedure

  1. Refresh docs. Call butterbase_docs with topic: "schema". If the plan calls for advanced schema features (vectors, partial indexes, generated columns), also WebFetch https://docs.butterbase.ai/schema. Skip this step if docs/butterbase/03b-docs-cache.md was written less than 30 minutes ago and already covers schema.
  2. Read the Tables section of 02-plan.md. Print it back: "About to apply schema: <N tables>. Proceed?". Wait for yes.
  3. Invoke butterbase-skills:schema-design via the Skill tool, passing the Tables section and app_id. The wrapped skill will build the declarative schema, dry-run it with manage_schema action: dry_run, then apply with action: apply after user approval of the diff.
  4. After it returns, optionally run a sanity manage_schema action: get and show the user the live shape.
  5. Hackathon mode only: if 00-state.md has hackathon_mode: true, also invoke butterbase-skills:journey-rls inline now. After it returns, mark the rls checkbox as (folded) in 00-state.md rather than leaving it unchecked.
  6. Append one line to docs/butterbase/04-build-log.md (create if absent): <ISO timestamp> schema manage_schema ok
  7. Tick - [x] schema in 00-state.md, set current_stage: to the next unchecked stage (typically rls outside hackathon mode, otherwise the stage after rls), bump last_updated.
  8. Return to journey orchestrator (or, if invoked directly, ask: "Continue to the next stage? (yes/no)").

Outputs

  • Live schema in the Butterbase app.
  • One line in 04-build-log.md.
  • Updated 00-state.md.

Anti-patterns

  • ❌ Calling manage_schema action: apply without showing the user the dry-run diff.
  • ❌ Forgetting _drop: / _dropColumns: are needed for destructive changes — never set them without explicit user confirmation.
  • ❌ Forgetting the hackathon-mode RLS fold.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free