sk-create-skill

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 .opencode/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 or install-guide 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

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

Smart Router Pseudocode

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",
}
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 .opencode/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 .opencode/bin/skill-advisor.cjs skill_graph_scan --trusted. Smoke-test routing with node .opencode/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

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. 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; 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 owns the run-folder grammar, the report file set and the index shape; create-manual-testing-playbook 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.
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 .opencode/bin/skill-advisor.cjs skill_graph_scan --trusted. Smoke-test with node .opencode/bin/skill-advisor.cjs advisor_recommend --json '{"prompt":"<a phrase from your intent signals>"}' --warm-only --format json.

Parent Hub Shape

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 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:

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:

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

Package only after validation passes:

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.
• ../shared/references/core-standards.md - shared markdown standards.
• ../shared/references/validation.md - shared validation workflow.