| name | flux-skill-builder |
| description | Autonomously create production-grade agent skills from a brief description. Use when user says "build a skill", "create a skill for X", "I need a skill that does Y", or wants to turn a repeated workflow into a reusable skill. Handles research, drafting, validation, and installation without interactive gates. Do NOT use for editing existing skills (use direct file editing) or for Flux plugin development (use flux-contribute).
|
| user-invocable | true |
Flux Skill Builder
Autonomously create production-grade agent skills from a short description. No interview loops — the agent researches, infers, drafts, validates, and installs in one pass.
Why this exists: The default LLM behavior when asked to "make a skill" produces vague descriptions that never trigger, monolithic SKILL.md files with no progressive disclosure, empty gotchas sections, and instructions that state the obvious. This skill encodes the hard-won patterns that make skills actually work.
Session Phase Tracking
On entry, save the current phase and set the new one:
PLUGIN_ROOT="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}}"
[ ! -d "$PLUGIN_ROOT/scripts" ] && PLUGIN_ROOT=$(ls -td ~/.claude/plugins/cache/nairon-flux/flux/*/ 2>/dev/null | head -1)
FLUXCTL="${PLUGIN_ROOT}/scripts/fluxctl"
PREV_PHASE=$($FLUXCTL session-phase get 2>/dev/null || echo "idle")
$FLUXCTL session-phase set skill_build
On completion, restore the previous phase (not blindly reset to idle — this skill may be invoked from reflect or improve):
$FLUXCTL session-phase set "$PREV_PHASE"
Input
Full request: $ARGUMENTS
Accepts:
- Natural language description:
"build a skill for database migrations"
- Path to existing workflow:
"turn scripts/deploy.sh into a skill"
- Reference to repeated behavior:
"I keep doing X manually, make it a skill"
If empty, ask: "What repeated workflow or capability should this skill encode? Describe it in 1-3 sentences."
Workflow
Execute these 4 phases sequentially. No human gates between phases — run to completion, present the finished skill.
Read pipeline.md for the detailed autonomous execution pipeline.
Phase overview:
| Phase | What happens | Output |
|---|
| 1. Research | Analyze intent, scan codebase, study existing skills | Inferred spec (category, triggers, capabilities, failure modes) |
| 2. Draft | Write SKILL.md + supporting files using progressive disclosure | Complete skill folder |
| 3. Validate | Run validate_skills.py, self-review against checklists | Pass/fail with auto-fixes |
| 4. Deliver | Install to project-local .secureskills/ through PlaTo when available, with loose skill mirrors only as fallback, then generate trigger test report | Installed and ready |
Key Principles
- Infer, don't interview — Research the codebase, existing skills, and brain vault to answer the questions the interactive version would ask. Only ask the user if genuinely ambiguous (2+ equally valid interpretations).
- Description is king — The frontmatter description determines whether the skill ever fires. Spend disproportionate effort here. It must include WHAT, WHEN (with specific trigger phrases), and negative triggers.
- Gotchas are the highest-signal section — Analyze how Claude fails at this task today. Every known failure mode becomes a gotcha. An empty gotchas section means you didn't research hard enough.
- Progressive disclosure — SKILL.md stays under 350 lines. Heavy content goes to
workflow.md, references/, examples.md, or steps.md.
- Scripts for deterministic work — If the skill involves a checkable operation, write a script. Code is deterministic. Prose instructions are not.
- One job per skill — If the skill straddles two categories, split it or narrow the scope.
Gotchas
- Undertriggering is the #1 failure mode. Skills that never fire are worthless. The description must be "slightly pushy" — include adjacent phrases the user might say, not just the exact command name.
- Do not state the obvious. Claude already knows how to code. The skill should contain information Claude does NOT have — repo-specific constraints, non-obvious failure modes, decision rules that override defaults.
- Do not over-railroad. Only use rigid step sequences when deviating genuinely breaks things. For judgment-heavy tasks, give principles and examples, not exact scripts.
- Validate before delivering. Always run
python3 scripts/validate_skills.py skills/<name>/ before presenting the skill. Fix errors automatically. Present warnings to the user.
- Check for existing skills first. Before creating a new skill, scan
.secureskills/store/, ~/.codex/skills/, ~/.claude/skills/, .codex/skills/, and .claude/skills/ for overlap. Extend rather than duplicate.
- Validate the install path, not the repo path. Run
validate_skills.py against the installed skill directory. Prefer PlaTo's materialized project path when available; otherwise validate the loose fallback install path, not skills/<name>/ inside the Flux repo.
- Restore session phase on completion. This skill may be invoked from reflect or improve. Save the previous phase on entry and restore it on exit — do not blindly reset to
idle.
Update Check (End of Command)
ALWAYS run at the very end of execution:
PLUGIN_ROOT="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}}"
[ ! -d "$PLUGIN_ROOT/scripts" ] && PLUGIN_ROOT=$(ls -td ~/.claude/plugins/cache/nairon-flux/flux/*/ 2>/dev/null | head -1)
UPDATE_JSON=$("$PLUGIN_ROOT/scripts/version-check.sh" 2>/dev/null || echo '{"update_available":false}')
UPDATE_AVAILABLE=$(echo "$UPDATE_JSON" | jq -r '.update_available')
LOCAL_VER=$(echo "$UPDATE_JSON" | jq -r '.local_version')
REMOTE_VER=$(echo "$UPDATE_JSON" | jq -r '.remote_version')
If update available, append to output:
---
Flux update available: v${LOCAL_VER} → v${REMOTE_VER}
Update Flux from the same source you installed it from, then restart your agent session.
---
