Why this exists

A skill is instructions handed to an agent that may be able to touch your files. My rule is simple: you should be able to read a skill before you trust it.

These skills came from repeated work with Claude Code, Codex, and other runtimes that read the open Agent Skills format: planning, investigation, review, writing, orchestration, priming, architecture, and knowledge work. Some have been in daily use and evolution since well over a year ago; others were added when the work demanded them. That is my account, not a benchmark. What is published here is the working set, not a demo.

Composable, not a framework. Install one or install fifty. Each skill is its own decision, and your agent keeps room to think between them. Take what earns its place.

Start with the work

I need to… Start with What it gives you
turn an objective into an executable plan plan-create a phased plan with explicit gates and verification
establish facts before deciding investigate read-only evidence gathering with provenance and gaps
challenge work with fresh eyes cold-review bounded outside review against actual artifacts
make a report easier to decide from human-output a writing contract built around verdict, consequence, evidence, and omissions
coordinate agents through a shared folder agent-mailbox traceable, append-only agent communication with Handler-readable state

Throughout these docs, a skill's written command is its folder name (/insight-explore, /plan-phases) — the portable form across runtimes. Shorter phrases declared in frontmatter triggers: (/explore, /phase-plan) are recognition aliases that some runtimes also honor.

The generated SKILLS.md catalog groups all 62 skills into twelve families. It is built from live SKILL.md metadata plus the pack's taxonomy.yon, so the human catalog and machine catalogs share one source rather than parallel hand-maintained menus.

Inside an agent, /skills-help reads that same bundled taxonomy and the skills actually installed beside it. Unknown third-party skills remain visible under Unclassified; they are not guessed into one of this pack's families.

What is inspectable, and what is not enforced

Each skill folder carries its core instructions and required runtime companions. Optional sibling skills and repository-only release checks are declared separately and do not block the core skill when absent. Thirty-nine procedural skills also carry protocol.yon, a declarative companion that names steps, rules (MUST / MUST_NOT), and gates (ABORT / WARN) as typed records.

That distinction matters:

Surface What it proves
SKILL.md the operational instructions the agent is being asked to follow
protocol.yon an inspectable, diffable declaration of the intended protocol
parser validation that the declaration is structurally valid for its profile
CI checks only the specific syntax, reference, dataflow, catalog, count, and privacy properties they inspect

There is no interpreter standing over the model and forcing runtime obedience. A valid protocol may still describe something harmful. Validation narrows what you must inspect; it does not replace inspection, sandbox the agent, or make the behavior safe.

Validate a protocol yourself with the separately published Apache-2.0 reference parser created by Alexandru Mares:

npx -y @younndai/yon-parser@2 validate \
  skills/cold-review/protocol.yon --profile exec

The npx command may download and execute that package. Inspect the package or install it through a route you trust before relying on it. The exact trust boundaries, including what validation cannot establish, are in THREAT-MODEL.md; current structural results are in CONFORMANCE.md.

Install

The safest first path is a frozen copy: read the source, copy only the skills you want, and diff before updating.

git clone https://github.com/allemaar/open-skills
cd open-skills

# POSIX shell. Set exactly one directory your runtime actually reads.
# The subshell keeps a failed preflight from closing an interactive terminal.
(
  set -eu
  SKILLS_DIR="$HOME/.claude/skills"
  SRC="skills/cold-review"
  DEST="$SKILLS_DIR/cold-review"

  probe="$DEST"
  while [ "$probe" != "/" ]; do
    [ ! -L "$probe" ] || { echo "link in destination chain: $probe"; exit 1; }
    probe=$(dirname "$probe")
  done
  [ ! -e "$DEST" ] || { echo "already installed — diff before replacing"; exit 1; }
  cp -r "$SRC" "$DEST"
)

The directories are not interchangeable. Claude Code reads ~/.claude/skills; current Codex installations can use ~/.agents/skills; other tools may use their own directory. Establish the path your runtime reads and change SKILLS_DIR once. On Windows, prefer the installer below: it performs native link checks instead of relying on POSIX shell semantics.

Optional installer

install.mjs is one readable Node file with zero local npm dependencies. It copies skill folders, can stamp their SKILL.md with an unsigned provenance note, and invokes npx for protocol validation unless you pass --no-validate.

node install.mjs cold-review
node install.mjs --runtime claude cold-review
node install.mjs --all
node install.mjs --list

Important boundaries:

  • By default it targets every known skills directory that already exists. Use --runtime claude|codex|agents to narrow it.
  • It refuses to overwrite an existing skill unless you pass --force.
  • It refuses to overwrite a symlinked or junctioned skill rather than risk deleting through the link into its source.
  • With --force, it stages and, unless --no-validate is supplied, validates the candidate before moving the existing copy aside, restores that copy if the swap fails, and surfaces crash leftovers for manual inspection.
  • Its provenance stamp is an unsigned plain-text assertion, not a certificate, and makes the installed SKILL.md differ from this repository. --no-stamp preserves byte identity.
  • The installer itself uses Node built-ins; validation may still fetch and execute @younndai/yon-parser through npx.

Claude Code plugin

/plugin marketplace add allemaar/open-skills
/plugin install open-skills@open-skills

This is the fastest Claude Code route, but it reverses the read-first order: installation happens before you inspect every skill. Use it only if that trade is acceptable.

Other distribution tools may also consume the repository, including gh skill install allemaar/open-skills. Their provenance metadata and update behavior belong to those tools. Review their prompts and resulting files rather than treating a source label as authenticated provenance.

Telemetry: the skills themselves contain no telemetry. The installer performs no analytics or reporting; its only optional network execution is parser validation through npx. Your agent runtime, plugin manager, package manager, Git host, or referenced external tool may have its own telemetry.

Worked example: cold review

  1. Read skills/cold-review/SKILL.md.
  2. Inspect skills/cold-review/protocol.yon. It declares an abort when no concrete artifact exists and bounds reviewer fan-out.
  3. Validate the declaration with the command above.
  4. Run the skill in your agent:
/cold-review the auth refactor on this branch

The useful property is not that YON makes the review happen. It is that you can see the intended gates and limits before you ask an agent to act, then diff those declarations when they change.

Agent Mailbox

I use agent-mailbox in FULL mode when I want a traceable orchestration record between agents. It lets Claude Code and Codex agents exchange append-only Markdown calls to action through Handler-controlled folders, including local folders, OneDrive, free Lyt (Link Your Think™) vaults, and network shares.

shared folder -> request -> durable disposition -> deliverable

That is a description of my current dogfooding, not a promise that every host can wake a stopped task or that every synchronization provider has the same latency. Work-or-Listen is participant-local and non-negotiated. The skill separates publication, local materialization, detection, full reconciliation, task wake, disposition, and re-arm because success in one layer does not prove the next.

The complete operating and security contract remains in the skill. Start with SKILL.md, use the operation-first resource spine only when you need a collaboration recipe, then use CONNECTION-GUIDES.md for transport/runtime adapters and VALIDATION.md for measured, observed, design-validated, and still-pending evidence. Experimental patterns remain in the skill as maintainer source material but are excluded from normal routing. No watcher, daemon, SDK, or runtime dependency is shipped.

Map Your Knowledge

The map- family is a system: Map Your Knowledge (MYK) — a protocol that makes any folder of markdown navigable cold, for people and agents alike. Every file declares its home map, every map lists its members, and new data is born mapped. Its first law is elasticity: existing conventions outrank MYK's defaults, verdicts are always human-confirmed, and a "no" is remembered forever.

  • map-rules — the shared rulebook every agent loads before touching organized markdown
  • map-this — "map this project": zero-write assessment → proposal table → you pick → careful apply
  • map-init — consent-first onboarding of the routing rules into your agents' directives, every platform
  • map-check — the honest inspector: read-only health checks via a bundled deterministic script, never an unqualified "all clear"
  • map-maintain — the gardener: one bounded check → you pick the repairs → it mends and rechecks

The full story, diagrams included: MapYourKnowledge.md.

Two headliner families

Orientation

The orient- family answers “where are we?” from current repository evidence rather than cached notes:

Human output

The human- family treats presentation as part of correctness:

  • human-output — write a decision-bearing result
  • human-rewrite — repair text without changing substance
  • human-draw — use a figure only when relationships need one
  • human-merge — combine several reports into one decision surface

The full breadth remains in SKILLS.md.

Updating

A copied skill is intentionally frozen. To update it, pull the repository, diff the installed folder against the candidate, read the change, then re-copy only after accepting it.

git pull
git diff --no-index ~/.claude/skills/cold-review skills/cold-review

Silence means byte-identical. Do not filter the diff unless you deliberately installed with the provenance stamp and understand exactly which lines you are excluding. A symlink is different: it makes every pull a live update, often without a separate review moment. That is useful while authoring your own skills and a poor default for running somebody else's.

Before updating, read CHANGELOG.md. Skill folders can be renamed, references can change, and a new release can alter the trust surface even when the syntax remains valid.

For agents and tooling

These are generated by tools/spine.mjs from live skill metadata, protocol facts, and the pack taxonomy. They are discovery surfaces, not runtime enforcement.

YON and its parser

Alexandru Mares created YON and its Apache-2.0 reference parser. They are published separately in the YounndAI ecosystem, alongside the public specification, parser, and editor support (VS Code Marketplace · Open VSX).

yon-read interprets existing YON. yon-write authors it. Their presence in this personal pack does not transfer ownership of YON to open-skills or make open-skills a YounndAI product.

Contributing and support

Read CONTRIBUTING.md before opening a pull request. Commits require Developer Certificate of Origin sign-off, current skill metadata must remain complete, and public content must contain no personal paths, credentials, mailbox identifiers, or private operational evidence.

License and project identity

Copyright 2026 Alexandru Mares (allemaar.com).

open-skills is licensed under the Apache License, Version 2.0. See NOTICE for attribution and TRADEMARK.md for the separate trademark rules.

This is my personal project, separate from the YounndAI product portfolio. YounndAI™, YounndAI Object Notation™, and Link Your Think™ are trademarks of MARLINK TRADING SRL. Their truthful mention here does not imply that open-skills is a YounndAI product.

Made by Alexandru Mares. Model-assisted, then reviewed, tested, and dogfooded in the work it describes.