skillkit

## Section 1: Intent Detection & Routing
**Detect user intent, route to appropriate workflow.**

| Intent | Keywords | Route To |
|--------|----------|----------|
| Full skill creation | "create skill", "build skill", "new skill" | Section 2 |
| Subagent creation | "create subagent", "build subagent", "new subagent" | Section 6 |
| Validation | "validate", "check quality" | Section 3 |
| Decision | "Skills vs Subagents", "decide", "which to use" | Section 4 |
| Migration | "convert", "migrate doc" | Section 5 |
| Single tool | "validate only", "estimate tokens", "scan" | Section 7 |

**PROCEED to corresponding section after intent detection.**

**Stop Condition (Mandatory):**
- If multiple routes match or intent is ambiguous: stop, ask user to choose one route.
- Do not proceed until user confirms the route.

**Workflow Value:** Research-driven approach validates design before building.
Sequential steps with checkpoints produce 9.0/10+ quality vs ad-hoc creation.

---

## Section 2: Creation Workflows (Dual Mode)

**Prerequisites:** Skill description provided, workspace available.

### Mode Selection (Required at Start)

Detect or prompt for workflow mode before running the creation flow.

**Stop Condition (Mandatory):**
- If mode is not explicitly provided: stop and ask "Do you want fast or full mode?"
- Do not continue until user confirms the mode.

| Mode | Steps | Validation | Quality Target | Time |
|------|-------|------------|----------------|------|
| **fast** | 10 | Structural only | >=9.0/10 | <10 min |
| **full** | 14 | Structural + Behavioral | >=9.0/10 and behavioral >=7.0 | <20 min |

No implicit default mode is allowed when mode is not explicitly known.

### Workflow A: Fast Mode (10 Steps)

Use when `.skillkit-mode` contains `fast` or marker does not exist.

**→ READ `references/section-2-fast-creation-workflow.md` IN FULL before starting.**
**Create a task for each step listed in that file, then follow them in order.**
The outline below is a summary only — the reference file is authoritative.

Phase 1: Decision & Research
- Step 0: Decide approach (`decision_helper.py`)
- Step 1: Research and proposals
- Step 2: User validation
- Stop Condition: Stop and request user approval before continuing to Step 3.

Phase 2: Creation
- Step 3: Initialize skill (`init.py skill <name> --mode fast`)
- Step 4: Create content

Phase 3: Structural Validation
- Step 5: Validate skill (`validate_skill.py`) — runs structure + security + tokens in one call

Phase 4: Packaging
- Step 6: Progressive disclosure check
- Step 7: Generate tests (`test_generator.py`)
- Step 8: Quality assessment (`quality_scorer.py`)
- Step 9: Package (`package_skill.py`)

### Workflow B: Full Mode (14 Steps)

Use when `.skillkit-mode` contains `full`.

**→ READ `references/section-2-full-creation-workflow.md` IN FULL before starting.**
**Create a task for each step listed in that file, then follow them in order.**
The outline below is a summary only — the reference file is authoritative.

Phase 1: Decision and Research
- Step 0: Decide approach (`decision_helper.py`)
- Step 1: Research and proposals
- Step 2: User validation
- Stop Condition: Stop and request user approval before continuing to Step 3.

Phase 2: Behavioral Baseline (extra vs fast)
- Step 3 (RED): Run pressure scenarios without skill
  **→ Load `references/section-2-full-creation-workflow.md` → section "Full Mode Behavioral Testing Protocol" (mandatory)**
- Step 4: Document baseline failures

Phase 3: Creation
- Step 5: Initialize skill (`init.py skill <name> --mode full`)
- Step 6: Create content addressing baseline failures

Phase 4: Behavioral Verification (extra vs fast)
- Step 7 (GREEN): Run scenarios with skill
  **→ Load `references/section-2-full-creation-workflow.md` → section "Full Mode Behavioral Testing Protocol" (mandatory)**
- Step 8: Fix gaps

Phase 5: Structural Validation
- Step 9: Validate skill (`validate_skill.py`) — runs structure + security + tokens in one call

Phase 6: Refinement (extra vs fast)
- Step 10 (REFACTOR): Combined pressure tests
  **→ Load `references/section-2-full-creation-workflow.md` → section "Full Mode Behavioral Testing Protocol" (mandatory)**
- Step 11: Close loopholes

Phase 7: Packaging
- Step 12: Quality assessment (`quality_scorer.py --format json`) — behavioral score derived from Steps 3/7/10 subagent results, not from `--behavioral` flag
- Step 13: Package (`package_skill.py`)

### Mode Detection

Priority order:
1. Explicit flag: `--mode fast` or `--mode full`
2. Skill marker: `.skillkit-mode` file content
3. If unknown: stop and ask user to choose `fast` or `full`

---

## Section 3: Validation Workflow (Overview)

**Use when:** Validating existing skill

**Steps:** Execute validation subset (Steps 3-6)
1. Validate skill — structure + security + tokens (`validate_skill.py`, no flags needed)
2. Progressive disclosure check
3. Test generation (optional)
4. Quality assessment (quality_scorer.py)

**Note:** `--security-only` and `--tokens-only` flags are available for Section 7 individual tool use, not for workflow validation steps.

**For detailed workflow:** [See references/section-3-validation-workflow-existing-skill.md](references/section-3-validation-workflow-existing-skill.md)

---

## Section 4: Decision Workflow (Overview)

**Use when:** Uncertain if Skills is right approach

**CRITICAL: Agent MUST create a temp JSON file first.** The `decision_helper.py` script does NOT accept inline JSON strings - it requires a file path to a JSON file.

**Step-by-step invocation:** See `references/section-4-decision-workflow-skills-vs-subagents.md`

**Accuracy:** Highest (90-95% confidence).

**Process:**

1. Run `decision_helper.py` with json file.
2. Answer interactive questions
3. Receive recommendation with confidence score
4. Proceed if Skills recommended (confidence >=75%)
5. If confidence <75% or recommendation is uncertain, stop and ask user whether to continue, switch route, or refine inputs.

**Fo