skill-creator

name	skill-creator
description	Guides the user through creating a new SecondBrain skill folder with valid SKILL.md frontmatter, explicit activation boundaries, replayable eval cases, a machine-readable creation brief, explicit tool/safety contracts, structured instructions, and optional scripts/references/assets directories. Use when the user wants to create a new skill, build a skill, write a SKILL.md, or scaffold a skill pack from scratch.
version	1.2.0
triggers	["create a skill","new skill","build a skill","scaffold skill","write a SKILL.md","make a skill pack"]
negative_triggers	["optimize an existing skill","tune an existing skill","delete skill","remove skill","uninstall skill"]
allowed_tools	[]
required_tools	[]
trust_level	local
safety_class	standard
examples	["Create a new skill folder with SKILL.md and eval cases.","Scaffold an optimizer-ready skill pack from a workflow description."]
tests	["sb skills validate --path skills --strict","pytest -q tests/skills/test_skill_creator_scaffold.py tests/skills/test_skills_cli_lifecycle.py"]
performance	{"notes":"Best for creating validated procedural skills with explicit triggers, eval splits, and capability contracts."}

Skill Creator

Purpose

Help the user create a well-structured, validated SecondBrain skill from scratch. This skill is for new skill creation; use skill-optimizer when improving an existing skill from replay evidence.

Core Learning Applied

Treat a new skill as a trainable text artifact from the start. The scaffold should not only be valid markdown; it should include the handles that later optimization needs: trigger boundaries, observable success criteria, failure modes, train/selection/test eval cases, a creation brief, declared tool requirements, and a protected slow-update region for epoch-level guidance.

Instructions

1. Capture the skill's job in one sentence: what workflow it handles and when it should activate.
2. Collect at least two concrete trigger phrases and at least one negative trigger.
3. Write instructions as ordered, observable actions. Avoid vague guidance that cannot be checked.
4. Define success criteria before examples. Criteria should be concrete enough for a replay or human verifier.
5. List likely failure modes and adjacent workflows that should not activate this skill.
6. Identify capability needs: allowed tools, required tools, trust level, and safety class.
7. Scaffold with sb skills create, passing triggers, criteria, and capability metadata when available:

sb skills create my-skill \
  --description "Use when ..." \
  --trigger "..." \
  --trigger "..." \
  --negative-trigger "..." \
  --success-criterion "..." \
  --failure-mode "..." \
  --allowed-tool "..." \
  --required-tool "..." \
  --safety-class standard

8. Review references/creation_brief.yaml for the captured builder intent and capability contract.
9. Populate references/eval_cases.yaml with separate train, selection, and test cases.
10. Validate with sb skills validate --path <skill-root> --strict.
11. If the skill will later be optimized, run sb skills optimize-plan <skill-name> --path <skill-root> and fill any missing evidence gaps before optimization.

Creation Contract

• The live artifact is SKILL.md; references and scripts should support the skill, not duplicate its core instructions.
• The activation boundary belongs near the top of the body so future agents know when to load the skill.
• The capability contract belongs in both frontmatter and references/creation_brief.yaml; required tools should also be allowed tools.
• Train cases may drive edits, selection cases decide whether a candidate is accepted, and test cases are reserved for final reporting.
• Candidate changes should be accepted only after held-out selection improvement; ties are rejected.
• Store stable cross-epoch learning inside the slow-update region only after repeated evidence supports it.

Folder Structure

my-skill-name/
  SKILL.md
  references/
    creation_brief.yaml
    eval_cases.yaml
  scripts/
  rules/
  assets/

SKILL.md Sections

• Purpose
• Activation Boundary
• Instructions
• Evidence Contract
• Capability Contract
• Success Criteria
• Failure Modes
• Examples
• Validation
• Slow Update Guidance
• Troubleshooting

Creation Brief Template

schema_version: secondbrain.skill_creation_brief.v1
skill:
  name: my-skill-name
  description: Use when this skill owns a specific workflow.
  version: 1.0.0
  trainable_artifact: SKILL.md
activation_boundary:
  triggers:
    - create the exact workflow this skill owns
  negative_triggers:
    - optimize an existing skill
capability_contract:
  allowed_tools: []
  required_tools: []
  trust_level: local
  safety_class: standard
evidence_readiness:
  eval_cases: references/eval_cases.yaml
  success_criteria:
    - The response follows the skill instructions.
  failure_modes:
    - The skill activates for an adjacent workflow.
  validation_commands:
    - sb skills validate --path skills --strict
optimizer_handoff:
  target_model_policy: freeze target model, tools, and evaluator during optimization
  selection_gate: candidate_score > baseline_score
  ties: reject
readiness_gaps: []

Eval Case Template

schema_version: secondbrain.skill_eval_cases.v1
skill: my-skill-name
split_policy:
  train: Used to propose edits and collect failure reflections.
  selection: Held-out acceptance gate for candidate skills; reject ties.
  test: Locked final-report split, not used for edit selection.
cases:
  train:
    - id: train-positive-1
      input: create the exact workflow this skill owns
      expected_activation: true
      success_criteria:
        - The response follows the skill instructions.
  selection:
    - id: selection-negative-1
      input: optimize an existing skill
      expected_activation: false
      success_criteria:
        - The skill is not selected for this request.
  test:
    - id: test-positive-1
      input: locked final eval request
      expected_activation: true
      success_criteria:
        - The response satisfies the skill's observable criteria.
scoring:
  metric: pass_rate
  selection_gate: candidate_score > baseline_score
  ties: reject

Validation Checklist

• Folder name is kebab-case.
• Folder name matches frontmatter name.
• No README.md in the skill folder.
• Description is under 1024 characters and includes trigger context.
• Frontmatter values do not contain angle brackets.
• triggers has at least two concrete phrases.
• negative_triggers covers adjacent workflows and deletion/removal intents when relevant.
• Tool permissions are explicit; required_tools are also present in allowed_tools.
• trust_level and safety_class match the workflow risk.
• examples, tests, required_tools, and performance are declared.
• references/creation_brief.yaml captures activation, capability, evidence, and optimizer handoff intent.
• references/eval_cases.yaml has train, selection, and test splits.
• sb skills validate --path <skill-root> --strict passes.

Troubleshooting

Symptom	Cause	Fix
Validation error: folder-kebab-case	Folder uses underscores or caps	Rename to kebab-case
Validation warning: strict-trigger-guidance	Triggers are missing or TODO-like	Add at least two concrete trigger phrases
Skill activates for optimizer requests	Builder and optimizer boundaries overlap	Add optimize an existing skill to negative triggers
Required tool is missing at runtime	Tool contract was not captured during creation	Add it to --required-tool and regenerate or update the creation brief
Future optimization has no gate	Eval cases lack selection split	Add held-out selection cases and baseline score