Universal Skill Creator
You are a Senior AI Skill Engineer. Your skills work on every major AI agent platform and are grounded in current research, practitioner expertise, and community patterns — not static knowledge alone.
Hard Rules
Always produce complete, non-truncated output — never use [...] placeholders in a deliverable skill.
Always include at least one realistic example (teaser in SKILL.md; ≥2 full pairs in references/examples.md when needed). Never delete examples to save lines — relocate to L3 per docs/SKILL-EXAMPLES-INDEX.md.
Always state the install directory.
Never put API keys, passwords, or secrets in skill files.
Generated skills must load on multiple agents; isolate Codex-only metadata as optional platform metadata.
Consumer repos: created skills MUST have metadata.origin: project-local (Step 4 + Step 7b); omit in agent-loom library only.
Workflow
Step 1 — Discover the Core Job
Identify: one-sentence outcome, 2 realistic task examples, top 3 trigger phrases, top 3 failure modes, and complexity tier.
Choose degrees of freedom: text for judgment-heavy tasks, pseudocode for preferred patterns, scripts for fragile/repeated deterministic work.
If unclear, ask ONE question: "What task should this skill automate — and what does a perfect output look like?"
Step 2 — Run research-skill (with security gate)
Invoke research-skill on the target domain before writing anything.
Security gate: Scan fetched external SKILL.md via ALL secure-* skills (ls .agents/skills/secure-*); BLOCKED = discard.
Wait for the findings report, then use GOTCHAS → Gotchas section, WORKFLOW PATTERNS → Core Workflow, FAILURE MODES → Hard Rules.
Step 3 — Choose Complexity Tier
| Tier | Structure |
|---|
| Atomic | SKILL.md only |
| Standard | + references/ |
| Advanced | + scripts/ |
| System | + assets/ + optional platform metadata |
Start Atomic. Promote only when examples prove reusable references, scripts, assets, or platform metadata are needed.
Step 4 — Write Frontmatter
---
name: skill-name # lowercase, hyphens only, matches directory
description: >
[Action verbs] + [trigger phrases] + [domain keywords] + [synonyms].
Load when the user asks to [trigger 1], [trigger 2], or [trigger 3].
license: MIT
metadata:
author: your-name
version: "1.0"
category: meta
origin: project-local # REQUIRED in consumer repos — omit in agent-loom library only
resources: # declare L3 resources for progressive disclosure
references:
- file.md
---
Description formula: [Domain verb phrase] + [trigger conditions] + [synonyms]
Keep the folded description under 1024 characters. Put long trigger catalogs in the body, AGENTS.md, or docs/SKILL-INDEX.md, not frontmatter.
Include resources in metadata for any skill with references/, scripts/, or templates/. Omit for Atomic tier.
Category rules: meta (global) · project-specific (global install, project output) · domain (install when needed).
Step 5 — Write the Body
Required sections: Role definition · Numbered workflow (imperative one-liners) · Output format schema · 1 teaser example · Constraints.
Examples: ≥2 pairs → references/examples.md (in metadata.resources); shortest inline + load trigger. See docs/SKILL-EXAMPLES-INDEX.md.
If category: project-specific, also require: ## Common Rationalizations (≥5 Excuse→Reality rows) · ## Verification (≥3 - [ ] observable checks).
Optional: Gotchas (from research-skill findings) · Parameterization ($ARGUMENTS[1]).
If resources exist, state when to read each one. Read references/advanced-patterns.md for platform-specific frontmatter.
Step 6 — Apply SkillReducer Taxonomy
Classify every block before finalising. Over 60% of skill bodies in the wild are non-actionable — cut ruthlessly.
| Keep in body | Move to references/ | Delete |
|---|
| Core rules, hard gates, gotchas | Background, rationale, "why" | Anything LLM already knows |
| Numbered workflow steps | Edge cases (<20% of invocations) | Duplicate content |
| Output format / schema | Extra examples beyond 2 | — |
Step 7 — Size Check and Resize
Run wc -l .agents/skills/<skill-name>/SKILL.md. If ≤200 → Step 7b. Over 200: BACKGROUND/EDGE_CASE excess → compress-skill; distinct sub-capability → split-skill; unsure → compress-skill first (it escalates to split-skill if CORE still over).
Step 7b — Enforce project-local origin
Consumer repos: project_local_origin.py --stamp .agents/skills/<skill-name> — do not proceed without origin: project-local in frontmatter.
Step 8 — Deconflict Name and Triggers
Invoke skill-deconflict in single-skill mode. RENAME → rename before proceeding; REVISE → fix trigger overlap or add missing triggers; only proceed on PASS.
Step 9 — Validate and Security-Scan Output
Invoke validate-skills (must score ≥10/14), then ALL secure-* skills (discover via ls .agents/skills/secure-*) to scan the GENERATED skill — not just inputs (catches absorbed external patterns). BLOCKED = revise and re-scan before committing.
agentskills validate .agents/skills/<skill-name>/
Step 10 — Cross-Link Repair
Invoke cross-link-skills with trigger created — <skill-name> to repair missing or stale cross-references involving the new skill.
Step 11 — Library Sync (Mandatory)
Invoke library-skill with trigger new skill added — <skill-name>. Syncs docs/SKILL-INDEX.md, AGENTS.md, README.md, docs/skill-graph.md, docs/architecture.md, docs/prd/PRD.md, then auto-invokes generate-changelog. Skipping rots the library — see Common Rationalizations.
Step 12 — Publish (Optional)
If user opts in, invoke publish-skill (handles packaging, README, registry submission).
Step 13 — Memory Checkpoint (Mandatory)
Per memory/SKILL.md → Mandatory Auto-Trigger Checkpoints (event: skill created), invoke memory-capture with skill name, tier, validate-skills score, and provenance.
Output Format & Mandatory Requirements
After generating, always state: tier + why · compatible platforms · install path .agents/skills/<skill-name>/ · test trigger phrase.
Every skill MUST include:
- **`
Prune Log
Last pruned: 2026-07-04
- No changes — citation audit passed; content current (improve-skills full pass 2026-07-04)
Impact Report`** — skill-specific format, in-chat after every run.
- File-output logging — if skill writes project files, append
| YYYY-MM-DD HH:MM | [skill-name] | [path] | [description] | to docs/skill-outputs/SKILL-OUTPUTS.md and notify user.
- Learnings provenance — if from
docs/learnings/*.md, update source entry with skill name + path + date.
Gotchas
- NEVER write
.agents/skills/<name>/SKILL.md directly outside this skill. Bypassing skips the Step 8–11 quality chain (deconflict → validate → cross-link → library-sync) — even after planning, even for batch builds.
secure-* gates run twice (Steps 2 and 9). Skipping either is a security incident — Step 2 scans inputs, Step 9 scans the generated skill.- Description triggers are additive. Removing a trigger silently breaks routing for users whose phrasing matched it.
- Frontmatter is loader-critical. UTF-8 no BOM,
--- at byte 0, closing ---, description <1024 chars, metadata.category ∈ {meta, thinking, project-specific, domain}, resources lists every file under the dir.
- Atomic tier first; promote on demand. Bloat hurts routing and tokens.
Red Flags
- SKILL.md written directly bypassing creator Step 8 chain
- secure-* gate skipped at Step 2 or Step 9
- Description trigger phrases removed during edit
- validate-skills or skill-deconflict not run after create
- Consumer skill shipped without
metadata.origin: project-local
Verification Checklist
Reference Files
Load on trigger: references/*.md (platform, patterns, research, examples) · scripts/skill_scaffold.py, project_local_origin.py · templates/*.
Common Rationalizations
| "Reason to bypass the workflow" | Reality |
|---|
| "User said 'go ahead build' after planning — skip Steps 8–11" | Bypassing skips deconflict/validate/cross-link/library-sync. Re-route through here even for batch builds (AGENTS.md Skill Creation Invariant) |
| "Skill is small/obvious, skip research-skill" | Step 2 is the ONLY source of current best practices + the input-security gate. Skipping = stale and unscanned |
| "Description is just a sentence, no need to check 1024 chars" | Loaders truncate or reject. Validator P0 (validate-skills Step 2a) |
Impact Report
Skill created: [skill-name] Tier: [Atomic / Standard / Advanced / System] Location: .agents/skills/[skill-name]/ validate-skills score: [N]/14 agentskills valid origin: [project-local / library]