Skill Builder

Skill Builder

Skill edits are candidates until relevant behavioral checks pass. Preserve existing work; missing baseline evidence is evaluation work, not authority to delete it. An explicit skills-first update may precede trials, but must remain unqualified.

Routing

steps:
  - id: route
    action: Classify the request and dispatch
    instruction: |
      | Input                          | Workflow         | Jump to     |
      |-------------------------------|------------------|-------------|
      | URL, skills.sh link, skill:// | Intake & Install | intake      |
      | "new skill", "from scratch"   | Author (TDD)     | author_red  |
      | Docs site, GitHub repo, PDF   | Extraction       | extract     |
      | "audit", "is this safe"       | Security Scan    | security    |
      | "merge these skills"          | Merge            | merge       |
      Ambiguous? Ask: "Are you converting existing material or authoring from scratch?"
    validation: "User intent classified into exactly one workflow"
    on_failure: "Ask a clarifying question. Do not guess."

Pointer Repair and Invocation

Every context pointer names both its material and the branch or condition that triggers loading it. When a required reference is missed, sharpen that pointer first; inline its operative content only if sharpening fails, except for explicitly requested baked-in rules. When a step ends prematurely, sharpen its completion bound before splitting the sequence. Replace repeated explanatory phrases with a defined, established domain term when that improves retrieval; do not coin opaque slogans. Delete a demonstrated no-op sentence as a whole rather than cosmetically trimming it. A stronger leading word is useful only if observed behavior changes.

Treat always-loaded descriptions as the most expensive context surface: prune their words aggressively and retain only words that change routing or invocation. Separate that context cost from the human cost of remembering explicit entry points. Treat cognitive load as the price of human agency: spend it where human judgment matters and remove it where deterministic routing or existing conventions can carry the decision. Add an independently discoverable skill only when its own trigger or a real caller warrants that cost. Otherwise keep a conditional branch or shared reference under the existing owner. A router reduces the human index burden by naming destinations and when to use them, not by bypassing invocation or authorization policy.

Use the least costly sufficient information tier: keep ordered actions inline, use an in-file reference for on-demand material when that is enough, and disclose external material behind a pointer only when a branch needs it. An in-file reference is a valid hierarchy tier, not an automatic reason to split a skill.

Inspect the target host's supported invocation metadata before setting flags. Preserve existing invocation choice unless the user requests a change. Portable skills keep a meaningful description; do not assume description presence grants automatic dispatch, or that a foreign disable-model-invocation flag hides content on every host. Where the host enforces explicit-only invocation, routers suggest the skill rather than dispatch it. Shared material needed by such skills belongs in an accessible reference, not behind an unreachable invocation. Test explicit reachability, automatic-trigger positives/negatives and caller routing on the actual host before claiming these properties. Host-specific metadata is not a universal Lev contract. These operative rules are inline; loading the source SKILL-MECHANICS document is not a runtime prerequisite.

Output Sections

Use XML sections directly in the skill body for reusable output templates and semantic response blocks. Do not wrap active XML sections in fenced Markdown or XML code blocks. Fenced blocks are for literal examples only; active templates live as real sections.

Recommended: {option} — {reason}

a. {option_a} b. {option_b} c. {option_c}

YAML is for contracts, FSM/process steps, validation rules, and machine-checkable state. Templates are Markdown prose inside live XML sections.

Workflow 1: Intake & Install

steps:
  - id: intake_acquire
    action: Clone and stage the skill
    instruction: |
      ```bash
      git clone --depth 1 {repo} /tmp/skill-intake-{ts}/
      cp -r /tmp/skill-intake-{ts}/skills/{name}/ ~/.agents/skills-db/_workshop/{source}/{name}/
      rm -rf /tmp/skill-intake-{ts}/
      ```
      Never use WebFetch — it summarizes and destroys content. Never use haiku-tier agents — they hallucinate. Always git clone and cp verbatim.
    validation: "ls ~/.agents/skills-db/_workshop/{source}/{name}/SKILL.md exists and head -1 shows ---"
    on_failure: "Clone failed or SKILL.md missing. Check URL and retry."

  - id: intake_validate
    action: Run hard gates on staged copy
    instruction: |
      ```bash
      file=~/.agents/skills-db/_workshop/{source}/{name}/SKILL.md
      head -1 "$file" | grep -q "^---$" && grep -q "^name:" "$file" && grep -q "^description:" "$file"
      ```
      Any gate fails → reject. Move to .archive/ or delete.
    validation: "All grep commands exit 0"
    on_failure: "Reject the skill. Explain which gate failed."

  - id: intake_security
    action: Run security audit (mandatory for external skills)
    instruction: |
      Jump to security workflow (id: security). Required for anything not authored locally.
    validation: "Security verdict is PASS or PASS-WITH-WARNINGS"
    on_failure: "Hard reject. Quarantine to .archive/ with reason."

  - id: intake_score
    action: Score quality on 5 dimensions (1-10 each)
    instruction: |
      Actionability (concrete steps vs vague), Depth (expert vs surface), Structure (tables vs wall of text), Triggers (WHAT/WHEN + tags vs bare), Uniqueness (novel vs generic).
      A (8+) promote. B (7-7.9) promote with note. C (5-6.9) hold in _todo. D (<5) reject.
    validation: "Grade letter assigned. Destination directory determined."
    on_failure: "Default to C grade, hold in _todo for human review."

  - id: intake_catalog
    action: Move from staging to final location
    instruction: |
      A/B → `mv` to `~/.agents/skills-db/{domain}/{name}/`
      C → `mv` to `~/.agents/skills-db/_todo/{name}/`
      D → `mv` to `~/.agents/skills-db/.archive/{name}/`
      Activation to ~/.agents/skills/ happens ONLY if user explicitly requests it.
    validation: "Skill no longer in _workshop/. ls confirms new location."
    on_failure: "Check permissions and path. Retry mv."

Workflow 2: Author from Scratch (TDD)

steps:
  - id: author_red
    action: "RED — Establish baseline failure"
    instruction: |
      Establish source obligations and baseline evidence for behavioral qualification:
      1. Map each required behavior and failure mode to an observable scenario
      2. Freeze fixture, skill/source digests, allowed effects and finite trial budget
      3. Run fresh-context subagents without the target skill; keep source/reference and absorbed arms separate
      3. Capture verbatim: what choices, what rationalizations (exact words), which pressures triggered violations
      Distinguish observed failure, already-satisfied behavior, inconclusive result
      and infrastructure error. Never manufacture RED. Fresh prompts are not OS
      isolation; label shared-workspace trials representative_nonhermetic.
    validation: "Obligations have cases or explicit observability gaps; observed outcomes and trial limits are recorded."
    on_failure: "Keep behavioral qualification pending; preserve authorized candidate edits."

  - id: author_green
    action: "GREEN — Write minimal skill addressing observed failures"
    instruction: |
      Write SKILL.md addressing the specific rationalizations from RED.

      Format: standard skill frontmatter + body:
      - Frontmatter contains `name` and `description`; optional metadata only if the local runtime consumes it
      - Do not invent version/status/provenance keys
      - description starts with "Use when..." — trigger conditions ONLY, never workflow summary
      - Steps are verbs not states. "Search these sources" not "DISCOVER"
      - YAML blocks define contracts, FSM/process, validation, and state
      - Reusable output templates are live XML sections with Markdown prose inside, e.g. `<report>...</report>` or `<decision>...</decision>`
      - Do not put active XML templates inside fenced markdown or fenced XML code blocks
      - First step = most important output, not background theory
      - Bake the operative writing rules into this skill; writing-for-agents remains a separate top-level reference, not a runtime prerequisite.
      - Make every context pointer name its material and triggering branch; front-load only the distinguishing trigger words, collapse synonyms, and prune always-loaded words aggressively.
      - Keep mandatory steps inline. Disclose branch-only material with an explicit condition and load validation.
      - Use an in-file reference for on-demand material when it is the least costly sufficient hierarchy tier; disclose it externally only when a branch needs a separate context load.
      - Co-locate a concept's definition, constraints, and caveats; maintain one operative statement per rule.
      - Completion criteria must be observable and cover every required result; a heading or self-report is not completion.
      - Split a sequence only when later steps cause observed premature completion; a fresh context boundary must enforce the split.
      - Use established domain terms and positive action instructions. Keep a prohibition only for a hard guardrail that cannot be phrased positively, and pair it immediately with the positive target.
      - Treat code, config, schemas, directory layout and live help as the environment's source of truth; keep documentation as a cache only when lookup is costly, and preserve rationale and non-obvious constraints rather than stale copies.
      - Check every line for relevance to what the skill does; prune duplicate, stale and no-op prose, and measure context load separately from the operator's discovery burden.
      - Choose automatic versus explicit invocation deliberately; test trigger negatives and competing routes as well as happy paths.
      - validation: strings are concrete verifiable checks (commands or binary states)
      - Artifact-producing skills need a canon write gate plus lifecycle ledger: compiled_intent, disk vs memory state, artifact ref, route, blocker, confidence
      - Natural language in instruction blocks. Never LLM_MUST directives
      - Under 300 lines total. Prose is the enemy.

      Run the frozen scenarios WITH the candidate skill using fresh contexts.
      Retain raw outputs and artifact deltas; independent review assesses semantic
      outcomes, not repeated instruction wording. A changed fixture/rubric starts
      a new evaluator generation; do not repair subject and grader in one attempt.
    validation: "wc -l SKILL.md under 300. Frontmatter has supported keys. All steps have validation: strings. Artifact-producing skills include a fidelity/memory/ledger table. Reusable templates use live XML sections, not fenced code blocks. Subagent passes scenarios that failed in RED."
    on_failure: "Scenarios still fail → skill doesn't address the right rationalizations. Back to RED captures."

  - id: author_refactor
    action: "REFACTOR — Plug holes and build rationalization table"
    instruction: |
      1. Run combined-pressure scenarios (time + sunk cost + exhaustion)
      2. Capture NEW rationalizations, add explicit counters
      3. Build rationalization table (prolepsis — pre-refute evasions):
         | Excuse | Reality |
         | "{exact phrase from baseline}" | {short refutation} |
         Include only observed entries. Use agent's exact words, not invented quotas.
      4. Add red flags list quoting the THOUGHT not the behavior
      5. Re-test within the declared finite budget; unresolved failures remain open

      Three enforcement primitives (see references/techniques.yaml):
      - Prolepsis: rationalization table pre-refutes evasions
      - Positioned commands: validation strings become executable
      - Procedural chains: step IDs create presuppositional sequences
    validation: "Required cases pass within budget or pending failures and evidence gaps are explicit."
    on_failure: "Record the remaining obligation and stop the trial series at its budget."

Workflow 3: Extraction Pipeline

steps:
  - id: extract_prior_art
    action: Check if this skill already exists
    instruction: |
      `ls ~/.agents/skills/ | grep -i "{name}"` and `rg -l "{name}" ~/.agents/skills/*/SKILL.md`
      Exact match → enhance existing. Partial overlap → recommend merge. No match → proceed.
    validation: "Prior art search completed. Decision: new / enhance / merge."
    on_failure: "Search unavailable → proceed as new, note the gap."

  - id: extract_source
    action: Extract raw content
    instruction: |
      | Source  | Command                                              |
      |---------|------------------------------------------------------|
      | Website | skill-seekers scrape --name {name} --url {url}       |
      | GitHub  | skill-seekers github --repo {owner/repo}             |
      | PDF     | skill-seekers pdf --pdf {file} --name {name}         |
      | Multi   | skill-seekers unified --config {config.json}         |
      Not installed? `command -v skill-seekers` — see references/setup.md.
    validation: "output/{name}/ directory exists with extracted content"
    on_failure: "Check installation. See references/troubleshooting.md."

  - id: extract_enhance
    action: Enhance and apply authoring standards
    instruction: |
      Bug in skill-seekers ≤2.7.4: use scripts/enhance-workaround.sh output/{name}
      Then apply author_green rules: trigger-only description, under 300 lines, validation on every step.
      Package: `echo "y" | skill-seekers package output/{name}/ [--target claude|gemini|openai|markdown]`
      Then follow intake_score → intake_catalog for installation.
    validation: "SKILL.md has YAML frontmatter, description starts with 'Use when', wc -l under 300"
    on_failure: "Enhancement failed. Manually apply author_green standards."

Workflow 4: Security Scan

steps:
  - id: security
    action: Run 3-scanner security audit (sequential, early termination)
    instruction: |
      Scanner 1 — Structural Decompile (instant):
      `python3 ~/.agents/skills-db/security/skill-decompile/decompile.py "$file" --output yaml`
      risk_score >= 60 → HARD REJECT.

      Scanner 2 — Semantic Scan (~10s):
      Load security-scanner skill in sandboxed read-only subagent. Checks malicious NL, social engineering.

      Scanner 3 — AgentShield (~5s):
      `npx ecc-agentshield scan --path "$staged_dir" --min-severity medium`

      All pass → proceed. S1 pass + S2/S3 warn → user confirmation. Any hard fail → REJECT + quarantine.
      Full rubric: references/security-audit-gates.md
    validation: "All 3 scanners ran. Verdict recorded as PASS, WARN, or REJECT."
    on_failure: "Tooling unavailable → flag UNAUDITED, require user sign-off before activation."

Workflow 5: Merge

For absorption into existing lifecycle owners, use a source-step ledger before combining text. Each adopted instruction, result, insight and context technique names its source, destination and represented/superseded/rejected disposition with rationale; unresolved mappings remain gaps. Include referenced source resources. Retaining an unchanged specialist is not proof its behavior reached the lifecycle owner. Preserve source snapshots and keep duplicate activation until source-disabled parity supports demotion. Prefer existing owner protocols over a new router or parallel tracker. Domain-neutral versus SDLC-overlay rules must remain explicit; eligible follow-ups use skill://<name> tables.

steps:
  - id: merge
    action: Analyze overlap and produce merged skill
    instruction: |
      1. Read all source skills, identify trigger overlap (>30% = merge candidate)
      2. If merged content ≤ 300 lines → single SKILL.md (LEAF or HUB)
      3. If > 300 lines → ROUTER: write <100L routing header + independent sub-skills
         Add `skill_type: router` and `subsumes: [list]` to frontmatter
      4. Run author_red → author_green → author_refactor on the result
    validation: "Merged skill exists. No source triggers lost. wc -l under ceiling."
    on_failure: "Too large. Split into router + sub-skills."

Workflow 6: Fractal Auto-Generation

steps:
  - id: autogen_detect
    action: Detect repeated handler patterns that lack a dedicated skill
    instruction: |
      Sources of auto-generation signals (check in order):
      1. FlowMind flow metadata — skills can be emitted from typed flow YAML
         (ref: proposals/20260412-flowmind-typed-schemas.yaml)
      2. lifecycle-manifest.yaml — any verb without a matching skill is a scaffold candidate
      3. Agent telemetry — 3+ identical handler invocations across sessions = repetition signal
      Pattern: observe agent behavior → detect repetition → propose skill scaffold → validate → promote.
    validation: "At least one signal source checked. Candidate list is non-empty or explicitly empty."
    on_failure: "No signals found. Skip auto-generation. Do not fabricate candidates."

  - id: autogen_scaffold
    action: Generate candidate SKILL.md from detected pattern
    instruction: |
      Dogfood approach — pipe flow YAML to stdin, dry-run without writing:
      ```bash
      cat flow.yaml | lev skill scaffold --dry-run --from-flow -
      ```
      Output goes to stdout for review, never directly to disk.
      Scaffold must satisfy author_green rules: trigger-only description, validation on every step, under 300 lines.
      Reusable output templates must use live XML sections with Markdown prose inside, not fenced code blocks.
      For lifecycle verbs: extract the verb's handler signature as the skill's first step.
    validation: "Dry-run output parses as valid SKILL.md frontmatter + steps. Live XML sections wrap reusable templates. No files written."
    on_failure: "Scaffold invalid. Fix or discard. Never auto-promote broken output."

  - id: autogen_promote
    action: Validate scaffold and promote to intake pipeline
    instruction: |
      1. Run author_red baseline — does an agent fail WITHOUT this skill?
      2. If yes → run intake_score and intake_catalog (Workflow 1)
      3. If no → the pattern is not worth a skill. Archive the candidate.
      Auto-generated skills are NEVER activated without passing the full intake pipeline.
    validation: "Candidate either promoted through intake or archived with reason."
    on_failure: "Ambiguous value. Hold in _todo/ for human review."

References

Rationalization Table