20: Snippet Gallery and Prompts - transcript
Jessica: The QUILL Cast, episode twenty. I'm Jessica. Today we dig into two related inventory tools, the snippet gallery you build for yourself, and the prompt gallery that drives every AI action. They feel different in the menu, but they share a single design idea, named text you can recall by intention. Once you see them side by side, the rest of the AI arc falls into place.
Liam: I'm Liam. But first, an honest correction, because the show notes for this episode said we'd recap last week's files-everywhere episode, and that's not what just aired. Episode nineteen on disk is the text-supply toolkit, the Copy Tray, snippets, abbreviations, and macros. The files-everywhere episode, with F T P and S F T P and S S H and GitHub, lives at episode twenty-five on disk. So the recap I owe you is the one that actually played, the four tools that bring words to your cursor instead of making you fetch them by hand.
Jessica: And it is the perfect bridge into today. Snippets and abbreviations are the two halves of the same idea. Abbreviations are the auto siblings, you type a shorthand and the long form appears as you type, no keypress, no ceremony. Snippets are the deliberate siblings, you type a trigger and press a chord, and a whole structured block lands, placeholders and all. We covered snippets as a workflow in episode nineteen. Today we go under the hood, look at the actual file format, the placeholder grammar, the starter packs, and the gallery you did not know you had.
Liam: And then we cross the bridge to the AI side, the prompt library, the Quillin-contributed prompts, the dot p q p pack format, and the Promote continuum that turns a one-line prompt into a multi-step skill, and a multi-step skill into an autonomous agent. Two galleries, one philosophy, name it, version it, share it, and you will use it more.
Jessica: Before we go any further, here is your first do-this-now beat, and I mean literally now. Pause the audio. Open QUILL, create a fresh empty document, and go to the Insert menu, then Manage Snippets, and choose Create snippet. Name it something simple like test, set the trigger to a semicolon followed by the word test, and put just a few characters of body, the words hello world, then a dollar sign, curly brace, the word cursor, close curly brace. Save it. Come back when the new snippet dialog is closed and the snippet exists in your library. That is the smallest valid snippet you can write, and once it is in your library the rest of today's episode will make a lot more sense.
Liam: The reason that exercise matters is the structure. A snippet is a small bundle of five fields, and once you have built one you have touched all of them. There is a name, what you call it in the manager. There is a trigger, the short string you type to summon it. There is a body, the text that gets inserted. There is a description, a one-liner that shows up in tooltips and search results. And there is a tags list, optional labels for filtering. The data class in quill-core-snippets also tracks an enabled flag and a source, which can be user, starter-pack, or quillin, but you do not set those by hand, the manager and the gallery set them for you.
Jessica: The storage is delightfully boring. Every snippet you create goes into a single JSON file under your QUILL application data directory, in a snippets subfolder, named snippets.json. The file is written atomically, so a crash during save can never leave you with a half-written library. The path is exposed by snippet-library-path, the read by load-snippet-library, the write by save-snippet-library. We verified it. There is no database, no cloud sync, no hidden sidecar. Your snippets, your file, your machine.
Liam: The interesting part is the placeholder grammar inside the body, and there are exactly five kinds. Type a dollar sign, open curly brace, the word cursor, close curly brace, and that is the cursor marker. It is the place your caret will land after the snippet is inserted. If you forget to put one in, the caret just goes to the end of the inserted text, which is fine, but the whole point of snippets is to put your cursor exactly where you start typing the next thing. Put cursor in your snippet, and you do not have to arrow down or click.
Jessica: Kind two is the input prompt. Dollar sign, curly brace, the word input, a colon, then a name, close curly brace. The example from the developer flow starter pack, body says input colon summary, and when you insert that snippet, a dialog pops up labeled Value for summary, you type, you press Enter, the answer lands in the document. The name is whatever you put after the colon, and it appears in the dialog title so a screen reader announces the field by name. That is a quiet accessibility win, the field has a label, the label is in the dialog title, you always know what you are filling in.
Liam: Kind three is the choice prompt. Same shape, but the word is choice, and after the colon you put pipe-separated options. From the support-and-accessibility starter pack, the body has choice colon N V D A pipe J A W S pipe Narrator, and when you insert the snippet, a dropdown appears with those three screen readers as choices. Pick one, it lands. The choice placeholder also accepts the word name as an alias for input, so dollar-sign-curly-brace-name-colon-whatever-close is treated the same as input, that is in the code in extract-placeholders.
Jessica: Kind four and five are the automatic ones. Dollar sign, curly brace, the word date, close curly brace, gives you today's date as Y Y Y Y dash M M dash D D. Dollar sign, curly brace, the word time, close curly brace, gives you the current time as H H colon M M. They evaluate at insert time, not at save time, so a snippet that contains date will stamp the day you inserted it, not the day you wrote it. That is a really important distinction, and it is the kind of thing you only learn by inserting a date snippet on Monday and then opening the file on Friday.
Liam: And if you put a placeholder in your body that QUILL does not recognize at all, no leading kind, no colon, just a bare word in the braces, the code does the helpful thing, it treats it as an input prompt with that word as the name. So a typo or a hand-rolled placeholder still works, it just asks. We like that, it means you can build a snippet by feel, and QUILL will fill in the gaps.
Jessica: One more thing about the placeholder engine that the docs barely mention. Every input and choice placeholder is collected by name before any rendering happens, so the dialog presents them in the order they first appear in the body, and it stops at the first one that needs a value. Fill in the answer, the value is substituted, and the next placeholder in line is offered. That is why a multi-field snippet feels like a short conversation rather than a flurry of overlapping popups. The design is a small kindness to screen-reader users in particular, because the dialog does not stack, it queues.
Liam: And here is the feature most people miss, the smart trigger. We read the code in main-frame, the function is expand-snippet-trigger-if-match. The behavior is simple and surprising. You are typing in a document. You type your snippet's trigger, starting with a semicolon, and then you press a delimiter, a space, a tab, a period, a comma, a semicolon, a colon, an exclamation mark, a question mark, a closing parenthesis, a closing bracket, or a closing curly brace. At that exact moment, the editor looks back at the token, finds the matching snippet, and expands it inline. You did not press a chord, you did not open a menu, you just typed.
Jessica: That is the abbreviation-style magic from last episode, applied to snippets. A trigger like semicolon journal followed by a space, and the entire journal header lands, date and cursor included. A trigger like semicolon meeting followed by a colon, and the meeting notes scaffold expands. The only thing you have to do to enable it is make sure the setting snippet-trigger-expansion is on in your settings, which is the default.
Liam: This also means the chord QUILL key then S, and the menu item Insert, Insert Snippet, are the deliberate path. The smart trigger is the automatic path. The same snippet library powers both. You choose, depending on your mood, your muscle memory, and whether you want to see the picker first. Two doors, one room.
Jessica: Let us take a walk through the actual starter packs, because they are a free lunch and most people never open the box. There are three. Daily-writing gives you a journal header, triggered by semicolon journal, and a meeting notes template, triggered by semicolon meeting. Developer-flow gives you a bug report template, triggered by semicolon bug, and a conventional commit message helper, triggered by semicolon commit. Support-and-accessibility gives you the screen reader Q A checklist, triggered by semicolon S R Q A, with choice prompts for the screen reader and the pass or needs-follow-up verdict. Five snippets total, all installed from the same dialog.
Liam: The way you install them is part of the design, and I think it is the right way. You go to Insert, Manage Snippets, pick Install starter snippet packs, and the manager reads the pack names from the code, sorts them alphabetically, and offers you a chooser. Pick one, the snippets are merged into your library by id, which means a re-install is a no-op, it will not duplicate. If a starter snippet already exists in your library, your version wins. The starter pack is the floor, not the ceiling.
Jessica: The starter pack loader is its own small bit of code, merge-starter-pack, and the interesting line is setdefault, which is Python for only-add-if-not-already-present. We verified it, in quill-core-snippets at line 202. So the safety property is real, you cannot accidentally end up with two copies of a semicolon journal snippet by clicking Install twice in a row. And the installed snippets are tagged with source equal to starter-pack, so later, when you are scrolling your library, you can tell at a glance which ones came from QUILL and which ones are yours.
Liam: Now here is the part the docs almost never explain, and I think it is the most useful thing in this whole episode. There are two snippet-related menu items, and they are not the same. The first is Insert, Insert Snippet, the chord is QUILL key then S, and that one is for the snippets you wrote, your library. The second is Insert, Snippet Gallery, and that one is for snippets that Quillins, the bundled extensions, contribute into a separate gallery. Different source, different storage, different dialog.
Jessica: The Quillin gallery is read-only from your perspective, you browse, you preview, you insert, but you do not edit. The contribution mechanism is a small bit of metadata that each Quillin can ship, and the gallery dialog is built in main-frame. The title of that dialog is literally Snippet Gallery, it lists entries by name with the contributing Quillin in parentheses, and on Insert it applies the snippet body to your cursor. If a Quillin did not contribute any gallery snippets, the dialog does not even open, you get a status message, no gallery snippets are available.
Liam: So the rule of thumb: you write, in Insert, Manage Snippets. You summon one of your own, with QUILL then S, or from Insert, Insert Snippet. You browse what the bundled extensions have to offer, from Insert, Snippet Gallery. The two have separate storage, separate commands, separate dialogs, but they all insert text the same way, through the same placeholder engine. That is why we are covering them in one episode, they are siblings.
Jessica: One honest correction here. The show notes for this episode, and some older internal docs, mention the snippet gallery living under a Power menu. The current code does not have a Power menu in the main menu bar. The gallery lives under Insert, alongside Insert Snippet and Manage Snippets. If you remember a Power menu, you are not wrong, it existed in an earlier design, the menu surface was simplified. We are calling it out because if you ever hunt the menu by memory, you should hunt the right one.
Liam: Now we cross the bridge. The AI side has its own library, and we are going to be honest with you about a small but real drift between the show notes and the code. The brief for this episode said we would look at quill-core-ai-prompts, but that file does not exist. The actual prompt module is quill-core-prompt-library, and that is where we are pulling every claim from. If you ever see a reference to prompts.py, it is stale, the real home is prompt-library.py.
Jessica: And once we are over the bridge, the parallel is striking. The prompt library is the inventory of named instructions you can apply to text, the snippet library is the inventory of named text you can insert. Same shape, different verb. A snippet is something you say to your document, a prompt is something you say to the AI about your document.
Liam: The prompt library ships with twelve built-in prompts, in four categories. Editing has Check Grammar, Improve Clarity, Make Concise, Fix Grammar, Active Voice, Formal Tone, and Conversational Tone. Writing has Continue from Here. Structure has Summarize and Convert to Bullet Points. Research has Define This Term and Find Counterarguments. They cover the ninety percent case, the things you actually do to a draft, tighten, clarify, restructure, define, argue against. And they are not hidden, the AI menu and the AI Library dialog show them all, named, by category, with a preview.
Jessica: The built-ins have a special property in the code, and I want to say it out loud so it does not feel like magic. You cannot delete a built-in prompt. If you call the remove method on one, the library raises ValueError, built-in prompts cannot be removed. You can, however, override the text and you can disable them, those overrides are stored separately and are persisted to disk. The user prompts you write are persisted alongside the overrides, in a single JSON file written atomically. Same safety guarantee as the snippet library, a crash during save can never leave a half-written library.
Liam: And the placeholder grammar on the AI side is its own dialect, not the same as snippets. A prompt body can contain the literal word selection in curly braces, the literal word document in curly braces, and the literal word title in curly braces. At run time, those tokens get replaced with your actual selection, the whole document, and the document title, before the prompt is sent to the engine. So a single prompt like Summarize does the right thing whether you ran it on a sentence, a paragraph, or an entire chapter. The prompt does not care, the substitution engine adapts.
Jessica: Quillins can also contribute prompts, just like they contribute gallery snippets, by dropping a prompts.json file in their own folder. The library loads those contributions through load-quillin-prompts, and here is the part that matters, Quillin-sourced prompts are held in memory only and are not persisted. So when you restart QUILL, the Quillin contributions come back, but your own prompt library, the JSON file, is what you control.
Liam: And if you want to share your prompts with another user, or move them between machines, the pack format is dot p q p, the schema is quill-dot-prompt-pack-slash-one, and the file is plain JSON with three fields per prompt, name, text, category. You export a pack from the prompt manager, you get a single dot p q p file. You import on another machine, the library reads the pack, and for any prompt whose name is not already in the library it calls add and returns the new entries. Imports are non-destructive on name collision, no overwrites, no surprises.
Jessica: Now the part I have been waiting to get to, the Promote continuum. This is the design idea that ties the three AI inventories together, prompts, skills, and agents, as one library, and gives you a way to graduate your work as it gets more useful. The code lives in quill-core-ai-library, the file we have open. The shape of a library item is the same for all three, kind, id, name, description, detail, and the detail is the body you see in the preview pane. For a prompt, the detail is the prompt text. For a skill, the detail is the skill source. For an agent, the detail is the agent system prompt.
Liam: The Promote continuum is two functions. Prompt-to-skill-source takes a prompt's name and text, and generates a valid one-step dot s q p skill source. The skill's body is the prompt's text, with the curly-brace-selection, curly-brace-document, and curly-brace-title tokens carried through, so the moment you promote a prompt to a skill, you have a runnable workflow that does the same thing the prompt did, but as a step you can compose with others. The generated skill is wrapped in the proper front matter, schema, name, description, author, version. The code is unit-testable, it is a pure string transform.
Jessica: The second function, skill-to-agent-markdown, takes an installed skill and generates an agent dot m d scaffold. The agent's system prompt is derived from the skill's description and the headings of its steps, in order. So a multi-step skill, run-me, then summarize-me, then check-the-tone, graduates into an agent that says, work through these steps in order, using the read tools to look at the document and the edit tools to propose changes. The scaffold includes the agent front matter, id, display name, description, risk, default scope, default harness. You save it into your agents folder, it shows up in the AI Library next to the built-in agents, and you can review it before you ever run it.
Liam: And that last phrase, review it before you ever run it, is the whole point. Prompts run inline. Skills run as steps you trigger. Agents run autonomously, with tool use, with edits proposed, with a review gate. The continuum is not just a feature, it is a teaching path. You start with a one-shot prompt because the job is simple, you promote it to a skill when the job becomes repeatable, you promote it to an agent when the job becomes something you want to be able to hand off. Each step up the continuum adds capability and adds review.
Jessica: The AI Library dialog, which lives under the AI menu as AI Library, is the place where all three kinds live side by side. The list shows kind, name, description, and source. The preview pane shows the detail. And the Promote button is right there, context-sensitive, it only appears on prompts and skills because agents are the top of the continuum. The label is Promote to Skill for a prompt, Promote to Agent for a skill, and there is no button for an agent, because the next step for an agent is to refine it, not to graduate it.
Liam: The reason we put prompts and snippets in one episode is that the design idea is the same in both places. Name a unit of intent, store it durably, recall it on demand, share it as a pack. The differences are mechanical. Snippets have a placeholder grammar with five kinds, prompts have a substitution grammar with three tokens. Snippets insert text, prompts instruct an AI. Snippets are versioned with the snippet library, prompts are versioned with the prompt library, and the dot p q p and dot s q p pack formats make both shareable.
Jessica: A few honest calls before homework. The brief for this episode promised a deep dive on the snippet gallery, and we gave you two distinct galleries, the Insert, Manage Snippets library for your own work, and the Insert, Snippet Gallery for Quillin-contributed entries. They are not the same thing and the menu paths reflect that. The brief also said the prompt module lives at quill-core-ai-prompts, and it does not, the real file is quill-core-prompt-library. We did not paper over that, because if you ever go to read the code, you should know where to look.
Liam: One more. The on-disk episode numbering and the show's intended numbering do not line up perfectly yet. The files-everywhere episode sits at episode twenty-five on disk, not at the slot the show notes assume. We are mid-reorg, and the next few episodes will smooth that out. What matters for today is that the technical content lines up, and we verified it line by line against the actual source.
Jessica: And the smart trigger. The show notes for this episode, and episode nineteen, both treated snippet insertion as a deliberate chord. The current code also auto-expands a trigger the moment you finish it with a delimiter. That is the smart trigger feature, and it is on by default. We are calling it out because the rest of the AI arc will assume you can fire a snippet by typing, not just by chord.
Liam: Homework, four steps. One: open Insert, Manage Snippets, install all three starter packs, and insert at least one snippet from each so you have used all five placeholder kinds, input, choice, date, time, and cursor. Two: write one snippet of your own, something you would actually use this week, a weekly review template, a standup update, a sign-off block, with at least two different placeholder kinds. Three: open the AI Library, browse all three kinds, and promote one built-in prompt to a skill, then look at the generated dot s q p source. You do not have to use the skill, just see what the continuum produces. Four: export your user prompts as a dot p q p file, peek at the JSON, and import it back to confirm the round-trip is clean.
Jessica: And a fifth, if you have time, a bonus step. Open Insert, Snippet Gallery, and see which Quillins have contributed gallery snippets. If a Quillin you use daily has none, that is a feature request worth filing. The gallery is opt-in, and adoption is what makes it useful. Also, try the smart trigger: in any document, type semicolon journal followed by a space, and watch the daily journal header expand on its own. That single moment will make the whole smart-trigger design click.
Liam: Next episode, episode twenty-one, we change register entirely. Read Aloud and Voices, the speech system, the voice catalogs, the per-language and per-dialect voices, and the new multilingual read-aloud work. If you have ever wanted to hear your draft spoken by a voice that does not sound like a robot from two thousand eight, that episode is for you. We will walk through the S A P I voices, the Kokoro voices, the Piper voices, and how to switch on the fly.
Jessica: This is episode twenty of a fifty-four episode course. We are a little more than a third of the way through. The arc ahead, speech, then dictation, then the audio studio, then the AI Hub and everyday AI, then agents, then the vault, then G L O W, then braille, then Quillins and the console, then the finale on trust and community. A lot of ground. The pace is intentional.
Liam: I'm Liam.
Jessica: I'm Jessica. Name what you do, then you will do it more.