open-skills

# open-skills

Version: 1.8.0

> Reusable, inspectable skills for AI coding agents (Claude Code, Codex, any runtime that reads the open Agent Skills format). Every skill has a readable SKILL.md; 40 of 70 also carry a protocol.yon — a declarative, mechanically validatable account of steps, rules, and gates. Validation proves the declared structure, not runtime obedience. Apache-2.0. Read before you trust.

## About YON (YounndAI Object Notation™)
The protocol.yon files are written in YON (https://github.com/YounndAI/yon), a stream-first data format for AI-agent workflows with a public spec (https://github.com/YounndAI/yon-spec) and an Apache-2.0 reference parser (@younndai/yon-parser). YON makes a skill's declared rules (MUST / MUST_NOT) and gates (ABORT / WARN) inspectable as named, typed objects; it does not enforce runtime obedience.

## For agents — how to install
No build step, no opaque installer. Follow these in order; the checks in step 4 are the ones that matter, because every failure mode here is SILENT.
0. Clone this repo and work from its root: `git clone https://github.com/allemaar/open-skills && cd open-skills`. Every relative path below is from that root.
1. Enumerate skills from catalog.json (repo root) — each record carries name, description, triggers, gates, requiresSkills, companion classification, and install commands.
2. Choose SKILLS_DIR — the ONE directory the user's runtime actually reads. These are not interchangeable, and choosing wrong fails silently: no error, the skill simply never appears.
   - ~/.claude/skills — Claude Code, which reads this dir and no other — it does not read ~/.agents/skills
   - ~/.agents/skills — the shared cross-runtime dir — Codex (its current location), Cline, Zed, Warp
   - ~/.codex/skills — Codex — its older path, still read for backward compatibility
   Other tools use a dir of their own (Cursor ~/.cursor/skills, Copilot ~/.copilot/skills). If you cannot establish which runtime you are running in, ASK the user — do not guess. NOTE: SKILLS_DIR already ends in `/skills`. Every step below uses `$SKILLS_DIR/<name>` and never appends `/skills` a second time.
3. Resolve `requiresSkills` recursively for the requested skill. Install that dependency graph dependency-first before the requested skill. A missing dependency or cycle means STOP; report the invalid catalog instead of guessing an order.
4. CHECK every skill in that order before you write. Both of these, in order — neither condition raises an error on its own, so if you skip the check you will not find out:
   a. `test -e "$SKILLS_DIR/<name>"` — if it exists, the user already has this skill. ASK before replacing it. Do NOT just copy: `cp -r` onto an existing directory does not fail, it nests a second copy INSIDE it and leaves the old SKILL.md exactly where the runtime will keep reading it.
   b. `test -L "$SKILLS_DIR/<name>"` (PowerShell: `(Get-Item -Force "$SKILLS_DIR/<name>").LinkType`) — if it is a symlink or junction, STOP and ask. Copying through it writes into whatever it points at, outside the skills dir, and exits 0 while doing so. Remove the link itself (`rmdir` on Windows, `unlink` on POSIX) — never delete or copy through it.
5. COPY each folder in dependency-first order (copy-default, never symlink): `cp -r skills/<name> "$SKILLS_DIR/<name>"` (Windows PowerShell: `Copy-Item -Recurse skills/<name> "$SKILLS_DIR/<name>"`). Required companions are contained in that folder and travel with it; optional companions in catalog.json are repository or sibling enhancements and do not block the core skill when absent. If the copy fails because SKILLS_DIR itself does not exist, create exactly that directory and retry — do not invent a different path to make the command succeed.
6. If it ships a protocol.yon, validate it: `npx @younndai/yon-parser validate "$SKILLS_DIR/<name>/protocol.yon" --profile <profile>` (profile is in catalog.json).
   EXPECT exit 0 and `✓ <the path you passed>: Valid` — the parser echoes the full path, so match on `: Valid` and the exit code, not on a fixed string. Anything else — a parse error, a non-zero exit — means STOP: report the output to the user and do not claim the skill installed cleanly.
7. VERIFY, then report the path: `$SKILLS_DIR/<name>/SKILL.md` exists and its first line is `---`. Tell the user the exact directory you installed into — that is what decides which runtime can see it. (This confirms the copy landed; it cannot tell you SKILLS_DIR was the right dir. Step 2 is what gets that right.)
That is the basic install: copy a readable folder, then optionally validate its declarative protocol. The npx validation command may download and execute the separately published parser package; inspect that boundary before using it.
Updating later: these are frozen copies — they do not change until you re-copy. `git pull` in the clone, then diff before you accept: `git diff --no-index "$SKILLS_DIR/<name>" skills/<name>` — silence means identical; read anything it prints before re-copying. Do NOT filter that diff. A `cp -r` install carries no `metadata:` provenance block, so filtering those lines buys nothing and would hide one APPEARING — which is a change you want to see, since that block is an unsigned claim other tooling will act on.

## Skills by family

### Planning & execution
- freshness-contract [md-only] — Categorical decision table for reusing cached evidence — when an artifact you already read, a banked test result, a primer, a worker report, or a probe verdict is still trustworthy, and when it must be spot-checked or re-verified. — triggers: /freshness-contract, is this still current, can I trust what I read earlier, do I need to re-check this
- plan-cleanup [protocol.yon] — Post-execution cleanup — remove planning artifacts and tech debt left behind after a plan runs. — triggers: /plan-cleanup, clean up artifacts, remove the plan file, no tech debt
- plan-create [protocol.yon] — Propose a phased, gated implementation plan before any work begins. — triggers: /plan-create, make a plan, plan this out, design before coding
- plan-deep-dive [protocol.yon] — Phase-by-phase deep inspection of any multi-phase plan — stop at each phase and assess completeness, quality, and future-readiness before advancing. — triggers: /deep-dive, do a deep dive, inspect each phase, look at this more carefully
- plan-evolve [md-only] — Evolve a target to its next version — treat what shipped as v1, plan the next iteration. — triggers: what would v2 look like, evolve this, what's next for this, next iteration of this
- plan-execute [protocol.yon] — Apply the last approved plan exactly. — triggers: /execute, execute the plan, implement this, do it
- plan-phases [protocol.yon] — Restructure an existing plan into phases with /verify gates after each phase and critical outcomes, plus blocking pre-action gates for safety prerequisites. — triggers: /phase-plan, add phases to this plan, gate this plan, restructure the plan
- reflect [md-only] — Lightweight cognitive pause — surface assumptions, uncertainty, and what you'd do differently. — triggers: /reflect, step back and think before continuing
- verify [protocol.yon] — Formal phase gate — checks intent, plan, and execution artifacts for drift, then actively re-checks each load-bearing claim against its source (an agent's self-report of having checked is not evidence). — triggers: /verify

### Insight & decision
- cold-review [protocol.yon] — Run outside-agent review of actual work artifacts against objectives, with classification, fresh reviewer lenses, evidence-based findings (re-opened at synthesis, not recalled), scoring, and thresholds; the review self-verifies its own findings before returning. — triggers: /cold-review, cold review this, get outside review, have fresh agents inspect this work
- double-check [protocol.yon] — Targeted re-verification of a specific claim, output, or decision. — triggers: /double-check, verify this, re-check this, are you sure about this
- insight-adversarial [protocol.yon] — Multi-pass adversarial critique from dynamically selected personas — including Claude's own POV. — triggers: /insight-adversarial, adversarial, red team this, multi-POV review
- insight-angles [protocol.yon] — Angle & connection discovery engine. — triggers: /insight-angles, find unseen angles, what connections am I missing, what are we not seeing
- insight-assess [protocol.yon] — Structured decision evaluation — pros/cons, impact assessment, quality analysis, recommendation. — triggers: /assess, /insight-assess
- insight-critique [protocol.yon] — Advisory review workflow. — triggers: /critique, review this, critique this, what's wrong with this
- insight-cross-examine [protocol.yon] — Context-routed deliberation engine. — triggers: /insight-cross-examine, cross-examine this, weigh these options, pick between these and recommend
- insight-explore [protocol.yon] — Brainstorm 3+ possible implementations before committing. — triggers: /explore, brainstorm options, what are the ways to do this, explore approaches
- insight-retro [protocol.yon] — Post-implementation retrospective — map blast radius, audit documentation, extract skills, update KIs, document lessons learned. — triggers: /retro, retrospective, post-mortem, lessons learned
- insight-skill-gap [protocol.yon] — Scan recent work and identify if new skills should be created or existing ones updated. — triggers: /skill-gap, check for skill gaps, what skills should we add, did we miss anything worth capturing
- investigate [protocol.yon] — Gather facts (files, deps, patterns) without making changes. — triggers: /investigate, look into this, explore the codebase, understand how this works

### Priming
- extract-signal [protocol.yon] — An elastic signal-extraction methodology run under /multi-agent-mode. — triggers: /extract-signal, extract the signal on X and present it as Y, gather + vet + report the signal about X
- prime-expand [protocol.yon] — Expand a vague gap into concrete questions + named source candidates via a delegated sub-agent — caller sees only the proposed pair for confirm/edit/refuse, never the expansion reasoning. — triggers: /prime-expand, expand on this
- prime-fetch [protocol.yon] — Run a noisy data-fetching tool call (Grep, Glob, WebFetch, MCP search) on the caller's behalf in a sub-agent's context — only the filtered, proof-of-work-verified digest enters the caller's window. — triggers: /prime-fetch
- prime-sweep [protocol.yon] — Prime the calling agent with high-signal context from large source surfaces (multiple files, packages, folders) via parallel delegated sub-agents. — triggers: /prime-sweep

### Skill library
- directives-audit [md-only] — Audit or explicitly housekeep agent directives for authority, scope, safety, density, routing, drift, and consumed parity. — triggers: /directives-audit, audit these directives, boil my directives, directive housekeeping
- new-skill-creator [protocol.yon] — Scaffold a new Agent Skill end-to-end into a skills repo you maintain (folder, SKILL.md, optional protocol.yon for dual-doc skills, tri-runtime links for Claude Code + Codex + the shared .agents/ dir, commit and push). — triggers: /new-skill-creator, create a skill, make a new skill for X, add a slash command
- next-skills [protocol.yon] — The Next Skills protocol (NSP). — triggers: /next-skills
- self-improve [protocol.yon] — The Self-Improvement Protocol (SIP). — triggers: /self-improve, /self-improve [skill]
- skills-audit [md-only] — Audit or explicitly housekeep an Agent Skill or library for instruction quality, routing, decomposition, portability, dependencies, and consumed behavior. — triggers: /skills-audit, audit this skill, audit my skills, boil this skill
- skills-help [md-only] — The skills library menu — every skill grouped by family, each with a one-line description and a dual-doc/single-doc marker; pass a family name to drill into one family in full detail. — triggers: /skills-help, /skills-help {family}, list my skills, which skill for X

### Orchestration & dispatch
- agent-mailbox [protocol.yon] — Two or more agents — any harness, any vendor — collaborate through any shared folder: share a folder, load the skill, point at it. — triggers: /agent-mailbox, handshake with the other agent, collaborate through this inbox, listen for the other agent's reply
- ask-gate [protocol.yon] — The Ask-Gate Protocol (AGP). — triggers: /ask-gate
- budget-check [protocol.yon] — Pre-wave usage gate. — triggers: /budget-check
- caller-options [protocol.yon] — The Caller Options protocol (COP). — triggers: /caller-options
- handoff [protocol.yon] — Generate a structured cold-agent handoff brief (YAML frontmatter + Obsidian markdown + YON blocks) that any fresh LLM session can pick up and execute. — triggers: /handoff, create a handoff, dispatch to a fresh agent, hand this to a cold session
- handoff-execute [protocol.yon] — Execute a handoff brief with enforced source-read discipline — load the brief's @SOURCES.required tier fully before planning, cite sources per plan step, run @OUTCOME.verify after, emit the retro per @GROUND_TRUTH_REQUIRED. — triggers: /handoff-execute, /handoff-execute <brief-path>
- multi-agent-mode [md-only] — Activate multi-agent mode: the lead agent still works directly but delegates independent helper slices when useful. — triggers: /multi-agent-mode, multi-agent mode, use helper agents, work with subagents
- orchestrate-mode [md-only] — Activate orchestrator mode in the current session: the lead agent dispatches governed worker subagents and does not execute concrete work directly. — triggers: /orchestrate-mode, become an orchestrator, orchestrator mode, delegate everything
- route-task [md-only] — EXPERIMENTAL capability-routing rubric — score a task on five task-readable axes (Risk, Uncertainty, Scope, Coupling, Verification) to derive WHO should execute (capability band 0–3) and HOW HARD they should try (volume 0–24), plus an evidence-derived plan gate. — triggers: /route-task, which model should handle this, how should I route this task, score this task

### Orientation
- orient-gaps [protocol.yon] — Answers "What is stuck or missing?" on any subject — blockers (on you vs on others), open forks, loose ends, and inferred silent gaps, computed fresh via a bounded read-only subagent. — triggers: /orient-gaps, what's stuck, what's not done, what's missing here
- orient-map [protocol.yon] — Answers "What changed since I last looked?" on any subject — the delta since your last look, plus done → here → next as a path on trunk or a TREE on a branch, computed fresh via a bounded read-only subagent. — triggers: /orient-map, show me the map, what changed since last look, how deep down this branch am I
- orient-roadmap [protocol.yon] — Answers "What comes next, and what gates it?" on any subject — the increment arc (built → current → next), what shipped now, the gates, the next increment's clusters (paramount starred), and the runway of stage boxes (now → gated-next → future) plus the deferred lanes, computed fresh via a bounded read-only subagent. — triggers: /orient-roadmap, show me the roadmap, show me the runway, what's next
- orient-status [protocol.yon] — Answers "How far along am I, and when will it be done?" on any subject (repo, folder, plan, task) — current position, what's left, and a banded ETA, computed fresh via a bounded read-only subagent. — triggers: /orient-status, where are we on this, status quo and eta, how far along

### Human output
- agent-output [md-only] — Compact agent-to-agent communication contract for worker reports, handoffs, status, blockers, and review findings. — triggers: /agent-output, brief the worker, make agent reports terse, compress the subagent report
- human-draw [md-only] — Renders information as a picture a person reads at a glance. — triggers: /human-draw, draw this, draw it for me, show me this visually
- human-merge [md-only] — Takes several separate reports — from several agents, several sources, or several documents — and returns one surface a person can decide from. — triggers: /human-merge, merge these reports, combine what the agents found, what do all of these add up to
- human-output [md-only] — The contract for writing anything a person will read and decide from — a report, a finding, an answer, a request for a decision. — triggers: /human-output, remember I am a person not a machine, write this for a human, keep the reader in mind
- human-rewrite [md-only] — The repair pass on text that already exists — an agent's own last output, a subagent's report, a supplied document, a research summary, a legal or medical paragraph — rewritten so a person can read it fast and act on it, without changing what it claims. — triggers: /human-rewrite, translate that into human, that was a wall of text, I can't follow this
- prose-audit [md-only] — Diagnose semantic repetition, filler, fake structure, stock AI rhetoric, and avoidable reading load in existing text. — triggers: /prose-audit, find the AI filler, audit this for bloat, identify repetition and token padding
- synthesize [md-only] — Turn agent output into faithful, scannable, purpose-matched delivery. — triggers: /synthesize, synthesize this, make this scannable, I can't read this wall
- synthesize-init [md-only] — Opt-in installer for a minimal standing /synthesize route in existing agent directive files. — triggers: /synthesize-init, make synthesize my default, wire synthesize into my directives, inject synthesize

### Code & architecture
- audit-coupled-constant [md-only] — Audit every site of a constant whose value is duplicated across multiple call sites (retry budgets, timeouts, page sizes, magic numbers, feature flags). — triggers: /audit-coupled-constant, audit budget consistency, find all sites of this value, check coupled invariant
- design-an-interface [md-only] — Generate multiple radically different interface designs for a module, then compare and synthesize. — triggers: /design-an-interface, design an API, explore interface options, compare module shapes
- improve-codebase-architecture [protocol.yon] — Explore a codebase to find opportunities for architectural improvement by deepening shallow modules (John Ousterhout, "A Philosophy of Software Design"). — triggers: /improve-codebase-architecture, improve architecture, find refactoring opportunities, make this more testable
- monorepo-deps [protocol.yon] — End-to-end syncpack + manypkg flow for an npm monorepo: check, fix, update, and maintain `.syncpackrc.json`. — triggers: /monorepo-deps, update deps, sync deps, check deps

### Obsidian & vault
- json-canvas [md-only] — Create and edit JSON Canvas files (.canvas) with nodes, edges, groups, and connections. — triggers: make a canvas, build a mind map, draw a flowchart in Obsidian, add nodes to this canvas
- map-check [md-only] — The honest inspector for Map Your Knowledge — read-only conformance checks of an organized scope via a small bundled script, always reporting what was checked AND what was not; it can never claim an unqualified "all clear". — triggers: /map-check, check this map, check the graph, is this vault healthy
- map-init [md-only] — Install or remove the MYK directive route on selected agent surfaces. — triggers: /map-init, install map your knowledge, set up myk, make mapping my agents' default — requires: map-rules, map-this
- map-maintain [protocol.yon] — Run one bounded MYK stewardship cycle: map-check, Handler-selected repairs through map-this semantics, then targeted recheck. — triggers: /map-maintain, maintain this map, tend this graph, repair these map findings — requires: map-rules, map-check, map-this
- map-rules [md-only] — Route every governed Markdown organization operation, including unstructured or candidate assessment, to required Map Your Knowledge rules before reasoning. — triggers: /map-rules, follow my map rules, structure this note, organize vault data
- map-this [md-only] — Plan and organize a bounded folder, project, or vault using map-rules; audit first, show simple proposals, and apply only selected changes. — triggers: /map-this, organize this scope, map this project, housekeep this vault — requires: map-rules
- obsidian-bases [md-only] — Create and edit Obsidian Bases (.base YAML files) with views, filters, formulas, and summaries. — triggers: make a base, build a database view of my notes, add a filter/formula to this base, create a table/card view
- obsidian-cli [md-only] — Drive a running Obsidian instance via the `obsidian` CLI — search vault, open/create/move notes, toggle tasks, edit properties, reload plugins, run JS, capture errors/screenshots. — triggers: search my vault, open this note in Obsidian, list notes tagged X, reload my plugin
- obsidian-markdown [md-only] — Write valid Obsidian-Flavored Markdown — wikilinks, embeds, callouts, frontmatter properties, tags, comments. — triggers: write this as an Obsidian note, add a callout, use wikilinks, set frontmatter properties

### YON
- yon-read [md-only] — Read, interpret, or explain existing YON content. — triggers: read this YON, what does this YON mean, explain this @DOC/@RULE/@STEP, summarize this YON
- yon-write [md-only] — YON Writing & Compilation Mode. — triggers: write YON, convert to YON, create a .yon file, encode this as YON

### Web
- defuddle [md-only] — Extract clean markdown from web pages via Defuddle CLI (strips nav/ads/clutter, saves tokens). — triggers: read this article, fetch this page, summarize this blog post, pull this doc
- domain-check [protocol.yon] — Reconcile domain-name availability across sources that disagree. — triggers: /domain-check, is this domain available, check these domain names, did the availability tool lie

### Git & sync
- diff-recap [protocol.yon] — Turn a git diff into a PR-pasteable recap — one row per changed file whose path, status, and line counts are transcribed verbatim from `git diff --numstat` (true by construction; the model writes only the labels), emitted as an inline annotated widget plus a mandatory ASCII twin and a `diff-recap/1` record whose totals equal the sum of the rows. — triggers: /diff-recap, recap this diff, summarize these changes for a PR, what changed in this branch
- github-sync [protocol.yon] — Review the session's git changes, summarize them for approval, then commit and push to GitHub. — triggers: /github-sync, sync to github, commit and push, push this session

---
open-skills is a personal project by Alexandru Mares (allemaar.com), separate from the YounndAI™ product portfolio. Apache-2.0. YON (YounndAI Object Notation™), Lyt (Link Your Think™), and YounndAI™ are trademarks of MARLINK TRADING SRL.