# X9 Okf Adapt

> Use when adapting an existing Markdown knowledge base to OKF v0.1 frontmatter while preserving document bodies byte-for-byte — «адаптируй папку под OKF», «добавь OKF frontmatter», "migrate docs to OKF". Do not use for rewriting document bodies, ordinary Markdown cleanup, or repository onboarding files unless the user explicitly includes them.

- **Type:** Skill
- **Install:** `agentstack add skill-xonika9-agent-skills-x9-okf-adapt`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [xonika9](https://agentstack.voostack.com/s/xonika9)
- **Installs:** 0
- **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [xonika9](https://github.com/xonika9)
- **Source:** https://github.com/xonika9/agent-skills/tree/main/skills/x9-okf-adapt
- **Website:** https://skills.sh/xonika9/agent-skills

## Install

```sh
agentstack add skill-xonika9-agent-skills-x9-okf-adapt
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# OKF adaptation

This is a low-freedom migration: frontmatter correctness and byte preservation are the contract. Use deterministic scripts for insertion and validation.

## Runtime and placement

The canonical source is the package-owned `skills/x9-okf-adapt` directory and the workflow supports Claude Code and Codex. Migration scripts require Python 3 and Ruby with Psych for strict YAML inspection. Git is optional: timestamp inventory falls back to filesystem modification time when Git history is unavailable.

## Scope contract

- Operate only on explicitly scoped Markdown files.
- Exclude generated/bulk directories and files according to [references/okf-format.md](references/okf-format.md).
- A complete header contains `type`, `title`, `description`, `tags`, and `timestamp`.
- A file with partial frontmatter belongs in repair scope; do not classify it as complete.
- Preserve every existing valid `type`, `title`, `description`, and `tags` value by default. A manifest fills missing or invalid fields; replacing a valid semantic field requires the explicit `--replace-existing-metadata` option. The script preserves a valid `timestamp` when meaning is unchanged and updates it automatically when an existing header receives a meaning-changing metadata repair.
- Preserve the original body bytes, BOM, and line-ending style. Header insertion is the only default mutation.
- Repository `AGENTS.md`, `CLAUDE.md`, and README changes belong to `x9-context-files-generator`; README files require `--include-readme`, and the other onboarding files stay outside this script even when integration is requested.

## Migration

1. Run `python3 scripts/check_dependencies.py` before inventory. Stop without editing documents when required dependencies fail; report Git fallback as `DEGRADED`, not blocked.
2. Snapshot candidate body hashes, line-ending/BOM metadata, and a deterministic suggested timestamp with `python3 scripts/insert_frontmatter.py  --inventory-out `. For a new header or a missing/invalid timestamp, the script uses the last Git change and falls back to file modification time. During repair it updates a valid timestamp automatically only when semantic metadata changes.
3. Build the worklist with `python3 scripts/validate_okf.py  --missing`; review exclusions and partial headers.
4. Derive concise metadata from the complete document. For very large files, use headings plus enough body context to support an accurate description; do not claim to have read the full body when you did not.
5. Insert or repair headers only through `python3 scripts/insert_frontmatter.py  --manifest  --inventory `, using an explicit metadata manifest. Existing valid core values win by default. Use `--replace-existing-metadata` only when the user explicitly requested changing them. Never use destructive Git restoration to undo an out-of-scope edit.
6. Run `python3 scripts/validate_okf.py  --inventory ` against the post-migration tree. It verifies all required fields, uniqueness rules, body hashes, BOM, and line endings.
7. Review the diff for header-only changes. Route onboarding-file changes separately if they were requested.

After changing the deterministic migration scripts, run `python3 scripts/test_okf.py` as their regression suite.

The metadata contract is in [references/okf-format.md](references/okf-format.md). Use [references/markup-agent-prompt.md](references/markup-agent-prompt.md) only to prepare metadata proposals; the agent never writes document bytes directly.

## Done

- Every in-scope file has five valid fields.
- Existing valid semantic metadata remained unchanged unless replacement was explicitly authorized; timestamp behavior matches the automatic meaning-change policy.
- Body hash, BOM, and line-ending checks pass against the pre-edit inventory.
- Exclusions and repaired partial headers are reported.
- No unrelated or onboarding file changed without explicit scope.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [xonika9](https://github.com/xonika9)
- **Source:** [xonika9/agent-skills](https://github.com/xonika9/agent-skills)
- **License:** MIT
- **Homepage:** https://skills.sh/xonika9/agent-skills

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-xonika9-agent-skills-x9-okf-adapt
- Seller: https://agentstack.voostack.com/s/xonika9
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.