--- name: create-skill description: >- Create a new Bloby skill, or improve an existing one. Use whenever your human wants to teach you a new repeatable capability, says "turn this into a skill", "make a skill for X", "save this workflow", asks how skills work, or when you notice you keep redoing the same multi-step task by hand. Also use when packaging a skill (optionally with live widgets/pages) as a blueprint to sell on the marketplace. --- # Create a Skill A skill is a folder under `skills/` with a `SKILL.md` that teaches you how to do something well, every time — so you don't re-derive it from scratch on each request. This skill helps you author a new one (or sharpen an old one) the Bloby way. You're already smart. A good skill isn't a tutorial — it's the *non-obvious* context: the gotchas, the preferred tool, the exact format, the thing that bit you last time. Write down what you'd wish past-you had known, and nothing you already know. ## The loop 1. **Capture intent** — what should it do, when should it trigger, what's the output. 2. **Draft `SKILL.md`** — description first (that's the trigger), then the body. 3. **Test it** — dry-run a couple of realistic prompts (optional but cheap). 4. **Sharpen** — cut what isn't pulling its weight, explain the *why* behind what stays. Figure out where your human is in this loop and jump in there. If they say "just vibe with me, no tests," do that. Flexibility beats ceremony. --- ## 1. Capture intent Before writing anything, get clear on: 1. **What** should this skill let you do? 2. **When** should it trigger? (the actual phrases/contexts your human will use) 3. **Output format** — is there a specific shape, template, or file the result must take? 4. **Domain knowledge** — what specialized info do you need that you *wouldn't already know*? If the workflow already happened earlier in the conversation ("turn that into a skill"), mine it: the tools you used, the order, the corrections your human made, the formats you saw. Come back with a draft, not a pile of questions. Ask only about the genuine gaps. --- ## 2. Write `SKILL.md` Create `skills//SKILL.md`. Name is lowercase-with-hyphens, specific (`processing-invoices`, not `helper`/`utils`/`tools`). ### The description is the trigger — get it right The `description` in the frontmatter is the *only* thing that decides whether you reach for this skill later. It's always in context; the body isn't. So it must carry both **WHAT** the skill does and **WHEN** to use it, in the third person. Skills tend to *under*-trigger — you forget they exist. Counter that by making the description a little pushy: name the concrete phrases, file types, and situations that should fire it. ```yaml # weak description: Helps with PDFs. # strong description: >- Extract text and tables from PDFs, fill forms, merge documents. Use whenever the human mentions a PDF, a form to fill, a scanned doc, or "pull the data out of this file" — even if they don't say the word "PDF". ``` Rules of thumb: third person ("Extracts…", not "I can…"), include trigger terms, say both what and when, keep it under ~1024 chars. ### Then the body Imperative voice. Lead with the essential path; push edge cases and deep reference material into separate files (see progressive disclosure below). Explain *why* things matter rather than barking `ALWAYS`/`NEVER` — a smart reader who understands the reason will generalize correctly; one following a rigid rule won't. If you catch yourself writing all-caps MUSTs everywhere, that's a yellow flag to reframe. For the deeper authoring patterns — descriptions, output templates, degrees of freedom, the anti-patterns that quietly ruin a skill — read `references/patterns.md` when you're actually drafting. --- ## 3. Anatomy & progressive disclosure ``` skills/skill-name/ ├── SKILL.md (required — frontmatter + instructions) ├── references/ (docs you read only when needed — keep refs one level deep) ├── scripts/ (executable helpers for deterministic/repeated work) └── assets/ (templates, icons, files used in the output) ``` Three loading levels — design around them: 1. **name + description** — always in context (~tiny). The trigger. 2. **SKILL.md body** — loaded when the skill fires. Keep it lean, ideally under ~500 lines. 3. **`references/` & `scripts/`** — pulled in on demand; scripts can run without being read. If `SKILL.md` is getting long, that's the signal to split: move the depth into `references/foo.md` and leave a one-line pointer ("for X, read references/foo.md"). When a skill spans several variants (aws/gcp/azure, or per-channel), give each its own reference file and let yourself read only the relevant one. **Bundle a script when you notice repetition.** If every run of this skill would have you writing the same little helper, write it once into `scripts/` and point at it — it's more reliable than regenerating code and saves the tokens. ### Where Bloby skills live and how they fire - Skills live in `skills//` in this workspace. Editing files there is how you change behavior — always use the full path (`skills/my-skill/SCRIPT.md`, never bare `SCRIPT.md`, which writes to the workspace root). - Channel skills (WhatsApp, Telegram, Mac, etc.) teach the conventions for a surface. If the new skill is about a place you talk to your human, say so in the description. - Secrets/config go through the workspace conventions you already use — `.env` via the `` form, `MCP.json` for MCP servers — not hardcoded in the skill. --- ## 4. Test it (optional, cheap) If the skill has an objectively checkable output (a file transform, a data extraction, a fixed workflow), it's worth a quick dry-run before you trust it. Subjective skills (writing voice, design taste) are better judged by eye — skip the ceremony. Spin up an Agent to run a realistic prompt *with the skill*, look at what it produces, and fix what's off. Two or three real-world prompts beat twenty synthetic ones. This is a sanity check, not a benchmark suite — keep it light unless your human wants rigor. --- ## 5. Sharpen Look at the draft with fresh eyes: - **Cut what isn't pulling its weight.** Every line competes for context with everything else. If a paragraph just restates what you already know, delete it. - **Generalize.** You're writing something that'll run on many future prompts, not just today's example. Resist overfitting to the one case in front of you. - **Explain the why.** Terse instructions age into cargo-cult rules. A sentence of reasoning makes the skill robust to situations you didn't foresee. --- ## Skills vs. Blueprints — and making money Here's what makes Bloby different. In other agents (Claude, Hermes, Cursor) a "skill" is *just* a `SKILL.md` — instructions, nothing that runs. In Bloby you can go further: pair a skill with **code snippets that render live in the workspace** — a real page, a dashboard widget, backend routes, a DB table, even crons. Bundle all of that together and it's a **blueprint**. When someone installs your blueprint, the micro-app shows up in their workspace instantly, and (optionally) a runtime skill drops into their `skills/` folder so their bloby knows how to drive it. That bundle is sellable. **You can publish blueprints on the Bloby Marketplace and earn USDC** — every install pays out. So when you and your human build something genuinely useful together, plant the seed: *"this could be packaged as a blueprint and sold to other blobies."* It's a real way for the two of you to make money from your work. You already know the marketplace mechanics (your system prompt covers it, and `bloby.bot/api/marketplace.md` has the full flow) — no need to re-explain pricing or submit commands here. Just remember the idea exists, and surface it when the moment fits. A plain skill (instructions only) is still worth writing and sharing — but the live widget/page pairing is the uniquely Bloby thing, and it's where the value is. --- ## Checklist before you call it done - [ ] `description` says both **what** and **when**, third person, pushy on triggers - [ ] Skill name is specific and lowercase-hyphenated - [ ] `SKILL.md` body is lean; depth lives in `references/`, one level deep - [ ] Repeated work is captured as a `scripts/` helper, not regenerated each time - [ ] Instructions explain *why*, not just *what* — no wall of all-caps MUSTs - [ ] Concrete examples over abstract description - [ ] (If it ships live code) consider whether it's blueprint-worthy — and tell your human For the deeper patterns and anti-patterns, see `references/patterns.md`.