Sk Create Skill

---
name: sk-create-skill
description: Scaffold OpenCode skills and two-axis sk-doc parent hubs, including standalone, nested workflow, and surface packets.
allowed-tools: [Read, Write, Edit, Bash, Grep, Glob]
version: 1.5.0.0
---

<!-- Keywords: create-skill, create-skill-parent, skill scaffolding, parent hub, nested workflow packet, package-skill, init-skill, /create:skill, /create:skill-parent -->

# Create Skill

`create-skill` is the skill-authoring workflow packet of the `sk-doc` parent hub. It owns standalone OpenCode skill scaffolding and parent-hub scaffolding through two workflow modes: `create-skill` and `create-skill-parent`.

---

## 1. WHEN TO USE

### Activation Triggers

Use this packet when the request involves:
- Creating or rebuilding an OpenCode skill under `.skilled/skills/`.
- Running `/create:skill` for a standalone skill with its own advisor identity.
- Running `/create:skill-parent` for a parent hub with nested workflow or surface packets.
- Authoring or repairing `SKILL.md`, `README.md`, `references/`, `assets/`, `scripts/`, or `changelog/` for a skill package.
- Creating parent-hub router files such as `mode-registry.json`, `hub-router.json`, `description.json`, or hub-level `graph-metadata.json`.
- Validating and packaging a skill with `scripts/package_skill.py`.

Keyword triggers: `create skill`, `/create:skill`, `/create:skill-parent`, `new skill`, `skill scaffold`, `SKILL.md scaffold`, `OpenCode skill`, `sk-skill`, `create sk-`, `reusable capability`, `reusable helper`, `starter reference docs`, `parent skill`, `parent hub`, `mode packet`, `nested workflow packet`, `package skill`.

### When NOT to Use

Use another `sk-doc` packet when:
- The user asks for agent scaffolding, command scaffolding, README creation, benchmark packages, feature catalogs, manual testing playbooks, flowcharts, or changelogs. Use `create-agent`, `create-command`, `create-readme`, `create-benchmark`, `create-feature-catalog`, `create-manual-testing-playbook`, `create-flowchart`, or `create-changelog`.
- The task audits, validates, scores, or optimizes an existing skill document without authoring or rebuilding the skill. Use `create-quality-control`.
- The task is application code implementation. Route to `sk-code`.
- The user only needs conceptual advice and no artifact authoring or validation.

### Packet Boundary

This packet may create and edit skill artifacts. It does not own the sk-doc hub identity, and this nested workflow packet must not carry its own `graph-metadata.json`.

---

## 2. SMART ROUTING

### Primary Detection Signal

```text
SKILL AUTHORING REQUEST
    |
    +- Standalone skill -> workflowMode: sk-create-skill
    |   +- scripts/init_skill.py
    |   +- assets/skill/skill-md-template.md
    |   +- assets/skill/skill-readme-template.md
    |   +- assets/skill/skill-sync-manifest-template.md
    |
    +- Parent hub -> workflowMode: sk-create-skill-parent
        +- assets/parent-skill/parent-skill-hub-template.md
        +- assets/parent-skill/parent-skill-registry-template.json
        +- assets/parent-skill/parent-skill-hub-router-template.json
```

### Route Selection

Choose `create-skill` when the artifact is one skill with one advisor identity and one runtime contract.

Choose `create-skill-parent` when the artifact is one advisor-routable hub that dispatches to nested workflow packets or read-only surface packets.

Ask one focused clarification before authoring if it is unclear whether the user wants a standalone skill or a parent hub.

### Resource Domains

| Domain | Core Resources | Use |
| --- | --- | --- |
| Scaffolding | `scripts/init_skill.py`, `assets/skill/skill-md-template.md`, `assets/skill/skill-readme-template.md` | Create or normalize standalone skill files. |
| Resource templates | `assets/skill/skill-reference-template.md`, `assets/skill/skill-asset-template.md`, `assets/skill/skill-smart-router.md` | Create routed references, assets, and resilient smart-router pseudocode. |
| Runtime sync manifests | `assets/skill/skill-sync-manifest-template.md` | Document how a runtime config dir derives from the canonical `.skilled` tree (SYNC manifest). |
| Procedure cards | `assets/skill/skill-procedure-template.md` | Add a private, triggerable internal procedure to a skill or mode without a new public identity. |
| Parent hubs | `assets/parent-skill/parent-skill-*` | Create hub SKILL, registry, router, description, and graph metadata files. |
| Validation | `scripts/package_skill.py`, `../shared/scripts/extract_structure.py` | Check completion, package distribution zips, and inspect structure. |
| Routing measurement | `scripts/score-clarify-default.cjs` | Count how often compiled hubs answer `clarify` with zero model calls and write unlabeled clarify rows. `--score` stops below 30 labeled rows. Past that gate `--jev` or `--deem` asks a classifier for a default pick. |
| Leaf-route replay | `scripts/leaf-route-replay.cjs` | Replay the committed stage-two keyword block of each hub's `ROUTER.md` against its gold scenarios with zero model calls. `--transcripts` recounts `ROUTER.md` reads. Past its gate `--jev` or `--deem` asks a classifier to break ties. |
| Overflow detail | `references/README.md`, `references/{shared,skill,parent-skill}/`, `../shared/` | Load only for edge cases, exhaustive examples, or schema details beyond this SKILL.md. |

### Smart Router Pseudocode

```python
from pathlib import Path

SKILL_ROOT = Path(__file__).resolve().parent
RESOURCE_BASES = (SKILL_ROOT / "references", SKILL_ROOT / "assets")
DEFAULT_RESOURCE = "references/README.md"
RESOURCE_KEY_BY_MODE = {
    "sk-create-skill": "skill",
    "sk-create-skill-parent": "parent-skill",
}

INTENT_MODEL = {
    "SKILL_PACKAGE": {"weight": 4, "keywords": ["create skill", "/create:skill", "new skill", "skill scaffold", "skill.md scaffold", "opencode skill", "sk-skill", "create sk-", "reusable capability", "reusable helper", "starter reference docs", "package skill"]},
    "PARENT_HUB": {"weight": 4, "keywords": ["/create:skill-parent", "parent skill", "parent hub", "mode packet", "nested workflow packet", "mode-registry.json", "hub-router.json"]},
}

# The keyed selection below resolves to exactly these sets. Enumerating them keeps
# the routed inventory legible to a reader and to the connectivity scan, which is
# what catches a new reference that the keyed load silently picks up but no
# documented route names.
RESOURCE_MAP = {
    "SKILL_PACKAGE": [
        "references/shared/overview.md",
        "references/shared/common-pitfalls.md",
        "references/shared/validation-and-packaging.md",
        "references/shared/advisor-index-handoff.md",
        "references/shared/skill-root-metadata-contract.md",
        "references/skill/creation-workflow.md",
        "references/skill/examples-and-maintenance.md",
        "references/skill/upgrading-a-skill-to-v4.md",
        "assets/skill/skill-md-template.md",
        "assets/skill/skill-readme-template.md",
        "assets/skill/skill-reference-template.md",
        "assets/skill/skill-asset-template.md",
        "assets/skill/skill-procedure-template.md",
        "assets/skill/skill-scaffold-template.md",
        "assets/skill/skill-smart-router.md",
        "assets/skill/skill-sync-manifest-template.md",
    ],
    "PARENT_HUB": [
        "references/shared/overview.md",
        "references/shared/common-pitfalls.md",
        "references/shared/validation-and-packaging.md",
        "references/shared/advisor-index-handoff.md",
        "references/shared/skill-root-metadata-contract.md",
        "references/parent-skill/parent-skills-nested-packets.md",
        "references/parent-skill/parent-hub-router-schema.md",
        "references/parent-skill/compiled-routing-architecture.md",
        "assets/parent-skill/parent-skill-hub-template.md",
        "assets/parent-skill/parent-skill-readme-template.md",
        "assets/parent-skill/parent-skill-root-router-template.md",
        "assets/parent-skill/scaffold/hub-skill-scaffold.md",
        "assets/parent-skill/scaffold/packet-skill-scaffold.md",
    ],
}
UNKNOWN_FALLBACK_CHECKLIST = [
    "Confirm whether the artifact is a standalone skill or parent hub",
    "Confirm the target skill folder and intended advisor identity",
    "Provide one concrete trigger, output contract, or resource example",
    "Confirm the validation command before completion",
]

def discover_markdown_resources() -> set[str]:
    docs = []
    for base in RESOURCE_BASES:
        if base.exists():
            docs.extend(path for path in base.rglob("*.md") if path.is_file())
    return {doc.relative_to(SKILL_ROOT).as_posix() for doc in docs}

def _guard_in_skill(relative_path: str) -> str:
    resolved = (SKILL_ROOT / relative_path).resolve()
    resolved.relative_to(SKILL_ROOT)
    if resolved.suffix.lower() != ".md":
        raise ValueError(f"Only markdown resources are routable: {relative_path}")
    return resolved.relative_to(SKILL_ROOT).as_posix()

def load_if_available(relative_path: str, inventory: set[str], loaded: list[str], seen: set[str]) -> None:
    guarded = _guard_in_skill(relative_path)
    if guarded in inventory and guarded not in seen:
        load(guarded)
        loaded.append(guarded)
        seen.add(guarded)

def route_skill_authoring_request(request):
    inventory = discover_markdown_resources()
    loaded, seen = [], set()

    if asks_for_parent_hub_or_mode_registry(request):
        workflow_mode = "sk-create-skill-parent"
    elif asks_for_nested_workflow_or_surface_packets(request):
        workflow_mode = "sk-create-skill-parent"
    elif asks_for_one_skill_package(request):
        workflow_mode = "sk-create-skill"
    elif unclear_standalone_vs_parent(request):
        load_if_available(DEFAULT_RESOURCE, inventory, loaded, seen)
        return {
            "load_level": "UNKNOWN_FALLBACK",
            "needs_disambiguation": True,
            "disambiguation_checklist": UNKNOWN_FALLBACK_CHECKLIST,
            "resources": loaded,
        }
    else:
        load_if_available(DEFAULT_RESOURCE, inventory, loaded, seen)
        return {"load_level": "DEFER", "next": "matching sk-doc packet", "resources": loaded}

    routing_key = RESOURCE_KEY_BY_MODE[workflow_mode]
    shared_refs = sorted(path for path in inventory if path.startswith("references/shared/"))
    keyed_refs = sorted(path for path in inventory if path.startswith(f"references/{routing_key}/"))
    keyed_assets = sorted(path for path in inventory if path.startswith(f"assets/{routing_key}/"))

    if not keyed_refs and not keyed_assets:
        load_if_available(DEFAULT_RESOURCE, inventory, loaded, seen)
        return {
            "workflowMode": workflow_mode,
            "routing_key": routing_key,
            "notice": f"No create-skill resources found for routing key '{routing_key}'",
            "resources": loaded,
        }

    for path in shared_refs + keyed_refs + keyed_assets:
        load_if_available(path, inventory, loaded, seen)

    return {"workflowMode": workflow_mode, "routing_key": routing_key, "resources": loaded}
```

---

## 3. HOW IT WORKS

### Standalone Skill Creation Workflow

Follow these steps in order, skipping only when the target skill already exists and the skipped step is plainly not applicable.

1. Understand the skill through concrete examples.
2. Identify direct user examples or generate examples and validate them with the user when needed.
3. Clarify the skill purpose, trigger phrases, output contract, tool needs, and boundaries.
4. Ask only the most important missing questions first; conclude this step when the supported functionality is clear.
5. Plan reusable skill contents before writing final instructions.
6. For each expected use case, decide whether repeated work belongs in `scripts/`, `references/`, or `assets/`.
7. Put deterministic or repeatedly rewritten code in `scripts/`.
8. Put domain knowledge, schemas, policies, workflows, and detailed guidance in `references/`.
9. Put templates, boilerplate, images, or output resources in `assets/`.
10. Put a private, triggerable procedure in `references/procedures/` using `assets/skill/skill-procedure-template.md` when the skill has multiple distinct, individually-selected internal processes rather than one dominant workflow.
11. Scaffold a new skill when creating a new folder with `scripts/init_skill.py <skill-name> --path <output-directory>`.
12. Normalize generated files to this repo's section order after scaffolding.
13. Delete generated example files and directories that the final skill does not need.
14. Create reference markdown from `assets/skill/skill-reference-template.md`.
15. Create asset markdown from `assets/skill/skill-asset-template.md`.
16. When work creates or reshapes a runtime config dir (`.claude/`, `.codex/`, `.cursor/`, `.devin/`, `.pi/`, or a new runtime), author or update that dir's `SYNC.md` from `assets/skill/skill-sync-manifest-template.md` and cross-link it from every sibling manifest.
17. Use kebab-case for generated filesystem names in `references/`, `assets/`, and other authored resource trees. Keep Python filenames, Python import-package directories, and tool-mandated names such as `SKILL.md` and `README.md` unchanged.
18. Create `README.md` from `assets/skill/skill-readme-template.md` when operators need quick start, examples, troubleshooting, or a package map.
19. Author `SKILL.md` as the executable runtime contract, not as a link farm.
20. Keep `WHEN TO USE` limited to activation triggers, use cases, keyword triggers, and when-not-to-use boundaries.
21. Put resource selection in `SMART ROUTING`, including detection signals, resource domains, loading levels, and smart-router pseudocode.
22. Put the ordered execution path and decision points in `HOW IT WORKS`.
23. Put required actions, forbidden actions, and escalation conditions in `RULES`.
24. Put completion checks in `SUCCESS CRITERIA`.
25. Put references only as overflow pointers for deep detail, examples, or schemas.
26. Run `node .skilled/skills/sk-doc/sk-create-skill/scripts/ci-skill-root-metadata.cjs --fix` after authoring so the manifest and derived aliases are generated and the root passes its class gate.
27. Replace every slug-only routing default before calling the skill done: `graph-metadata.json` `domains` and `intent_signals` plus the `SKILL.md` keyword comment are the fields the advisor's scorers actually read, so fill them with phrases a user would genuinely type, not the skill name repeated.
28. Confirm advisor discovery. A warm advisor daemon ingests a new root automatically (its watcher watches the skills root for new top-level directories); with no daemon running, the next daemon start ingests it. Manual refresh: `node .skilled/bin/skill-advisor.cjs skill_graph_scan --trusted`. Smoke-test routing with `node .skilled/bin/skill-advisor.cjs advisor_recommend --json '{"prompt":"<a phrase from your intent signals>"}' --warm-only --format json` and confirm your skill appears in the recommendations.
29. Run `scripts/validate_skill_package.py <path/to/skill-folder>` before claiming the skill is complete.
30. Fix every hard failure and rerun the check until it exits clean.
31. Package only after validation passes with `scripts/package_skill.py <path/to/skill-folder> <output-directory>`.
32. Iterate after real usage by improving unclear instructions, adding missing resources, trimming bloated `SKILL.md` content into references, and improving trigger descriptions.

### Required Standalone Skill Shape

```text
skill-name/
├── SKILL.md
├── graph-metadata.json
├── leaf-manifest.config.json
├── leaf-manifest.json              # generated
├── leaf-aliases.json               # generated identity projection
├── README.md
├── references/
├── assets/
├── scripts/
├── manual-testing-playbook/          # the scenario corpus — an input
│   └── manual-testing-playbook.md    # the index; per-feature files in category folders
└── benchmark/                        # what running that corpus produced — output
    ├── README.md                     # layout and how to run
    └── reports/
        ├── README.md                 # run index, appended by the harness
        └── <YYYY-MM-DD>--<subject>--<variant>/
```

`SKILL.md` is the root marker. Root JSON requirements are class-specific; the complete authored/generated matrix is [skill-root-metadata-contract.md](references/shared/skill-root-metadata-contract.md). `README.md`, `references/`, `assets/`, and `scripts/` are optional only when they are genuinely unnecessary.

A standalone skill is class **S** under the root-metadata contract, so beyond `graph-metadata.json` it authors exactly one more metadata file — `leaf-manifest.config.json`, naming its single workflow mode and leaf roots — and generates the rest. Required, forbidden, and generated-versus-authored rules for every root JSON live in [`references/shared/skill-root-metadata-contract.md`](references/shared/skill-root-metadata-contract.md); do not infer them from a sibling skill.

The last two directories are a pair: `manual-testing-playbook/` holds the corpus a run reads, and
`benchmark/` holds what the run wrote. Keeping them apart is what lets a run be re-executed against
the same scenarios later and compared, so neither one is optional once a skill is benchmarked.

The scaffolder creates both. Their interiors are owned elsewhere and are not restated here:
[`create-benchmark`](../sk-create-benchmark/SKILL.md) owns the run-folder grammar, the report file set
and the index shape; [`create-manual-testing-playbook`](../sk-create-manual-testing-playbook/SKILL.md)
owns the corpus layout and the results-storage contract. Consult those rather than inferring the rules
from an example.

### SKILL.md Frontmatter Contract

Every `SKILL.md` must include:
- `name`: lowercase hyphen-case and matching the folder name.
- `description`: single-line, specific, non-placeholder routing description.
- `allowed-tools`: YAML array format such as `[Read, Write, Edit, Bash, Grep, Glob]`.
- `version`: four-part `X.Y.Z.W`.

Every authored `references/*.md` and markdown asset should carry the full reference/asset frontmatter block from the packet templates, including `version`. `README.md` is exempt from the full reference block but still uses the README template frontmatter.

### Parent Hub Creation Workflow

Use the parent-hub path when one public skill identity must dispatch to multiple packets.

1. Confirm the hub is one advisor-routable identity, not multiple standalone skills.
2. Keep the hub routing-only; nested packets own detailed workflows, evidence, examples, tool boundaries, and validation.
3. Ask whether the generated state must be `legacy` or `ready`; do not silently choose in the authoring workflow. Existing CLI calls remain backward-compatible and default to `legacy`.
4. Scaffold the selected state with `scripts/init_skill.py <hub-name> --path <parent-directory> --kind parent --compiled-routing legacy|ready`.
5. Create the hub root with `SKILL.md`, `mode-registry.json`, `hub-router.json`, root `ROUTER.md`, `description.json`, `graph-metadata.json`, and generated `leaf-manifest.json`, plus `changelog/`, `manual-testing-playbook/`, and `benchmark/`. Add `command-metadata.json` only when the hub owns slash commands; when present, it has one entry per owned command.
6. `init_skill.py --kind parent` always emits the root `ROUTER.md` with `router_state: stage1-only` — empty stage-two maps and a root `SKILL.md` pointer. Keep it `stage1-only` until a concrete leaf map is authored; only then replace `router_state` with `active` with non-empty equal-key `INTENT_SIGNALS`/`RESOURCE_MAP` whose paths resolve and map to typed `leaf-manifest.json` pairs. Never synthesize placeholder intents.
7. Create each nested packet with `SKILL.md`, `README.md`, and `changelog/`.
8. Add `references/` and `assets/` to surface packets when they carry evidence material.
9. Give a workflow packet its own `procedures/` folder, using `assets/skill/skill-procedure-template.md`, when it has multiple distinct, individually-triggered internal processes; use `shared/procedures/` only for a card that genuinely coordinates two or more packets.
10. Do not add `graph-metadata.json` to nested workflow packets or surface packets.
11. Define every packet in one `mode-registry.json > modes[]` array.
12. Use `packetKind: "workflow"` for lifecycle or process packets.
13. Use `packetKind: "surface"` for read-only evidence packets.
14. For every `modes[]` entry, define `workflowMode`, `packetKind`, `backendKind`, `toolSurface`, `packet`, `packetSkillName`, `grandfatheredFolderMismatch`, `aliases`, and `advisorRouting`.
15. Keep `folder == packetSkillName` for all new packets.
16. Set `grandfatheredFolderMismatch: false` unless preserving an existing mismatch.
17. Keep aliases unique across all modes.
18. Put all workflow and surface packets in `modes[]`; never create a second array such as `surfacePackets[]`.
19. Create `hub-router.json` with `routerPolicy`, `routerSignals`, and `vocabularyClasses`.
20. Ensure `routerSignals` keys match `mode-registry.json > modes[].workflowMode` exactly.
21. Ensure `routerPolicy.tieBreak` lists every registry mode once, with workflow modes before surface packets.
22. Ensure router outcomes include the base three `single`, `orderedBundle`, and `defer`; add `surfaceBundle` only when the hub has surface packets (`surface-axis`).
23. Ensure all router resources are hub-root-relative, packet-qualified paths that resolve on disk.
24. Use named `extensions` only when real routing semantics require them; do not add extra directory tiers for extensions.
25. Treat `legacy (no manifest)` as complete only when no canonical manifest was emitted. For `ready`, the initializer calls `compiled-route-manifest.cjs mint` after the final router inputs exist and then calls `freshness` against the same hub root.
26. Accept `compiled-ready (fresh manifest verified)` only from a valid, fresh canonical result. A missing minter, failed mint, malformed manifest, or stale manifest is a failed generation and retains legacy fallback; never synthesize a digest or author an activation manifest.
27. Confirm the finished hub conforms to class **H** of the root-metadata contract with `node scripts/ci-skill-root-metadata.cjs --fix`, then rerun `node scripts/ci-skill-root-metadata.cjs` to prove cleanliness. Declaring `mode-registry.json` and `hub-router.json` is what makes a root a hub; declaring only one of them is a half-written declaration the gate rejects. Required, forbidden, and generated-versus-authored rules are in [`references/shared/skill-root-metadata-contract.md`](references/shared/skill-root-metadata-contract.md).
28. Replace every slug-only routing default: `graph-metadata.json` `domains` and `intent_signals`, `description.json` keywords, and per-mode registry aliases are the fields the advisor's scorers read — fill them with phrases a user would genuinely type.
29. Confirm advisor discovery. A warm advisor daemon ingests a new hub automatically (its watcher watches the skills root for new top-level directories); with no daemon running, the next start ingests it. Manual refresh: `node .skilled/bin/skill-advisor.cjs skill_graph_scan --trusted`. Smoke-test with `node .skilled/bin/skill-advisor.cjs advisor_recommend --json '{"prompt":"<a phrase from your intent signals>"}' --warm-only --format json`.

### Parent Hub Shape

```text
parent-hub/
├── SKILL.md
├── mode-registry.json
├── hub-router.json
├── ROUTER.md                   # stage-two control; stage1-only on a fresh scaffold
├── description.json
├── graph-metadata.json
├── command-metadata.json          # optional; only when the hub owns slash commands
├── leaf-manifest.json              # generated
├── changelog/
├── manual-testing-playbook/          # the scenario corpus — an input
│   └── manual-testing-playbook.md    # the index; per-feature files in category folders
├── benchmark/                        # what running that corpus produced — output
│   ├── README.md                     # layout and how to run
│   └── reports/
│       ├── README.md                 # run index, appended by the harness
│       └── <YYYY-MM-DD>--<subject>--<variant>/
├── workflow-packet/
│   ├── SKILL.md
│   ├── README.md
│   ├── procedures/       (optional - only if the packet has multiple distinct, triggered procedures)
│   └── changelog/
└── surface-packet/
    ├── SKILL.md
    ├── README.md
    ├── references/
    ├── assets/
    └── changelog/
```

Class-H root metadata follows the [skill-root-metadata-contract.md](references/shared/skill-root-metadata-contract.md) matrix, including authored versus generated files.

A packet may carry its own `benchmark/` in the same shape when it is measured separately from its
hub. The corpus/output pairing and the owning-skill references described under the standalone shape
apply identically here.

### Validation And Packaging Gate

Run the completion gate before any completion claim:

```bash
scripts/validate_skill_package.py <path/to/skill-folder>
```

It auto-detects skill kind — standalone skills run the package check; parent hubs additionally run the parent-hub structural check and the canonical manifest freshness check. A missing manifest reports the valid legacy state; a valid fresh manifest reports compiled-ready; malformed or stale manifests fail validation.

`--check` hard-fails on missing SKILL frontmatter or required fields, non-four-part versions, folder/name mismatches, missing required sections, malformed names, and descriptions that are missing, multiline, or contain angle brackets. Generated package paths that are not kebab-case remain advisory during a debt-tolerant `--check`; `--strict` and actual packaging promote them to blocking errors. Python filenames, Python import-package directories, frozen/generated subtrees, and tool-mandated names are exempt.

Use structure extraction when quality evidence is needed:

```bash
../shared/scripts/extract_structure.py <path/to/skill/SKILL.md>
```

Package only after validation passes:

```bash
scripts/package_skill.py <path/to/skill-folder> <output-directory>
```

---

## 4. RULES

### ✅ ALWAYS

1. Read existing target skill or hub files before editing them.
2. Select `create-skill` or `create-skill-parent` before authoring.
3. Build the skill for another AI agent instance to execute; include information that is beneficial and non-obvious.
4. Use local templates under `assets/skill/` rather than inventing file shapes from memory.
5. Keep `SKILL.md` under 5k words and focused on activation, routing, core workflow, rules, and success criteria.
6. Move deep examples, schemas, edge cases, and long guidance into `references/`.
7. Keep `WHEN TO USE` free of file references and navigation tables.
8. Keep one authoritative routing source in `SMART ROUTING`.
9. Delete TODO placeholders and generated example files before validation.
10. Run `scripts/validate_skill_package.py <path>` before calling the scaffold complete.
11. Use `assets/skill/skill-procedure-template.md` for a private, triggerable internal procedure; use `assets/skill/skill-reference-template.md` when no trigger-based selection is needed.

### ⛔ NEVER

1. Never defer the core executable creation workflow out of `SKILL.md`.
2. Never create multiple advisor identities when the requested artifact is a parent hub.
3. Never add `graph-metadata.json` to a nested workflow or surface packet.
4. Never add `surfacePackets[]` or another parallel registry array.
5. Never create new folder/name mismatches for convenience.
6. Never use multiline YAML descriptions in skill frontmatter.
7. Never leave angle-bracket placeholders, TODO text, or generic descriptions in shipped artifacts.
8. Never claim automatic platform behavior that OpenCode does not provide; document manual verification instead.
9. Never package or distribute a skill before validation passes.
10. Never broaden into unrelated sk-doc artifact types.

### ⚠️ ESCALATE IF

1. It is unclear whether the target should be a standalone skill or parent hub.
2. Tool permissions, mutation authority, or advisor identity boundaries are ambiguous.
3. Existing folder names conflict with required `name` or `packetSkillName` rules.
4. A parent hub needs routing semantics beyond the core two-tier model.
5. Validation fails for reasons that would require changing the public contract.

---

## 5. SUCCESS CRITERIA

- The correct workflow mode was selected: `create-skill` or `create-skill-parent`.
- Concrete trigger examples, boundaries, tool needs, and output contracts are reflected in the artifact.
- Standalone skills contain valid frontmatter, executable `SKILL.md` workflow content, useful resources, and no placeholder examples.
- Parent hubs contain one hub identity, one `modes[]` registry, valid router metadata, one root `ROUTER.md` in a valid `stage1-only` or `active` state, and nested packets without packet-local graph metadata.
- Generated resource paths use kebab-case, with Python and tool-mandated names preserved exactly.
- `scripts/validate_skill_package.py <path>` exits clean, or exact blockers are reported.
- Shared create-quality-control standards from `../shared` were applied when quality evidence was needed.

---

## 6. REFERENCES

Use these only for overflow detail, exhaustive examples, or schema checks beyond the core workflow above.

- `references/README.md` - route map for the full reference set.
- `references/shared/overview.md` - deeper anatomy, layered-doc structure, and resource placement guidance.
- `references/skill/creation-workflow.md` - expanded examples for the six-step standalone workflow.
- `references/skill/upgrading-a-skill-to-v4.md` - adopter guide for reconciling a customized skill to the v4 parent-hub format (convert-vs-keep-single decision, single→parent procedure, sk-code/sk-git cases).
- `references/shared/validation-and-packaging.md` - detailed validation, packaging, and distribution notes.
- `references/shared/common-pitfalls.md` - examples of recurring trigger, YAML, style, and context-budget defects.
- `references/parent-skill/parent-skills-nested-packets.md` - detailed parent-hub and nested-packet model.
- `references/parent-skill/parent-hub-router-schema.md` - full router and registry schema.
- `references/parent-skill/compiled-routing-architecture.md` - which hubs the compiled router serves, the shadow-child-to-cohort chain, and why `--compiled-routing ready` mints onboarding evidence, not compiled-serving.
- `assets/skill/skill-md-template.md` - standalone skill SKILL.md template.
- `assets/skill/skill-readme-template.md` - skill README template.
- `assets/skill/skill-reference-template.md` - reference markdown template.
- `assets/skill/skill-asset-template.md` - asset markdown template.
- `assets/skill/skill-smart-router.md` - resilient smart-router pattern.
- `assets/skill/skill-procedure-template.md` - private procedure card templates and guidelines.
- `assets/parent-skill/parent-skill-*` - parent hub templates.
- `scripts/init_skill.py` - standalone skill scaffold helper.
- `scripts/package_skill.py` - validation and packaging helper.
- `scripts/score-clarify-default.cjs` - zero-call clarify census and default-pick scorer. It stops below 30 labeled rows. `--jev` or `--deem` scores a pick only past that gate.
- `scripts/leaf-route-replay.cjs` - zero-call stage-two keyword replay and read recount. It scores the `ROUTER.md` keyword block against the committed gold scenarios. `--transcripts` recounts reads and `--jev` or `--deem` breaks ties.
- `../shared/references/core-standards.md` - shared markdown standards.
- `../shared/references/validation.md` - shared validation workflow.