Skip to content

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

skf-export-skill

Verified

Exports an SKF skill, validating its package, writing its context snippet and updating the managed section in CLAUDE.md, AGENTS.md or .cursorrules. Use when the user requests to "export a skill" or "package a skill."

references/summary.md

View on GitHub
---
nextStepFile: 'health-check.md'
---

<!-- Config: communicate in {communication_language}. Render the user-facing summary in {document_output_language}. -->

# Step 6: Summary

## STEP GOAL:

To present a complete export summary showing all files written, token counts, and provide distribution instructions based on the skill's source authority. Then chain to the local health-check step — it, not this summary, is the terminal step.

## Rules

- Focus only on summarizing what was done and providing next steps: the only files this step writes are the result files the emitter writes in §6 (none on a dry run)
- Chains to the local health-check step via `{nextStepFile}` after completion — the user-facing summary is NOT the terminal step
- **Multi-skill mode:** emit ONE consolidated summary and ONE result contract for the whole batch. The files-written table lists every skill in `skill_batch` (one row per skill's `context-snippet.md` + one row per target managed-section file, shared across the batch). The result contract's `outputs` enumerates every context-snippet file, every target context file and the manifest. Distribution instructions (§2) key off `source_authority` per skill: present one block per distinct authority value observed in the batch, listing the skills it applies to. See step 1 §1c.

## MANDATORY SEQUENCE

### 1. Compile Export Summary

"**Export Complete{if dry-run: ' (Dry Run)'}**

---

**Skill:** {skill-name}
**Type:** {skill_type} | **Authority:** {source_authority} | **Tier:** {confidence_tier}
**Context File(s):** {context-file-list} (skill root: {skill-root-list})

---

### Files {if dry-run: 'Previewed' else: 'Written'}

| File | Status | Tokens |
|------|--------|--------|
| context-snippet.md | {✅ written / ⚠️ skipped (passive off) / 👁️ previewed} | ~{t} |
| {target-file-1} managed section | {✅ updated ({case}) / ⚠️ skipped / 👁️ previewed} | ~{t} |
| {target-file-N} managed section | {✅ updated ({case}) / ⚠️ skipped / 👁️ previewed} | ~{t} |
| Package structure | ✅ validated | ~{t} total |

**Total context cost:** ~{always-on-tokens} tokens always-on, ~{on-trigger-tokens} tokens on-trigger"

### 2. Distribution Instructions

**Based on `source_authority` from metadata:**

**If `official`:**

"### Distribution: Official Ecosystem

Your skill is ready for the agentskills.io ecosystem.

**Publish:**
```
npx skills publish {skill-name}
```

**Others can install with:**
```
npx skills add {skill-name}
```

**Before publishing, ensure:**
- Source repo URL is correct in metadata.json
- You have publish access to the agentskills.io registry
- SKILL.md has been reviewed for accuracy"

**If `internal`:**

"### Distribution: Internal

Your skill is committed to the project's `skills/` directory and ships with your code.

**Team members** will automatically have access when they pull the latest changes.

**To update team context:** Ensure all target files ({target-file-list}) are committed with the managed section updates."

**If `community`:**

"### Distribution: Community (Local)

Your skill is generated from an external dependency for local use.

**Location:** `{skills_output_folder}/{skill-name}/{version}/{skill-name}/`
**Scope:** This project only — not for publishing to agentskills.io

**Note:** Community skills are generated from third-party source code. Only `official` skills (generated by the library maintainer) should be published to the ecosystem."

### 3. Use It In This Project

Always show this section (regardless of `source_authority`) so the author can install the skill they just forged into the current project and try it immediately.

**Rendering rule for the command below — must be obeyed:** substitute `{resolved_skill_package}` with the actual resolved path before printing (do not leave the placeholder for the user to replace). The substituted path must be either absolute (starts with `/`) or `./`-prefixed. A bare relative path like `skills/foo/1.0.0/foo` is parsed by the `skills` CLI as `https://github.com/skills/foo.git` (org/repo GitHub lookup) and will fail with an authentication error. If `{resolved_skill_package}` resolves to a relative path, prefix it with `./` before emitting.

"### Use It In This Project

To install this skill into the current project right now, run:

```
npx skills add {resolved_skill_package}
```

For other source formats (registry name, git URL, tarball, etc.), see the **Installation → Source Formats** section at <https://www.npmjs.com/package/skills>.

If the installed skill's commands are not available in the same IDE session, reload plugins (e.g. for Claude Code users, run `/reload-plugins`) or restart your AI editor. Next time you will see the command `/{skill-name}` (e.g. `/{skill-name}`)."

### 4. Dry Run Reminder (If Applicable)

**If dry-run mode was active:**

"### Dry Run Complete

No context file, snippet, export manifest or result file was written, and no `on_complete` hook ran. To run the export for real:

**Re-run without `--dry-run`** to write all files."

### 5. Recommended Next Steps

"### Next Steps

- **audit-skill** — Run periodic integrity checks to detect drift between skill and source
- **update-skill** — After refactoring source code, regenerate the skill
- **test-skill** — Verify skill completeness and accuracy"

**Verification:** After export, inform the user how to verify the skill is active:
- Check that context files exist at the expected IDE paths
- Suggest testing by invoking the skill's trigger phrase in a new conversation
- If token budget was exceeded, note which skills were trimmed

### 6. Result Contract and Envelope

Build the run's `SKF_EXPORT_RESULT_JSON` envelope, and outside a dry run its result files, with the shared emitter `{emitEnvelopeHelper}` (resolved at SKILL.md On Activation §4). Pass the payload on stdin in a quoted heredoc, so no value is expanded, with each path written with `/` in place of `\` so every value stays a JSON string, and never type the envelope or a result file yourself:

```bash
uv run {emitEnvelopeHelper} emit --workflow skf-export-skill [--run-dir "{run_dir}"] [--result-dir "{skills_output_folder}"] <<'SKF_JSON'
{"status":"success","skills":["{skill-name}"],"context_files_updated":["{context_file}"],"manifest_path":"{manifest_path}","result_contract":{result_contract}}
SKF_JSON
```

- Pass `--run-dir` in a headless run: the emitter folds the auto-decisions the gates recorded there into `headless_decisions`, in the line and in the result file.
- **Without `--dry-run`:** pass `--result-dir`, and give `status` `"success"`, `skills` (every skill in `skill_batch`), `context_files_updated` (the files step 4 §9 wrote; `[]` with passive context off), `manifest_path` (the `{manifest_path}` step 4 §9b bound) and `result_contract` (below). The emitter writes the per-run record `export-skill-result-{YYYYMMDD-HHmmss}.json` in `{skills_output_folder}` (its name from the clock, with `-2`, `-3` and so on when a run already took that second), then its copy `export-skill-result-latest.json`, the record of the last run whose emitter wrote this copy, at a stable path; a caller reads its own run's `SKF_EXPORT_RESULT_JSON` line.
- **With `--dry-run`:** leave out `--result-dir` and `result_contract`, and give `status` `"dry-run"`, `skills`, `context_files_updated: []` and `manifest_path: null`. The emitter writes no file, so a dry run leaves `export-skill-result-latest.json` as the last real export wrote it.

The emitter derives `exit_code` (0) and `halt_reason` (null) and sets `result_path`: leave them out. Bind `{result_path}` ← the line's `result_path` (null on a dry run). When `{headless_mode}` is true, bind `{result_envelope_line}` ← the line and do not display it here: the shared health check displays it verbatim as the run's last line, so a `claude -p` caller reads the envelope as the final message. If the emitter exits non-zero, correct the payload field its stderr message names and run it once more; if it fails again, leave `{result_envelope_line}` empty, display "**Result contract not written:** {message}" and continue with `{result_path}` null.

`result_contract` follows `shared/references/output-contract-schema.md`; the emitter adds `timestamp`, `headless_decisions` and `warnings` to the record it writes, and `run_id` in a headless run:

```json
{
  "skill": "skf-export-skill",
  "status": "success",
  "outputs": [
    {"type": "skill", "path": "{resolved_skill_package}/context-snippet.md"},
    {"type": "config", "path": "{context_file}"},
    {"type": "manifest", "path": "{manifest_path}"}
  ],
  "summary": {
    "skills": ["{skill-name}"],
    "always_on_tokens": 0,
    "on_trigger_tokens": {"{skill-name}": 0}
  }
}
```

`outputs` holds one `skill` entry per file in `snippets_written` (step 4 §9c), one `config` entry per file in `context_files_updated` and the `manifest` entry. In `summary`, `always_on_tokens` is the managed section's `tokens` step 5 measured (`null` when step 5 found no managed section, as with passive context off), and `on_trigger_tokens` maps each skill to its `SKILL.md` `tokens` from step 5.

**`deviations[]` field (export-skill-specific extension):** when step 4 §4c.1 detected manifest-orphan managed rows and the operator (or `{headless_mode}`) chose **(b) Preserve verbatim**, also include a `deviations[]` array in `result_contract`. Each entry has the shape:

```json
{
  "kind": "preserve_external_skills",
  "skills": [
    {"name": "skill-name", "version": "1.0.0", "source_files": ["CLAUDE.md", ".cursorrules"]}
  ],
  "rationale": "managed-section row exists but no manifest entry / no source draft"
}
```

`source_files` per skill records the prior context files the orphan was found in (the §4c.1 multi-file scan deduplicates by `(skill, version)` and tracks which target context files originally carried the row — useful when an operator later debugs which IDE's managed section first introduced the external skill).

Other workflow choices that diverge from the strict spec path may add their own entries with a distinct `kind` value — auditors then have one place to look for "what did this run choose to do differently from the canonical flow." Omit the field when there are no deviations rather than writing an empty array, so the absence is readable as "ran the canonical path."

### 6b. Post-Export Hook (Optional)

Skip this section on a dry run (a dry run fires no hook), when `{onCompleteCommand}` (resolved at SKILL.md On Activation §3 from `workflow.on_complete`) is empty, the bundled default, and when `{result_path}` is null (§6 wrote no per-run record). Otherwise invoke it now, after the emitter wrote the per-run record:

```bash
{onCompleteCommand} --result-path="{result_path}"
```

Run it with a bounded timeout. On success, continue. On a non-zero exit, a timeout or any other failure, display "**Warning:** on_complete failed: {reason}" (for example `exit {N}: {stderr_first_line}`) and continue. **The hook must never fail the workflow:** it is integration glue (downstream distribution, notifier, pipeline chain), and a failure there is orthogonal to the export outcome. The warning is in neither the envelope nor the result file: the hook reads the result file, so both are written before it runs.

### 7. Chain to Health Check

When `{headless_mode}` is true, delete the `{run_dir}` folder: the run's envelope is built. ONLY WHEN the export summary, distribution instructions, result contract and envelope, and on-complete hook (or its skip) are complete will you then load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step: do not stop here even though the summary reads as final.
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