ai-skills

ai-skills is a TypeScript and npm package for defining and distributing tool-agnostic AI skills. It is the skill-focused sibling of ai-agents: this repository is about reusable instruction bundles, not about full agent catalogs and renderers.

Source of Truth

The v1 specification lives in spec.md.

It defines:

• the canonical skill bundle structure
• authoring rules for portable skills
• skill-private bundle visibility and canonical cross-skill references
• the initial taxonomy for future skills
• how the canonical format maps to Codex, Claude, and Copilot

Repository Layout

• skills/ is reserved for canonical skill bundles
• spec.md defines the v1 contract for those bundles
• src/ contains the TypeScript CLI release surface
• dist/ contains compiled package output and is generated by pnpm build
• ai/PROJECT/DECISIONS/ contains repository ADRs

User Install

Install the public package globally with npm:

npm install -g @barney-media/ai-skills
ai-skills --help

The install and update commands both replace package-owned ai-skills-* directories in the supported target directories. Non-prefixed user skills are preserved.

ai-skills install
ai-skills update --assume-yes

Without --assume-yes, the CLI asks for confirmation before deleting and replacing package-owned ai-skills-* directories.

Catalog validation enforces that each skill bundle is skill-private: skills may refer to other skills only as skill ai-skills-..., never through another bundle's file paths.

For repository development, build, and release validation details, see CONTRIBUTIONS.md.