eric-cielo/moflo / .claude/skills/spell-builder
spell-builder
VerifiedCreate, edit, and validate spell definitions (YAML/JSON) that compose connectors and step commands into end-to-end spells. Use when building new spell definitions, modifying existing ones, or exploring available spell components.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.9 KB |
| architecture.md | markdown | 8.5 KB |
| connectors/github-cli/README.md | markdown | 2.0 KB |
| connectors/http/README.md | markdown | 1.4 KB |
| connectors/local-outlook/README.md | markdown | 1.9 KB |
| connectors/playwright/README.md | markdown | 1.7 KB |
| permissions.md | markdown | 4.3 KB |
| preflight.md | markdown | 4.1 KB |
| steps/agent/README.md | markdown | 1.8 KB |
| steps/bash/README.md | markdown | 1005 B |
| steps/browser/README.md | markdown | 2.1 KB |
| steps/condition/README.md | markdown | 1.1 KB |
| steps/github/README.md | markdown | 1.6 KB |
| steps/loop/README.md | markdown | 1.2 KB |
| steps/memory/README.md | markdown | 1.6 KB |
| steps/outlook/README.md | markdown | 2.9 KB |
| steps/parallel/README.md | markdown | 1.1 KB |
| steps/prompt/README.md | markdown | 923 B |
| steps/wait/README.md | markdown | 667 B |
preflight.md
View on GitHub# Preflight Checks — Author Guide
Purpose: preflight checks let a step fail fast with a helpful message **before** any side effects occur, when the failure depends on runtime state the user controls (clean git tree, logged-in CLI, reachable host, etc.).
## Required: every preflight has a `hint:` field
The `hint:` is what the end user sees on failure. Without it they get raw shell output (`command "git diff --quiet" exited with 1, expected 0`) which looks like a bug in the spell engine.
Good hints:
- Plain English. No command names, exit codes, internal identifiers.
- State BOTH the problem AND the fix in one or two sentences.
- Assume a non-technical reader.
```yaml
steps:
- id: create-branch
type: bash
preflight:
- name: "working tree clean (tracked changes)"
command: "git diff --quiet"
hint: "You have uncommitted changes to tracked files. Commit them or stash them (git stash) before running this spell."
- name: "gh cli authenticated"
command: "gh auth status"
hint: "The GitHub CLI isn't signed in. Run: gh auth login"
config:
command: "git checkout -b feature/new"
```
Bad hints (don't do this):
```yaml
hint: "git diff --quiet failed with exit code 1" # leaks command name + exit code
hint: "Precondition violated" # tells user nothing actionable
```
Preflights without `hint` still work but produce unfriendly default output — flag this as a quality issue before saving the spell.
## Severity: fatal vs warning
Default `severity: fatal` — failure aborts the spell. Use `severity: warning` ONLY when:
- The underlying problem has a safe, one-step fix the user might reasonably want to apply.
- Proceeding is viable either way — the step itself is robust to the condition.
Warning preflights MUST declare `resolutions:` — a list the user can pick from. Each resolution has a `label` and an optional `command` to run before continuing. If `command` is omitted, picking the resolution just proceeds (useful for "I'll handle it myself").
```yaml
preflight:
- name: "working tree clean (tracked changes)"
command: "git diff --quiet"
severity: "warning"
hint: "You have uncommitted changes. If you want them carried onto the new branch, pick 'Stash and carry over'."
resolutions:
- label: "Stash changes and carry them onto the new branch"
command: "git stash push --include-untracked --message 'pre-spell autostash'"
- label: "Commit changes to the current branch first, then continue"
command: "git commit -am 'wip: pre-spell snapshot'"
```
In non-interactive contexts (CI, daemons, scheduled spells) warnings automatically behave like fatals — there is no one to prompt. Don't use `warning` to silently ignore a problem; if ignoring is always safe, the check shouldn't be there.
## Step-Command Preflight Checks (TypeScript)
When authoring a step command (see `connector-builder`), the `preflight:` array on the command takes a `check` function. The `reason` string returned on failure is shown verbatim to end users — same copywriting rules apply.
```typescript
preflight: [
{
name: '<service> reachable',
severity: 'fatal',
check: async (config, ctx) => {
const ok = await ping(config.endpoint);
if (ok) return { passed: true };
return {
passed: false,
reason: `Can't reach ${config.endpoint}. Check your network connection or the service URL in your spell config.`,
};
},
},
{
name: 'local cache fresh',
severity: 'warning',
resolutions: [
{ label: 'Refresh the cache now', command: '<type>-cli cache refresh' },
{ label: 'Continue with stale cache' },
],
check: async (config) => {
const stale = await isCacheStale(config.endpoint);
return stale
? { passed: false, reason: 'Your local cache is more than 24 hours old and may produce outdated results.' }
: { passed: true };
},
},
],
```
## See Also
- [SKILL.md](SKILL.md) — main spell-builder skill
- [permissions.md](permissions.md) — permission disclosure & dry-run reporting
- [architecture.md](architecture.md) — three-layer model
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |