fabioc-aloha Skill Creator
Author skills that pass skill-review's five gates by construction. The five gates are the quality bar; invert them, and you build to standard the first time.
This skill teaches the spec-aligned shape — agentskills.io / Anthropic / Microsoft converge on name + description as the only required fields, with ACT discipline fields layered alongside.
Three-level loading (the cost model)
Anthropic's architectural framing, adopted by ACT:
| Level | When loaded | Token cost | Content |
|---|---|---|---|
| L1 — Metadata | Always (startup) | ~100 tok/skill | Frontmatter name, description. Pre-loaded into system prompt for discovery. |
| L2 — Body | When triggered | <5k tok | SKILL.md body. Read when description matches the request. |
| L3 — Bundled | On demand | Effectively unlimited | references/, scripts/, assets/, examples/. Zero context cost until accessed. Scripts emit output, not code. |
Implication: every line in SKILL.md competes with conversation context once the skill fires. Bundled files are nearly free. When in doubt, bundle.
When to Use
- Authoring a new skill in
.github/skills/ - Refactoring an existing skill (scope shift, split, merge)
- Adopting a Mall unit into this brain (adapt, don't copy verbatim)
When not to use
- Editing an instruction (
.github/instructions/*.instructions.md) — instructions are always-on rules, not invokable skills. Different artifact. - Writing a one-off prompt (
.github/prompts/*.prompt.md) — verb-prompts pair with noun-skills; prompt-only goes through a lighter path. - Authoring a Mall unit — Mall skills target external delivery surfaces (Claude, Cursor, antigravity). Different authoring path.
The Seven Phases
Each phase inverts one of the five gates. Author against the phase, pass the gate.
Phase 1 — Intent capture + evals
Before any drafting, answer in writing:
- What does this skill enable that the agent currently can't do well? One sentence. If the sentence contains "and" or "+", you have two skills — split.
- When should it fire? Concrete trigger phrases or contexts. Not abstract categories.
- What's the output? A file? A decision? A modified artifact? Be specific.
Evals before body (Anthropic's strongest authoring rule). Before writing the SKILL.md body, write 2-3 representative tasks the skill must handle and run the agent without the skill. Document specific failures. Those failures are the eval set; the skill body exists to make them pass. Iterate body against evals, not against imagined use.
Output of this phase: a 3-line intent bullet list + a short eval list at the top of a draft SKILL.md. Delete both before commit — the act of answering forces clarity.
Phase 2 — Prior-art scan
Before writing, look. Two channels (ordered by precedence):
| Channel | How | What you're looking for |
|---|---|---|
| Existing brain | ls .github/skills/ + grep -r description: .github/instructions/ |
Overlap with existing artifacts (Gate 2 dedup risk) |
| Mall inventory | Check the Mall catalog per mall-installation.instructions.md |
Existing Mall units that cover this — adopt rather than author |
Decision matrix:
| Finding | Action |
|---|---|
| Existing brain artifact covers ≥70% | Extend the existing one, don't create a new artifact |
| Mall unit covers it cleanly | Adopt the Mall unit (retarget frontmatter), don't write from scratch |
| Partial coverage in Mall or brain | Author the new skill, cite the partial coverage in Related |
| Nothing exists | Author from scratch — this is the legitimate gap |
If the prior-art scan changes your intent (Phase 1) — go back and revise. Drafting on the wrong intent wastes the rest.
Phase 3 — Draft against Gate 1 (Spec)
Use the frontmatter template at references/frontmatter-spec.md. Spec-aligned shape:
---
name: <kebab-name> # required — matches folder, ≤64 chars, lowercase + hyphens
description: "..." # required — third-person, ≤1024 chars, names what + when
lastReviewed: YYYY-MM-DD # brain-qa enforced, drives the review queue
---
Description discipline (Anthropic, load-bearing because L1 metadata is the discovery mechanism):
- Third person: "Processes Excel files", not "I can help you process Excel files"
- Specific: includes exact package names, tool names, trigger phrases
- Both halves: what the skill does + when to use it
| Good | Bad |
|---|---|
"Extract text and tables from PDF files. Use when the user mentions PDFs, forms, or document extraction." |
"Helps with documents" |
"Detect stale Mall stores using deterministic freshness checks. Use during /audit-mall or when triaging upstream drift." |
"Mall freshness helper" |
File location: .github/skills/<kebab-name>/SKILL.md. Folder name matches name frontmatter. Anthropic recommends gerund form for new skills (processing-, analyzing-, converting-); existing noun-form skills (skill-review, mall-curation) stay as-is — no forced rename.
Phase 4 — Draft against Gate 2 (Quality)
| Quality criterion | How you author for it |
|---|---|
| Behavioral, not encyclopedic | Every section title is a verb or instruction. "What X Is" sections are anti-patterns. |
| Visible markers / falsifiability | Include a ## Would Revise If block with at least one concrete falsifier (date, count, observable event). |
| ≤500 lines | Anthropic spec cap. Bundle long reference content into references/<topic>.md rather than inlining (see Phase 6). |
| Single responsibility | One verb in the title. If you need "and", split. |
| No duplicate content | Cross-reference, don't restate. Link to the five-gates checklist; don't paste it. |
| Consistent terminology | Pick one term per concept ("field" / "box" / "element" — pick one), use it throughout. |
| Time-sensitive info | Avoid "as of August 2025" phrasing. Use "Current method" + collapsed "Old patterns" sections instead. |
Phase 5 — Draft against Gate 3 (Scope)
Routing — where does this skill live?
| Target | Route |
|---|---|
| Generic, helpful to many projects | File in this heir's .github/skills/ |
| Project-specific helper, no reuse | Not a skill — it's a project script or a one-off prompt |
| External surface (Claude / Cursor / antigravity catalog) | Not an ACT skill — author a Mall unit instead |
Phase 6 — Draft against Gate 4 (Safety) + bundle resources
Safety checks (inversion of Gate 4):
- No destructive defaults. Anything that deletes, force-pushes, or overwrites requires
confirm()or explicit user approval in the SKILL.md prose, not just in linked scripts. - No hardcoded credentials, no PII, no real client names.
- If the skill reads external content (URLs, files), specify how it sanitizes before use.
- Reversible: a user can disable the skill (delete its folder, or move it out of
.github/skills/) without breaking the brain.
Bundled resources — the under-used pattern. Most Supervisor skills are SKILL.md-only. They shouldn't be. Use subfolders when content is read-on-demand rather than always-loaded:
| Subfolder | Put here | Don't put here |
|---|---|---|
references/ |
Domain knowledge the skill consults (checklists, specs, frameworks, taxonomies). Markdown only. | Behavioral rules — those go in SKILL.md prose. |
scripts/ |
Executable helpers the skill invokes (Node, PowerShell, Python). | One-shot project scripts unrelated to the skill itself. |
assets/ |
Output templates the skill produces (skeleton files, report templates, examples). | Working drafts, generated outputs. |
examples/ |
Worked examples showing the skill applied. | Test fixtures (those go in scripts/test/). |
See references/bundled-resources.md for the full pattern guide. The goal is the SKILL.md stays ≤500 lines while domain knowledge expands freely in references/.
Script discipline (Anthropic, applies when the skill bundles scripts/):
- Solve, don't punt — handle errors inside the script; don't let the script fail and ask the model to recover
- No voodoo constants — every magic number gets an inline comment.
REQUEST_TIMEOUT = 30 # HTTP requests typically complete within 30snotTIMEOUT = 47 # ? - Forward slashes always — even on Windows.
scripts/foo.cjs, notscripts\foo.cjs - Specify install commands — don't assume packages are present; document
npm install xorpip install y - MCP tool names — fully qualified (
ServerName:tool_name), not bare
Phase 7 — Dogfood self-audit
Before committing, run skill-review's five gates on your own draft. For routine self-audit the verdict lives in the commit message; for an external candidate (Mall unit, store skill) write the verdict per skill-review/SKILL.md § Recording the Verdict. Writing it down, not just thinking it, is what surfaces the gaps. If any gate fails, fix and re-run.
Also write 2-3 test prompts:
- Should-fire prompts: 2-3 user phrasings the skill must catch (drive the
descriptionfield's keyword set) - Should-not-fire prompts: 2-3 phrasings that look adjacent but shouldn't trigger (guards against over-triggering)
Keep these in your draft notes. They are not part of the shipped skill, but they prove the description field is calibrated. If a should-fire prompt doesn't visibly match the description, the description needs more "pushy" keywords. If a should-not-fire prompt does match, tighten the description.
Optional Phase 8 — Description optimization
After the skill has been used ≥3 times, revisit the description field. If the agent had to be invoked manually each time, the description undertriggers — add keywords from the should-fire prompts. If unrelated invocations fired the skill, it overtriggers — narrow the description.
Anti-Patterns
| Anti-pattern | Correction |
|---|---|
| Writing the skill before the intent capture | Phase 1 is cheap and prevents wasted Phase 3-6 work |
| Skipping evals before drafting | Anthropic's strongest rule. Without evals, the body solves imagined problems. |
| Skipping the prior-art scan because "I know what's there" | The Mall has 14k units. You don't know what's there. |
| Restating the five gates inside the new skill | Cross-link to skill-review. Single source of truth. |
Bundling resources prematurely (empty references/ folder) |
Add a subfolder only when there's real content to put in it. Empty bundling is decoration. |
| Self-auditing without writing the verdict | The verdict template forces honesty. Skipping it lets fuzzy self-assessment slip through. |
| Author and dogfood in the same pass without a break | Read the draft cold. If you wrote it five minutes ago, you can't audit it fairly. |
| Vague description ("Helps with X") | Specific + trigger phrases. Description is the discovery field — no keywords = no discovery. |
| Too many alternatives in body ("use pypdf or pdfplumber or pymupdf") | One default + one escape hatch. Decision fatigue defeats the skill. |
Deeply nested references (SKILL.md → A.md → B.md → C.md) |
Keep references one level deep. Deeper nesting causes partial reads. |
| Reference file >100 lines without table-of-contents | Add a TOC block at the top. |
| Verbose explanations of what the model already knows | Ask "does this paragraph justify its token cost?" Cut if no. |
Windows-style paths in scripts (scripts\foo.cjs) |
Forward slashes always. |
Falsifiability — Would Revise If
This skill's design has failed if any of the following occur within 90 days of stabilization:
- Event-based: ≥2 skills authored using this guide fail
skill-reviewGate 1 or Gate 2 on first self-audit (the phases didn't internalize the gates). - Date-based: 2026-08-26 — if no new skills have been authored via this guide by that date, the skill is decorative, not load-bearing. Sunset this skill.
Related
- skill-review — the five gates this skill inverts (single source of truth)
- instruction-creator — sibling for instructions
- prompt-creator — sibling for prompts
- agent-creator — sibling for agents
- meditation — extracting patterns from session work into new skills
- act-pass — required for medium-stakes skill authoring