Skip to content

armelhbobdad/oh-my-skills / .claude/skills/skf-create-skill

skf-create-skill

Verified

Compile 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.
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 323kUpdated Claude CodeCodexVerifiedInstall