AI Skills Registry

This repository is the source of truth for portable, governed AI skills. Each skill captures a reusable capability in a vendor-neutral format so it can be adapted across assistants such as Codex, Claude, and Copilot.

Design Principles

• simple
• declarative
• composable
• vendor-neutral

Repository Layout

index.yaml
package.json
src/
skills/
  <skill-name>/
    skill.yaml
    instructions.md
    adapters/
      codex.md
      claude.md
      copilot.md

• index.yaml is the registry catalog.
• package.json publishes the public npm CLI as @nuskin/skills.
• src/ contains the JavaScript CLI implementation.
• skill.yaml stores the metadata contract for a skill.
• instructions.md stores the assistant-agnostic behavior.
• adapters/ stores optional assistant-specific guidance.

skill.yaml Contract

name: example-skill
version: 1.0.0
description: Short description of the reusable capability.
inputs:
  - name: request
    type: string
    required: true
    description: What the skill needs from the caller.
outputs:
  - name: result
    type: string
    description: What the skill returns.
tags:
  - example
owner: Platform (Kaizen)
compatibility:
  - codex
  - claude
  - copilot

Use semantic versioning. Keep instructions.md focused on intent, decision rules, and expected outputs rather than tool-specific implementation details.

CLI

The repository ships a public npm CLI named @nuskin/skills.

Examples:

npx @nuskin/skills list
npx @nuskin/skills show semantic-release-eslint
npx @nuskin/skills install semantic-release-eslint --target codex
npx @nuskin/skills install semantic-release-eslint --target claude
npx @nuskin/skills install semantic-release-eslint --target copilot
npx @nuskin/skills help

During local development, install dependencies and run the CLI directly:

yarn install
node src/cli.js list
yarn validate
node src/cli.js validate

Install Targets

• codex installs rendered skills into ${CODEX_HOME:-~/.codex}/skills.
• claude installs rendered skills into ${CLAUDE_HOME:-~/.claude}/skills.
• copilot installs rendered prompt files into ./.github/prompts by default.

The Copilot prompt-file workflow is workspace-scoped rather than a global personal skill store. Prompt files are currently a GitHub public preview.

Public Repository Rules

This repository is public. Do not commit:

• secrets, tokens, passwords, or API keys
• environment variable values
• private URLs, internal board links, or private repository names
• customer data, personal data, or production identifiers
• local machine paths or assumptions that only work on one developer workstation

Keep skills portable and safe to publish.

Current Status

Phase 1 includes the first migrated skill:

• semantic-release-eslint

The public CLI is scaffolded in JavaScript with JSDoc and runtime validation. Legacy Codex-oriented helper scripts remain in the repository during the transition and are not yet part of the portable registry contract.

See CONTRIBUTING.md for authoring rules and review expectations.