/skillkit

name: skillkit
description: >
  Toolkit for creating and validating skills and subagents.
  Use when: creating a new skill (fast or full mode), validating an
  existing skill, deciding Skills vs Subagents, migrating docs to skills,
  estimating token cost, or running a security scan.
  Triggers: "create skill", "build skill", "validate skill", "new subagent",
  "skills vs subagents", "estimate tokens", "security scan".
category: core

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 i