armelhbobdad/oh-my-skills / .claude/skills/skf-export-skill
skf-export-skill
VerifiedExports 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."
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.5 KB |
| assets/managed-section-format.md | markdown | 7.1 KB |
| assets/snippet-format.md | markdown | 6.1 KB |
| customize.toml | config | 3.8 KB |
| references/generate-snippet.md | markdown | 14.0 KB |
| references/health-check.md | markdown | 1.2 KB |
| references/invocation-contract.md | markdown | 3.3 KB |
| references/load-skill.md | markdown | 19.8 KB |
| references/manifest-rebuild.md | markdown | 3.5 KB |
| references/multi-skill-mode.md | markdown | 3.1 KB |
| references/orphan-context-detection.md | markdown | 6.0 KB |
| references/orphan-row-detection.md | markdown | 7.3 KB |
| references/package.md | markdown | 1.6 KB |
| references/preflight-snippet-root-probe.md | markdown | 7.1 KB |
| references/result-envelope.md | markdown | 5.1 KB |
| references/summary.md | markdown | 11.5 KB |
| references/token-report.md | markdown | 7.0 KB |
| references/update-context.md | markdown | 16.7 KB |
references/orphan-context-detection.md
View on GitHub---
# Static reference loaded by update-context.md §3b only when
# `orphaned_context_files` is non-empty (i.e. the cheap pre-check in
# §3b found a context file on disk with an SKF managed section that
# is no longer in the current `target_context_files`). The reference
# carries the (a)/(b)/(c) gate protocol, headless default, and
# downstream-state contract; the trigger detection itself stays
# inline in §3b so the LLM knows when to invoke this protocol.
---
<!-- Config: communicate in {communication_language}. Render the orphan list and gate prompt in {document_output_language}. -->
# Orphan Context-File Detection — Gate Protocol
## Purpose
Handle the (a) clear / (b) keep / (c) rewrite gate when one or more known context files (`CLAUDE.md`, `.cursorrules`, `AGENTS.md`) on disk contain an SKF managed section but their owning IDE is no longer listed in `config.yaml.ides`. Loaded by `update-context.md` §3b after the cheap pre-check populates `orphaned_context_files`.
## Inputs
- `orphaned_context_files` — list of `{context_file, file_path}` entries built by §3b's pre-check
- `target_context_files` — current export's IDE → context-file map (from step 1)
- `{headless_mode}` — boolean flag from workflow context
## Gate Protocol
Emit the warning and gate:
> **Orphaned context files detected.** The following files contain SKF managed sections but no configured IDEs target them:
> {list: context file → file path}
>
> The managed sections in these files are stale. Options:
>
> - **(a) clear** — remove the SKF managed section from each orphaned file (surgical marker replacement, leaves user content intact)
> - **(b) keep** — leave them untouched (they will remain stale until you re-add an IDE that targets this file or delete the file)
> - **(c) rewrite** — also rewrite the orphaned files with the current skill index (use this if the IDE was removed by mistake)
Wait for user choice.
**GATE [default: b]**, headless or non-interactive: when `{headless_mode}` (or dry-run, or unattended), default to **(b) keep** and print the warning only: no destructive action without explicit consent.
When `{headless_mode}` is true, also record the decision in the run sink, listing each orphaned file's `file_path` with `/` in place of `\` so it stays a JSON string. If `record` exits non-zero, display its error line and go on (a failed `record` never stops the run):
```bash
uv run {emitEnvelopeHelper} record --workflow skf-export-skill --run-dir "{run_dir}" --decision <<'SKF_JSON'
{"gate":"update-context.orphan-context-files","default_action":"b","taken_action":"b","reason":"headless: orphaned context files kept untouched","evidence":{"files":["{file_path}"]}}
SKF_JSON
```
## Choice handling
### (a) clear
The marker excision is deterministic surgery with one correct answer per input: a mis-parsed boundary silently corrupts the user's surrounding content. Delegate it to the tested `clear` action of `skf-rebuild-managed-sections.py`, the same helper `update-context.md` §9 writes the section with; do not excise markers in-prompt. `{rebuildManagedSectionsHelper}` is the path SKILL.md's On Activation resolved, and activation halts (exit code 4, `halt_reason: "context-rebuild-failed"`) when no candidate exists: falling through to an in-prompt excision would regress the atomic-write + post-clear verify guarantee.
For each file in `orphaned_context_files`:
1. Run:
```bash
python3 {rebuildManagedSectionsHelper} {file_path} clear
```
The `clear` action removes the entire `<!-- SKF:BEGIN -->`…`<!-- SKF:END -->` block (and its surrounding blank lines), leaves the rest of the file intact, and performs an atomic temp-file + rename write with a post-clear verify that the section is gone. Treat any non-zero exit (or a `status: "error"` envelope) as a clear failure — HALT (exit code 4, `halt_reason: "context-rebuild-failed"`) reporting `{file_path}: {captured stderr}`. This branch is interactive-only (the headless default is (b) keep), so it emits no result envelope here.
2. On success (`status: "ok"`, `action: "cleared"`), append the file path to `orphans_cleared`. On a non-empty list, record it in the §6 result contract as a `deviations[]` entry (`kind: "clear_orphan_context"`, `files: [...]`) — the extensible deviations mechanism summary.md §6 documents for choices that diverge from the canonical export path.
### (b) keep
Record nothing. The orphaned files remain on disk, untouched. Proceed.
### (c) rewrite
Add each entry in `orphaned_context_files` to a separate `rewrite_context_files` list. This list is kept distinct from `target_context_files` so the user's intent to only export to configured IDEs is preserved in the manifest update at §9b: `rewrite_context_files` joins the §4 to §9 writes for this run only and is not promoted into the manifest's `ides` arrays.
Use `.agents/skills/` as the default skill root for rewritten orphans (the IDE-neutral path used when the original IDE mapping is no longer available).
Record each rewritten file in `orphans_rewritten`. On a non-empty list, record it in the §6 result contract as a `deviations[]` entry (`kind: "rewrite_orphan_context"`, `files: [...]`) — the same extensible deviations mechanism summary.md §6 documents.
## Downstream contract
After this protocol completes, §3b returns control to §4 with these workflow-context variables populated:
- `orphans_cleared: []` — set when the user chose (a) or stayed empty otherwise
- `orphans_rewritten: []` — set when the user chose (c) or stayed empty otherwise
- `rewrite_context_files: []`: joins the targets of §4 to §9 when the user chose (c)
§4 to §9 run over `target_context_files + rewrite_context_files`. The §9b manifest update reads only `target_context_files` (rewritten orphans are not promoted into the manifest).
## Scope note
This cleanup only runs during interactive export (and the headless default explicitly does nothing destructive). Drop-skill and rename-skill operate on the manifest's declared context files and are not responsible for orphan detection — their scope is the active manifest, not arbitrary on-disk markers.
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 |