GHOST

SQLite migration rules for the Ghost codebase. MUST READ before writing or modifying any file in migrations/. Covers: table recreation patterns, column ordering, CHECK constraint changes, NOT NULL safety, and the validation checklist. A faulty migration that ships breaks the production daemon on startup with no recovery path short of manual DB surgery — these rules are non-negotiable.

Read when you need to browse, traverse, or query the knowledge system beyond basic knowledge_search — graph traversal, tag exploration, orphan detection, reference browsing, topic listing, or direct SQL access.

Import and update external content in the knowledge base — git repos, web crawls, documents (PDF, DOCX), and books (EPUB). Use when the OPERATOR wants persistent, searchable reference material from a git repository, website, document, or book, or when existing references may be stale and need refreshing.

Ghost's Lua scripting layer internals. MUST READ before modifying anything in src/scripting/, prompts/stdlib/, prompts/agents/*/agent.lua, or agent hook logic. Covers: ScriptHost VM lifecycle, sandbox, host globals, ctx bindings, nudge library, template module, custom tools, type stubs, and the PreTurnState contract.

Use when reading or changing GHOST configuration (providers, models, timing, compaction, services, any config.toml key), adding or switching LLM providers, answering questions about GHOST's own features or capabilities, a CLI tool is missing or "not found", services need starting/stopping/debugging, updating GHOST to a newer version, managing the Nix shell environment, or troubleshooting GHOST setup.

Triage and fix issues reported via Ghost's /feedback command. MUST READ when the user points you to a feedback folder, mentions a feedback report, or asks you to investigate a bug that happened during a GHOST session. Covers: retrieving feedback from remote servers, reading transcripts and debug request dumps, root-cause categorization, and the fix workflow.

Read before first use of the browser tool in a session. Covers browser selection workflow (list → pick → connect), when to use headless vs operator browser, how to guide the OPERATOR to expose their browser with `ghost browsers serve`, tab management, element refs, and web_fetch session sharing.

Tracing, observability, and instrumentation conventions for the Ghost codebase. MUST READ before adding or modifying: tracing spans, #[tracing::instrument] attributes, tracing::info_span!() calls, OTel semantic convention fields (gen_ai.*), span hierarchy, or any observability-related code. Failure to follow these conventions produces inconsistent telemetry.

Create new skills, modify and improve existing skills, and measure skill performance. Use when the OPERATOR wants to create a skill from scratch, edit or optimize an existing skill, run evals to test a skill, or benchmark skill performance with variance analysis.

Read when the OPERATOR asks a question that will require web research across multiple sources — recommendations, comparisons, evaluations, multi-factor decisions, "what should I buy/use", or any question where you'd need to read several web pages. This skill decides whether to spawn a background research agent (to protect your context from heavy fetching) or handle it yourself. Do NOT read for simple factual lookups or questions fully answered by your knowledge base.

Use when executing implementation plans with independent tasks in the current session. Dispatch a fresh subagent per task, with two-stage review after each — spec compliance review first, then code quality review. Keeps context clean and quality high.

Read before creating or updating knowledge notes with note_write. Covers mandatory conventions — truth principle, archetypes, titles, typed linking, tags, trust scores, evidence bar, consolidation, and archival. Skip for diary entries and simple file writes.

Create spawnable Lua agents coupled with skills. Use when you need to create an autonomous agent that achieves a specific task. Also use when the OPERATOR wants a reusable background agent.

Use when you have a spec or requirements for a multi-step task, before touching code. Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste.

Manage coding sessions. Use when the OPERATOR asks to work on code, hack on a repo, implement features, fix bugs, or do any development work in a codebase.

Generate or edit images with Nano Banana 2 (Gemini 3.1 Flash Image). Use for any image create/modify requests. Supports text-to-image + image-to-image; 1K/2K/4K resolutions.

Create, manage, and organize projects — persistent cross-session task containers for long-horizon work. Also read when the OPERATOR describes an ambition or goal that will span multiple sessions ("I want to build X", "I want to learn Y from scratch", "help me create Z") — offer to create a project to track progress. Covers CLI commands, file structure, workflow, and when to create or archive.

Use when the OPERATOR asks a question that needs code to answer — data processing, CSV/JSON parsing, API calls, domain lookups, web scraping, calculations, or anything beyond a single coreutils command. MUST READ before writing any Python or running python/python3 commands.

Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies.

Use when completing tasks, implementing major features, or before merging to verify work meets requirements

Step-based stepwise test design, implementation, and iteration for Ghost. Use this skill when creating, rewriting, reviewing, or debugging stepwise tests that chain fixtures across steps, use LiveTestEnv snapshots, run sequentially, or compare behavior across model aliases. Also covers daemon-boot e2e tests. Covers: tests/stepwise harness layout, hard-fail predecessor fixtures, transcript/metrics artifacts, interactive scripts/e2e tooling, and the iteration workflow when tests fail.

Use when you need to send an image, generated file, CSV, or any attachment to the OPERATOR.

You MUST use this before any creative work — creating features, building components, adding functionality, or modifying behavior. Explores the OPERATOR's intent, requirements, and design before implementation.

Use when you have a written implementation plan to execute in a separate session with review checkpoints. Load plan, review critically, execute tasks in batches, and report for review between batches.

Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup

Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification

Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation

Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes

Use when implementing any feature or bugfix, before writing implementation code. Write the test first. Watch it fail. Write minimal code to pass.

Use when about to claim work is complete, fixed, or passing, before committing or creating PRs. Requires running verification commands and confirming output before making any success claims. Evidence before assertions, always.

Use when creating new skills, editing existing skills, or verifying skills work before deployment

Documentation conventions for Ghost's user-facing docs site (Astro Starlight). MUST READ before creating or updating any page under docs/, modifying CLI help text, or changing user-facing behavior that needs documentation. Covers which doc file to update for each change type, build verification, formatting, and terminology rules.

Test conventions, harness API, and readability rules for the Ghost codebase. MUST READ before writing or modifying any test — unit tests, integration tests, or live tests. Covers: test helper functions (test_config, test_workspace, test_database), MockProvider, LiveTestEnv, live test isolation rules, and the non-negotiable readability requirements. For step-based end-to-end tests, also read the `e2e-testing` skill. Failure to read this will produce duplicated boilerplate and broken test isolation.

Self-documentation for Claude Code. MUST READ after implementing complex features, making structural changes, or learning non-obvious patterns that would be useful in future sessions. Covers: when to create or update .agents/skills/ files, what belongs in a skill vs CLAUDE.md vs auto-memory, the skill file format, and the maintenance checklist to run before finishing work.

Writing and running Python code with uv inline scripts. MUST READ every time you need to run ANY Python code, process JSON/data, execute multi-line shell logic, or feel tempted to use python3 -c, jq, awk, or long bash pipes. ALWAYS search existing scripts first (ls scripts/) and extend one before writing new. Covers: inline dependency declarations, script placement, discoverability.