Skills reference

stos-setup

Triggers: User says "set up storytelleros", "connect my workspace", "configure STOS". Also fires when a stos_* tool returns 401 or the connector card shows "Connection has expired".

Walks the user through generating credentials, pasting them into Cowork, and verifying the connector is live. The go-to skill any time the tools stop responding.

• Tries calling a stos_* tool first; branches on three outcomes: data returned (skip ahead), 401 (refresh credentials), tool missing entirely (add the connector for the first time).
• Tells the user exactly which dashboard page to open and which Cowork dialog to click into. No guessing.
• After a successful re-auth, suggests pairing with Author Automations if they post to social.

getting-started

Triggers: User is new and asks "where do I start?", "what should I do first?", "help me get set up" — or Claude notices a nearly-empty account (no pen names, no books).

First-run coaching, one step at a time. Reads live setup readiness via stos_getting_started, then offers only the single most valuable next step — never the whole checklist.

• Calls stos_getting_started for readiness (pen names, books, AI keys, per-pen-name email senders, social link), tailored nextSteps, and task guides.
• Walks the first-run arc: pen name → first book (recommends the web app's 30-second ASIN import for published authors) → story bible → socials → email sending.
• Hands off to stos-setup for connector problems, story-bible for extraction, social-handoff for posting.

pen-names

Triggers: User mentions a specific pen name, has multiple pen names, or asks to switch identities. Phrases like "draft under my [pen name]", "switch to [pen name]", "log time for [pen name]", "list my pen names".

Discovers the user's pen names and tells Claude to pass the right penNameId on every subsequent scoped tool call.

• Calls stos_pen_names_list once to discover ids; matches the user's intent to a specific pen name.
• Reminds Claude that the penNameId argument is required on every call in a multi-step flow — it doesn't carry across automatically.
• Flags the brand-voice consequences: a cozy-mystery pen name's prose_guide and characters are different from a thriller pen name's.

quick-task-capture

Triggers: User says "remember to X", "I need to Y later", "add a todo", "capture this", "log a task". Also backs the /stos-task slash command.

One-shot todo capture. Extracts a short action-oriented title, drops it via stos_tasks_create, confirms back.

• Strips filler ("remember to", "I need to") so the saved title reads as an imperative.
• If the user named a pen name, scopes it; otherwise lets it land on the active pen name.
• Pairs with the tasks skill for review/filter/complete flows.

chapter-drafting

Triggers: User asks Claude to draft or revise prose. Phrases like "draft chapter 4", "write scene Y", "rewrite this chapter", "continue from where I left off".

The deep-writing flow. Reads pen-name voice + the title's existing chapters + relevant characters/locations/lore, then drafts in the right voice and saves on approval.

• Required reads before drafting: pen-name persona (prose_guide, prose_sample, words_to_use/avoid), prior chapters for continuity, characters and locations for the title.
• Always shows the draft to the user and waits for approval before stos_chapters_update.
• Has a revise mode (also reached via /stos-revise) — pulls existing text, applies feedback, preserves voice + continuity.

story-bible

Triggers: User asks for a full bible. Phrases like "generate a story bible", "build out the world of [title]", "extract characters from this manuscript".

Loops per-entity through characters → locations → events → lore for a title. NEVER batches.

• One stos_characters_create call per character, with every field populated. Same for locations, events, lore.
• After entities are saved, runs stos_worldbuilding_link once per association ("Sasha appears in chapter 3", "the Crow Court rules govern scene 7").
• Reports counts at the end ("saved 14 characters, 7 locations, 12 events, 5 lore, 38 associations") so the user can verify nothing was truncated.

worldbuilding

Triggers: User wants to add ONE entity, not a whole bible. Phrases like "add a character to [title]", "describe this place", "add a new lore entry".

Lighter cousin to story-bible. One entity at a time, with the full set of fields.

• Before creating, checks for duplicates via the matching _list tool.
• Drafts the full record (not a stub) and shows it for approval.
• Wires natural associations via stos_worldbuilding_link if the entity has obvious links ("she's in chapter 3").

time-tracking

Triggers: User wants to start, stop, or review writing time. Phrases like "start a writing timer", "stop the timer", "how long did I spend on [project]", "log my pomodoro".

Manages time-tracking entries, writing sessions, writing goals, and pomodoro settings.

• Start/stop wraps stos_time_tracking_start / _stop with the right pen name + title attribution.
• For "how much time did I spend on X" — sums (ended_at − started_at) deltas over stos_time_tracking_list.
• Touches pomodoro_settings + writing_goals when the user references them.

finance

Triggers: User says "log an expense", "I got royalties of $X", "what did I spend on editing", "add a vendor", "how much did I make from [title]".

Vendors + transactions + summaries. Never speaks developer jargon back to the user.

• Always searches stos_vendors_list before creating a new vendor to avoid duplicates.
• For reviews, uses stos_finance_summary with the right groupBy (category / book / vendor / pen_name / type) over the right range.
• Strips programmer vocabulary — says "expense", "income", "vendor", never "transaction record" or "row".

calendar

Triggers: User mentions a real-world date. Phrases like "add to my calendar", "what's on my calendar [date]", "block out [date] for [thing]".

Real-world calendar events — release dates, signings, deadlines. Distinct from story-timeline events.

• Always asks (or infers) which calendar to use when the user has multiple.
• Distinguishes itself from the timeline skill: if the user said "story event" or referenced an in-universe date, hands off there instead.

timeline

Triggers: User wants to manage IN-UNIVERSE story events. Phrases like "add a story event", "when does the war start in [title]", "what's the canon timeline".

Story-timeline events (events table — the worldbuilding one). Distinct from calendar.

• event_date is free text because in-universe dates often don't map to real calendars ("Year 1187, Hightide Moon").
• On creation, wires scene/character/location links so the event is findable in context later.

tasks

Triggers: User wants to review, prioritize, complete, or manage existing tasks. Phrases like "what's on my task list", "show me high-priority tasks", "what's due this week", "mark [task] done".

Full task management beyond quick-capture. Filter by status/priority/scope; complete via the _complete sugar tool.

• Surfaces a focus view (top 5–10 by priority + due_date) rather than dumping the whole list.
• Always asks before marking a task done if the user phrased it ambiguously.
• For one-shot adds, defers to quick-task-capture.

manuscript-revisions

Triggers: User mentions manuscript files. Phrases like "show me my manuscript versions", "I just uploaded a new draft", "switch to the [name] revision".

List / register / set-active / annotate manuscript file revisions for a title.

• Each revision lives in Supabase Storage and carries its own display name + notes — re-uploads don't silently overwrite the previous draft.
• set-active mirrors the storage_path onto the parent title so legacy callers + the in-app editor see the new file.
• Delete removes the DB row but NOT the underlying storage file (kept for recovery).

sales-studio

Triggers: User wants to manage retailers, retailer links, title variations (ebook/paperback/audiobook), marketing assets, products, or reviews. Phrases like "add Amazon link for [title]", "create a paperback variation", "list reviews for [title]".

Sales-side data — retailers, variations, links, marketing assets, products, reviews.

• Variation-first ordering: ebook/paperback/audiobook is the join point, so a retailer link without a variation is orphaned.
• Matches Amazon URLs to the right variation type (Kindle URL → ebook, not paperback).

marketing-studio

Triggers: User wants to manage email lists, contacts, tags, campaigns, articles, FAQs, or webinars. EXCLUDES social — social work routes to social-handoff.

Email + article + FAQ + webinar workflows. Email-campaign send is plumbed but currently returns 503 (engine still in stub status).

• Never calls a stos social tool — there isn't one and there won't be.
• For "send to all my subscribers", surfaces the list size first as a sanity check.

social-handoff

Triggers: User mentions ANY social verb — post, schedule, campaign, publish to Instagram/TikTok/Threads/YouTube/etc. Always routes to the Author Automations plugin.

Reads the pen name's aaProfileId and routes the call to aa_* tools. Refuses to call stos endpoints for social work.

• Guards: if aaProfileId is null, stops and tells the user to provision the pen name in Author Automations first; if aaUnreachableSince is set, warns about reconnecting.
• Surfaces STOS context (title, persona, brand voice) to the AA tool — looks up title or pen-name details first, then passes the relevant strings to aa_create_post / aa_create_campaign.
• There is no stos_social_* tool by design. Hard rule.