armelhbobdad/oh-my-skills / .claude/skills/skf-create-skill
skf-create-skill
VerifiedCompile a skill from a brief. Supports --batch for multiple briefs. Use when the user requests to "create a skill" or "compile a skill."
assets/skill-sections.md
View on GitHub# SKILL.md Section Structure
## agentskills.io Compliant Format
### Frontmatter
The authoritative frontmatter contract — permitted fields, the `name`/`description` rules, the trigger-phrase/voice requirements, and the no-angle-brackets rule — is owned by `assets/compile-assembly-rules.md` (## Frontmatter). This catalog does not restate it (both files load together at compile.md §1).
### Two-Tier Section Structure
SKILL.md uses a two-tier structure to ensure actionable content survives `split-body` extraction.
#### Tier 1 — Always Inline (survives split-body, target <300 lines)
| # | Section | Budget | Purpose |
|----|--------------------------------------|-----------|-----------------------------------------------------------------|
| 1 | **Overview** | ~10 lines | What the library does, source repo, version, tier, export count |
| 2 | **Quick Start** | ~30 lines | 3-5 core functions with one runnable end-to-end example |
| 3 | **Common Workflows** | ~30 lines | 4-5 typical function call sequences for common tasks |
| 4 | **Key API Summary** | ~20 lines | Table of top 10-15 functions (name, purpose, key params) |
| 4b | **Migration & Deprecation Warnings** | ~10 lines | T2-future warnings inline (Deep tier only, skip if none) |
| 5 | **Key Types** | ~20 lines | Most important enum/type values inline |
| 6 | **Architecture at a Glance** | ~10 lines | Bullet list of subsystem categories |
| 7 | **CLI** | ~10 lines | Basic CLI commands (skip if no CLI) |
| 7b | **Scripts & Assets** | ~10 lines | Manifest of included scripts and assets (skip if none detected) |
| 8 | **Manual Sections** | ~5 lines | `<!-- [MANUAL] -->` markers for update-skill |
#### Tier 2 — Reference-Eligible (extracted by split-body into references/)
| # | Section | Purpose |
|---|---------|---------|
| 9 | **Full API Reference** | Complete signatures, parameter tables, return types, examples, citations |
| 10 | **Full Type Definitions** | All types, interfaces, enums with full field details |
| 11 | **Full Integration Patterns** | Co-import patterns, adapter details, pipeline internals (Forge/Deep only) |
#### Section Conditionality
- **Section 4b (Migration & Deprecation Warnings)** is conditional: only emitted for Deep tier when T2-future annotations exist. Quick/Forge/Forge+ tiers and Deep tiers without T2-future annotations omit it entirely (no empty section). Parsers and validators must treat this section as optional.
- **Section 7b (Scripts & Assets)** is conditional: only emitted when `scripts_inventory` or `assets_inventory` is non-empty. Omitted entirely when no scripts or assets are detected. Parsers and validators must treat this section as optional.
Assembly ordering, the under-300-line Tier-1 budget, and split-body targeting are owned by `assets/compile-assembly-rules.md` (### Assembly Rules).
### Component Library Section Overrides
The `component-library` section formats — Component Catalog (§4), Key Props (§5), the Props Reference Tier 2 layout, and the component-library `context-snippet.md` format — are owned by `assets/compile-assembly-rules.md` (### Component Library Assembly Overrides), alongside the `reference-app` and whole-language override sets. This catalog does not restate them (both files load together at compile.md §1).
### Provenance Citation Format
| Tier | Format | Example |
|-----------------|----------------------------|-------------------------------|
| T1 (AST) | `[AST:{file}:L{line}]` | `[AST:src/auth/index.ts:L42]` |
| T1-low (Source) | `[SRC:{file}:L{line}]` | `[SRC:src/auth/index.ts:L42]` |
| T2 (QMD) | `[QMD:{collection}:{doc}]` | `[QMD:project:CHANGELOG.md]` |
| T3 (External) | `[EXT:{url}]` | `[EXT:docs.example.com/api]` |
### [MANUAL] Section Markers
Seed empty manual sections for future update-skill compatibility:
```markdown
<!-- [MANUAL:additional-notes] -->
<!-- Add custom notes here. This section is preserved during skill updates. -->
<!-- [/MANUAL:additional-notes] -->
```
Place after Quick Start and after API Reference sections.
---
## context-snippet.md Format (Vercel-aligned indexed format)
Indexed pipe-delimited format for CLAUDE.md managed section (~80-120 tokens per skill). Aligned with Vercel's research finding that retrieval instructions + indexed file maps + inline gotchas dramatically improve agent performance.
```markdown
[{skill-name} v{version}]|root: skills/{skill-name}/
|IMPORTANT: {skill-name} v{version} — read SKILL.md before writing {skill-name} code. Do NOT rely on training data.
|quick-start:{SKILL.md#quick-start}
|api: {top exports with () for functions, comma-separated}
|key-types:{SKILL.md#key-types} — {inline summary of most important type values}
|gotchas: {2-3 most critical pitfalls or breaking changes, inline}
```
### Format rules
- **Line 1:** Skill name + version + root path — version signals training data staleness
- **Line 2 (IMPORTANT):** Retrieval instruction — always present, tells agent to read SKILL.md before acting
- **Lines 3+:** Pipe-delimited index mapping topics to SKILL.md sections (with `#anchor` pointers)
- **Inline content:** Each index line includes a brief inline summary (~10 words) so the agent can decide whether to read the full section
- **gotchas line:** 2-3 most critical pitfalls inline — prevents mistakes without requiring a file read
- **Token budget:** ~80-120 tokens per skill (justified by Vercel's finding that indexed format maintains performance at 80% compression)
- **T1-now content only** — no T2 annotations in the snippet
- **Section anchors** (`#quick-start`, `#key-types`) must match actual SKILL.md heading slugs
- **Version** comes from source detection, not brief default
---
## metadata.json Structure
```json
{
"name": "{skill-name}",
"version": "{source-version}",
"skill_type": "single",
"scope_type": "{full-library|specific-modules|public-api|component-library|reference-app|docs-only}",
"source_authority": "{official|community|internal}",
"source_repo": "{github-url}",
"source_root": "{resolved-source-path}",
"source_commit": "{commit-hash}",
"source_ref": "{source_ref or null}",
"confidence_tier": "{Quick|Forge|Forge+|Deep}",
"spec_version": "1.3",
"generation_date": "{ISO-8601}",
"description": "{SKILL.md frontmatter description}",
"language": "{primary-source-language}",
"ast_node_count": "{number-or-omitted-if-no-ast}",
"exports": [],
"tool_versions": {
"ast_grep": "{version-or-null}",
"qmd": "{version-or-null}",
"skf": "{installed-skf-version-or-unknown}"
},
"confidence_distribution": {
"t1": 0,
"t1_low": 0,
"t2": 0,
"t3": 0
},
"stats": {
"exports_documented": 0,
"exports_public_api": 0,
"exports_internal": 0,
"exports_total": 0,
"public_api_coverage": 0.0,
"total_coverage": 0.0,
"scripts_count": 0,
"assets_count": 0
// "effective_denominator": 0 // optional: emitted when compile.md §4 passes it (counts.effective_denominator_decision.store and a stratified scope.notes); test-skill uses this as the coverage denominator when present.
},
// scripts[] and assets[] — include ONLY when inventories are non-empty; omit entirely otherwise
// "scripts": [{ "file": "scripts/{name}", "purpose": "{description}", "source_file": "{source-path}", "confidence": "T1-low" }],
// "assets": [{ "file": "assets/{name}", "purpose": "{description}", "source_file": "{source-path}", "confidence": "T1-low" }],
// doc_sources[] — include ONLY when doc detection ran; omit if detection was skipped entirely
// "doc_sources": [{ "url": "https://...", "detected_via": "homepageUrl|readme_link|pages_api|docs_folder|readme_always|brief_doc_urls", "content_hash": "sha256:{hex}|null", "recorded_at": "ISO-8601" }],
// detected_via "brief_doc_urls" = docs-only skills: the brief's doc_urls (plus subpages step 3c fetched), hashed by `skf-detect-docs.py hash-urls`
"generated_by": "{quick-skill|create-skill}",
"dependencies": [],
"compatibility": ""
}
```
---
## references/ Directory Structure
One file per major function group or type:
```
references/
├── {function-group-a}.md — Detailed reference with full examples
├── {function-group-b}.md — Detailed reference with full examples
└── {type-name}.md — Type definition details
```
Each reference file includes:
- Full function signatures
- Detailed parameter descriptions
- Return value details
- Complete usage examples
- Related functions cross-references
- Temporal annotations (Deep tier: T2-past, T2-future)
- **Table of contents** (required for files exceeding 100 lines) — a `## Contents` section at the top listing all sub-sections for agent discoverability
---
## provenance-map.json Structure
```json
{
"provenance_version": "2.0",
"skill_name": "{name}",
"skill_type": "single|stack",
"source_repo": "{url or [urls] for multi-source}",
"source_commit": "{hash or {repo: hash} for multi-source}",
"source_ref": "v0.5.0",
"generated_at": "{ISO-8601}",
"entries": [
{
"export_name": "getToken",
"export_type": "function",
"source_library": "{library-name — defaults to skill name for single skills}",
"params": ["userId: string", "options?: TokenOptions"],
"return_type": "Token",
"source_file": "src/auth/index.ts",
"source_line": 42,
"confidence": "T1",
"extraction_method": "ast-grep",
"ast_node_type": "export_statement",
"signature_source": "T1"
}
],
"integrations": [
{
"libraries": ["lib-a", "lib-b"],
"pattern_type": "provider-consumer",
"detection_method": "co-import grep|architecture_co_mention|inferred_from_shared_domain",
"co_import_files": [{"path": "src/app.ts", "line_a": 5, "line_b": 7}],
"confidence": "T1|T2|T3"
}
],
"constituents": [
{
"skill_name": "{constituent-skill-name}",
"skill_path": "skills/{skill-dir}/",
"version": "{version at compose time}",
"composed_at": "{ISO-8601}",
"metadata_hash": "sha256:{hash of constituent metadata.json at compose time}"
}
],
"file_entries": [
{
"file_name": "scripts/{name}",
"file_type": "script",
"source_file": "{source-path}",
"confidence": "T1-low",
"extraction_method": "file-copy",
"content_hash": "sha256:{hash}"
}
]
}
```
- `provenance_version`: Schema version. `"2.0"` enables unified single/stack support. Audit reads both v1 (no version field) and v2.
- `source_library`: Identifies which library an export belongs to. For single skills, defaults to the skill/package name. For stack skills, identifies the constituent library.
- `integrations`: Stack-only. Describes cross-library integration patterns with their own schema — not shoehorned into entries.
- `constituents`: Stack-only (compose-mode). Tracks the compose-time snapshot of each source skill for staleness detection. `metadata_hash` enables audit to detect constituent drift without re-reading all constituent files.
- `file_entries` remains optional — omit when no scripts, assets, or promoted docs exist.
- Single skills omit `integrations` and `constituents` arrays entirely (not empty arrays).
**`file_type` enum — canonical values:**
| Value | Source inventory | Copied to skill package? | `extraction_method` | Purpose |
|---|---|---|---|---|
| `"script"` | `scripts_inventory` | yes → `scripts/` | `"file-copy"` | Runnable scripts (CLI tools, validation scripts, etc.) bundled into the skill for execution. |
| `"asset"` | `assets_inventory` | yes → `assets/` | `"file-copy"` | Data files (templates, JSON schemas, config fixtures) bundled for reference. |
| `"doc"` | `promoted_docs` (from step 3 §2a) | **no** | `"promoted-authoritative"` | Authoritative AI documentation files (`llms.txt`, `AGENTS.md`, etc.) promoted into scope by the Discovered Authoritative Files Protocol. The source file is tracked for drift detection but not bundled into the skill — its content influences compile-time decisions (description, Quick Start) and is watched for upstream changes. |
When `file_type: "doc"`:
- `source_file` is the relative path from the source root to the authoritative doc.
- `content_hash` is computed at promotion time (step 3 §2a) and persisted here so update-skill Category D can detect drift via hash comparison.
- `file_name` convention: use the source-relative path prefixed with `docs/authoritative/` to namespace doc entries away from script/asset filenames in tools that iterate `file_entries[]` by `file_name`. Example: `docs/authoritative/apps/docs/public/llms.txt`. Step-07 does not write this path — it is a synthetic namespace used only within the provenance map.
- `confidence` is `"T1-low"` (the promotion decision is source-level but the content was not AST-parsed).
---
## evidence-report.md Structure
```markdown
---
skill_name: {skill-name}
generated: {date}
forge_tier: {tier}
t2_future_count: {N}
---
# Evidence Report: {skill-name}
**Generated:** {date}
**Forge Tier:** {tier}
**Source:** {repo} @ {commit}
## Tool Versions
- ast-grep: {tool_versions.ast_grep}
- QMD: {tool_versions.qmd}
- SKF: {tool_versions.skf}
## Extraction Summary
- Files scanned: {count}
- Exports found: {count}
- Confidence: T1={n}, T1-low={n}, T2={n}, T3={n}
## Validation Results
- Schema: {pass/fail} (quality score: {score}/100)
- Frontmatter: {pass/fail}
- Body: {pass/fail} {body split applied if applicable}
- Security: {pass/warn/skipped} ({the note §5's Security row gives})
- Description angle brackets: {none | re-sanitized ({count} substitutions) | not checked — no description}
- Tessl Review: {tessl_summary}
- Metadata: {pass/fail}
- Provenance labels: {pass | relabeled {N} to match extraction_method: {export names}}{; WARN, no node kind found: {export names}}
- Provenance lines: {pass | findings | fixed {N} source lines, {M} citation prefixes and {K} node kinds | not run: verifier missing | not run: verifier error}{; second run: verifier error}{; unverified, no definition line found: {export names}}{; WARN: {each line, citation or node-kind warning §7a lists}}{; source lines not checked: no local source tree}{; node kinds not checked: no ast-grep CLI | unrecognized ast-grep}{; node kinds unchecked: {export name (reason) for each node_kinds_unchecked item}}{; node kinds skipped: {N} in files ast-grep has no language for}
## Quality Score Breakdown
- Frontmatter (30%): {score} | Description (30%): {score} | Body (20%): {score} | Links (10%): {score} | File (10%): {score}
## Description Guard
- Restored: {true/false}
- Triggering tool: {tool_name or —}
- Original description preserved: {true/false}
- Notes: {one-sentence detail or —}
## Auto-Fixed Issues
- {"skill-check --fix rewrote SKILL.md" when §2 recorded `skill_check_fix_changed: true`, "SKILL.md may have been rewritten (not hashed) by skill-check --fix" when it recorded `skill_check_fix_changed: unchecked`, otherwise "none"}
## Remaining Warnings
- {any warnings from extraction or validation}
## Tessl Review
- Result: {tessl_summary}
- Workspace: {tessl_workspace or —} · tessl {tessl_version or —} · Run: {tessl_run_id or —}
- Validation findings: {each {tessl_validation} finding as `name (status): message`, or "none"}
- Description suggestions (to act on one, edit the description in the brief and re-run create-skill): {each of {tessl_description_suggestions}, or "none"}
- Content suggestions (advisory, not applied): {each of {tessl_content_suggestions} with its `(not applicable: <rule-id>)` mark, or "none"}
```
**Frontmatter — pinned detection contract:** the `t2_future_count` field is the authoritative forward-looking-annotation count for downstream gate checks (e.g. skf-test-skill §2b migration-section rule). Emit **always**, even when 0 — omission is indistinguishable from "no T2-future data" and silently flips the gate into Case 2/3 for a Case-1 skill. `generated` and `forge_tier` mirror the narrative header for consumers that read only the frontmatter. Downstream gate rules parse `t2_future_count` from frontmatter, not prose — prose drift (heading renames, alternate phrasings like "forward-looking annotations") silently breaks grep-based detection.
**Description Guard slot:** populated by step 6 §0 (create-skill) and §0 (update-skill) when the guard protocol fires. `Restored: true` indicates that an external tool (typically `skill-check --fix` or the `skf-shard-body.py` body split, which create-skill and update-skill both run; update-skill runs `split-body` only as its fallback when that helper is missing) rewrote the frontmatter `description` and the guard restored the pre-tool value. When `Restored: false`, leave `Triggering tool`, `Original description preserved`, and `Notes` as the no-fire dash the template above shows. When `Restored: true`, fill all four fields: tool name, whether the original was successfully written back, and a one-sentence note describing what the tool had changed (e.g., "replaced with generic summary", "truncated at 80 chars", "angle-bracket tokens re-introduced"). Downstream test-skill assertions can grep for `Restored: true` to detect unintended tool rewrites without parsing free-form warning prose.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |