npm package: @nuskin/skills
Description: Portable AI skills registry and installer CLI for Codex, Claude, and Copilot.
Latest version: 1.0.0

# 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

```text
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

```yaml
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:

```bash
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:

```bash
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](CONTRIBUTING.md) for authoring rules and review expectations.