skern: Instructions file for Codex

AGENTS.md — Skern Development Guide

Conventions, architecture, and design decisions for agents working in this repo. Human contributor setup — the full build/test matrix, directory tree, and dependency list — lives in docs/contributing/development.md. Release history lives in CHANGELOG.md; neither is restated here.

Project Overview

Skern is a minimal, agent-first CLI for managing Agent Skills across agentic development platforms. It follows the Agent Skills open standard (agentskills.io) and uses SKILL.md files with YAML frontmatter as the canonical format.

Written in Go 1.25+. Latest release v0.4.0; main carries unreleased work (see the [Unreleased] section of the CHANGELOG).

Scope

The registry is the center of gravity. Skern's value is being the single cross-platform source of truth for skills: one SKILL.md per skill, stored once, managed through skern regardless of which agent is running. Registry commands (create, import, edit, list, search, show, validate, version, diff, recommend, remove) are the primary surface, and skern init --instructions exists so an agent can be told to reach for skern directly instead of hunting through platform directories.

Platform install/uninstall is first-class and stays. Copying skills out to native platform directories serves real cases the registry alone does not: native progressive disclosure, sandboxed agents that cannot shell out to skern, and one-shot migration from an existing .claude/skills/. Adapters are maintained and extended, and adapter bugs are ordinary product bugs — they are just not the headline drive. The skern skill command tree encodes this split directly via two cobra groups: Registry commands and Platform commands (internal/cli/skill.go).

When proposing features, weigh them against the registry thesis first. New work that only makes sense as a per-platform copy needs a use case from the list above.