Dx Harness
pproenca/dot-skills
Developer-experience friction auditing and fixing — slow onboarding, repeated manual setup steps, missing bootstrap/reset/seed scripts, undiscoverable conventions.
Restructure agent instruction artifacts (Claude Agent Skills, rules files, CLAUDE.md, playbooks) by applying five structural principles derived from the Open Knowledge Format - bounding the…
Install Okf Principles
$ npx skills add serradura/okf --skill okf-principles -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install serradura/okf okf-principles --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/serradura/okf.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/okf-principles .claude/skills/okf-principles && rm -rf skills-srcUse ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.
Claude Code skills documentation · loads skills from .claude/skills/
Install the "okf-principles" agent skill from https://github.com/serradura/okf/tree/main/skills/okf-principles into .claude/skills/okf-principles/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "okf-principles", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/serradura/okf/tree/main/skills/okf-principlesType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add serradura/okf --skill okf-principles -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install serradura/okf okf-principles --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/serradura/okf.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/okf-principles .agents/skills/okf-principles && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "okf-principles" agent skill from https://github.com/serradura/okf/tree/main/skills/okf-principles into .agents/skills/okf-principles/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "okf-principles", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add serradura/okf --skill okf-principles -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install serradura/okf okf-principles --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/serradura/okf.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/okf-principles .cursor/skills/okf-principles && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "okf-principles" agent skill from https://github.com/serradura/okf/tree/main/skills/okf-principles into .cursor/skills/okf-principles/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "okf-principles", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/serradura/okf.git --path skills/okf-principles--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add serradura/okf --skill okf-principles -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install serradura/okf okf-principles --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/serradura/okf.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/okf-principles .gemini/skills/okf-principles && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "okf-principles" agent skill from https://github.com/serradura/okf/tree/main/skills/okf-principles into .gemini/skills/okf-principles/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "okf-principles", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install serradura/okf okf-principlesInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add serradura/okf --skill okf-principles -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/serradura/okf.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/okf-principles .github/skills/okf-principles && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "okf-principles" agent skill from https://github.com/serradura/okf/tree/main/skills/okf-principles into .github/skills/okf-principles/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "okf-principles", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add serradura/okf --skill okf-principles -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install serradura/okf okf-principles --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/serradura/okf.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/okf-principles .opencode/skills/okf-principles && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "okf-principles" agent skill from https://github.com/serradura/okf/tree/main/skills/okf-principles into .opencode/skills/okf-principles/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "okf-principles", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
okf-principles- GitHub stars
- 178
- Token cost
- ~994 tokens
- SKILL.md length
- 442 words
- Files
- 6 (incl. references)
- Skills in repo
- 2
- Repo updated
- First seen
- Licence
- Apache-2.0
At a glance
Restructure agent instruction artifacts (Claude Agent Skills, rules files, CLAUDE.md, playbooks) by applying five structural principles derived from the Open Knowledge Format - bounding the…
- Works in 6 steps: Inventory: list every file, its line… → Split along question boundaries, not… → Write the index per index-first. Every → …
- The user wants to split a monolithic skill
- SKILL.md covers The five principles, Procedure for restructuring an… and Anti-goals
- Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
What it does
Okf Principles is an agent skill from serradura/okf. Restructure agent instruction artifacts (Claude Agent Skills, rules files, CLAUDE.md, playbooks) by applying five structural principles derived from the Open Knowledge Format - bounding the worst-case context a question loads (the mean may rise; the win is the tail and answer accuracy) and making cross-references survive rewrites. Use this skill whenever the user wants to split a monolithic skill or reference file, reduce context loaded per question, add an index layer, make cross-references survive rewrites, or…
Its SKILL.md is about 990 tokens, which your agent loads only when the skill is triggered. The skill folder holds 6 other files, including reference files (for example `references/index-first.md`, `references/keyed-identity.md` and `references/kind-over-location.md`).
It sits in Agent Workflows, covering Agent instruction files. It works with Docker. The repository describes itself as: OKF (Open Knowledge Format): Durable, structured memory for AI agents. Author, validate, consume, and maintain portable knowledge bundles through an ecosystem of Skills, MCP, an… The licence is Apache-2.0.
When your agent uses it
- The user wants to split a monolithic skill
- Reduce context loaded per question
- Add an index layer
- Make cross-references survive rewrites
Example prompts
- “/okf-principles”
Workflow steps
6 steps, taken from the first numbered list in SKILL.md.
- Inventory: list every file, its line count, and what questions it
- Split along question boundaries, not size. Each resulting file should
- Write the index per index-first. Every
- Key every rule worth citing per
- Add reader guidance per
- Verify against the anti-goal with a fixed question set, judging the
What it can do on your machine
Read from SKILL.md and the folder at commit cfb7ffa. It shows what the files ask for, not the result of running them.
Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
No scripts in the folder and no shell commands in SKILL.md.
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Context cost
Okf Principles loads about 994 tokens when it runs, and up to ~3.3k if it reads all its reference files. Until then it costs about 175 tokens; SKILL.md has 442 words of instructions outside code blocks.
Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.
Safety
Auto-check passed
The automated check found no risky patterns in SKILL.md.
Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.
SKILL.md
The full file from serradura/okf at commit cfb7ffa, republished under its Apache-2.0 licence (© serradura). 442 words, ~994 tokens.
Download SKILL.mdSave it as
.claude/skills/okf-principles/SKILL.md (or your agent's skills folder). This skill also uses 5 other files; get the full folder from GitHub.- name
- okf-principles
- description
- Restructure agent instruction artifacts (Claude Agent Skills, rules files, CLAUDE.md, playbooks) by applying five structural principles derived from the Open Knowledge Format - bounding the worst-case context a question loads (the mean may rise; the win is the tail and answer accuracy) and making cross-references survive rewrites. Use this skill whenever the user wants to split a monolithic skill or reference file, reduce context loaded per question, add an index layer, make cross-references survive rewrites, or audit a skill's structure for efficiency. Also use it when the user mentions progressive disclosure, token-efficient skills, or restructuring instructions for agents.
okf-principles
Restructures instruction artifacts so an agent loads only what a question needs. The measured payoff is the tail, not the average: a split bounds the worst-case context per question and removes the cheap confident wrong answers blind scrolling produces - mean bytes may rise slightly, and that is not a failure. This file is the index: read the one principle file the task calls for, not all five.
The five principles
- Index first - the reader decides what to load, so structure must be inspectable before it is consumed. Read when splitting a monolith, writing an index, or indexing a vendored or generated file you cannot edit.
- Keyed identity - references are keyed, never positional, because agents rewrite. Read when adding rule IDs or fixing cross-references before a file move.
- Permissive reading - partial structure must still work. Read when writing reader-side instructions or migrating incrementally.
- No tooling required - plain text that survives being read as prose. Read when tempted to add a format, schema, or parser.
- Kind over location - a file declares what it is; folders are free to change. Read when organizing directories or labeling index entries.
Procedure for restructuring an existing skill
- Inventory: list every file, its line count, and what questions it answers. A file answering unrelated questions is a split candidate. Mark any file that is vendored, generated, or third-party: those are never split - they get an index beside them instead (see rule ss-index-beside-foreign).
- Split along question boundaries, not size. Each resulting file should answer one family of questions (per verb, per workflow, per format).
- Write the index per index-first. Every entry needs a description an agent can route on, and coverage must match the index's claim - especially for an index promoted from inside a file, which inherits its old host's narrower scope silently (rule ss-coverage-matches-claim).
- Key every rule worth citing per keyed-identity, then repoint existing cross-references at keys instead of paths and section names.
- Add reader guidance per permissive-reading so a half migrated state stays usable.
- Verify against the anti-goal with a fixed question set, judging the worst question rather than the mean (rule ss-measure-worst-case): one that loads more files or bytes than before names the boundary to merge back. Where a topic moved between files, leave a pointer at the old seam (rule ss-seam-pointers).
Show full SKILL.md (60 more words)Show less
Anti-goals
Do not port machine-oriented metadata (trust tiers, provenance chains,
attestation, changelogs) into a skill. Those solve multi-agent corpus
problems; a skill has one author and lives in version control. Do not
add frontmatter keys beyond what the host harness defines unless a
machine must read them; prefer expressing structure in the index body,
which no harness parses. <!-- rule: ss-no-ceremony -->
© serradura, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Files
SKILL.md and 5 other files (references) in skills/okf-principles of serradura/okf.
- SKILL.md
- references/index-first.md
- references/keyed-identity.md
- references/kind-over-location.md
- references/no-tooling.md
- references/permissive-reading.md
Open the folder on GitHubat commit cfb7ffa
Compare with similar skills
Okf Principles next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Okf Principles this skillserradura/okf | 178 | — | ~994 | Automated safety check: Pass | Apache-2.0 | |
| Dx Harnesspproenca/dot-skills | 215 | — | ~1.5k | Automated safety check: Pass | MIT | |
| Codigo Automacaoricneves-ai/flowgrammers-skills | 115 | — | ~2.3k | Automated safety check: Notes | MIT | |
| Using Agent Skillsaddyosmani/agent-skills | 104k | 4 repos | ~2.4k | Automated safety check: Pass | MIT | |
| Claude ReflectBayramAnnakov/claude-reflect | 1.8k | 2 repos | ~627 | Automated safety check: Pass | MIT | |
| Neat-Freak Knowledge CloseoutKKKKhazix/khazix-skills | 21k | — | ~1.9k | Automated safety check: Pass | MIT |
Similar skills
Codigo Automacao
ricneves-ai/flowgrammers-skills
Skills para desenvolvimento de software, debug, APIs, automações no-code e uso avançado de ferramentas de IA para desenvolvimento.
Using Agent Skills
addyosmani/agent-skills
Meta-skill for choosing which workflow skill fits the task at hand, plus always-on habits: surface assumptions, stop on confusion, push back, keep it simple and stay in scope.
Claude Reflect
BayramAnnakov/claude-reflect
Self-learning system that captures corrections during sessions and reminds users to run /reflect to update CLAUDE.md.
Neat-Freak Knowledge Closeout
KKKKhazix/khazix-skills
Brings project docs, agent rule files, authorized memory and leftover workspace files back in line with what the code and runtime actually do at the end of a work session.
Writing For Agents
bestofjs/bestofjs
Writing documents for agents. An agent skill from bestofjs/bestofjs.
More from serradura/okf
Okf
serradura/okf
Be the expert on Open Knowledge Format (OKF) — portable project knowledge as a directory of markdown files with YAML frontmatter that humans and agents read from one source.
Related
Works with
Categories
Questions about Okf Principles
What does Okf Principles do?
Restructure agent instruction artifacts (Claude Agent Skills, rules files, CLAUDE.md, playbooks) by applying five structural principles derived from the Open Knowledge Format - bounding the…. Okf Principles is an agent skill from serradura/okf.md, playbooks) by applying five structural principles derived from the Open Knowledge Format - bounding the worst-case context a question loads (the mean may rise; the win is the tail and answer accuracy) and making cross-references survive rewrites.
When should I use Okf Principles?
Okf Principles fits situations like: the user wants to split a monolithic skill; reduce context loaded per question; add an index layer; make cross-references survive rewrites.
How do I install Okf Principles in Claude Code?
Run `npx skills add serradura/okf --skill okf-principles -a claude-code`. Or copy the skill folder (skills/okf-principles in serradura/okf) into .claude/skills/okf-principles in your project. Claude Code loads it when a task matches its description.
How do I install Okf Principles in Codex?
Run `npx skills add serradura/okf --skill okf-principles -a codex`. Or copy the skill folder (skills/okf-principles in serradura/okf) into .agents/skills/okf-principles in your project. Codex loads it when a task matches its description.
Can I use Okf Principles in Cursor, Gemini CLI or GitHub Copilot?
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add serradura/okf --skill okf-principles -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/okf-principles, .gemini/skills/okf-principles, .github/skills/okf-principles and .opencode/skills/okf-principles in your project.
What does Okf Principles need to run?
SKILL.md names no scripts, command-line tools or credentials: Okf Principles is instructions for the agent only.
Does Okf Principles access the network?
SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.
Is Okf Principles safe to install?
Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.
What licence does Okf Principles use?
Okf Principles is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.
How many tokens does Okf Principles use?
About 994 tokens (SKILL.md is roughly 4k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 2.4k tokens, read only when the agent opens those files.
What are the alternatives to Okf Principles?
Skills that share tags, products or a category with Okf Principles: Dx Harness (pproenca/dot-skills, 215 stars), Codigo Automacao (ricneves-ai/flowgrammers-skills, 115 stars), Using Agent Skills (addyosmani/agent-skills, 104k stars) and Claude Reflect (BayramAnnakov/claude-reflect, 1.8k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains Okf Principles?
serradura (a GitHub user) maintains it in serradura/okf, which has 178 GitHub stars. The repository holds 2 skills in this directory. The repository was last updated on September 6, 2026.
Source: serradura/okf on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.