<!-- Source: README.md -->

# @codenhub/skills

A curated collection of AI agent skill assets, an installer for supported agent harnesses, and utilities for discovering and copying skill directories.

## Installation

Run the installer without adding it to a project:

```sh
pnpm dlx @codenhub/skills@latest
```

The equivalent npm command is `npx @codenhub/skills@latest`.

## Usage

Use the library entrypoint to discover skill directories and copy one into a destination:

```ts
import { copyRecursiveSync, getSkills } from "@codenhub/skills";

const [skill] = getSkills("./skills");

if (skill) {
  copyRecursiveSync({ src: skill.path, dest: `./output/${skill.id}` });
}
```

The CLI is interactive only when invoked in a TTY without arguments (`--include-drafts` aside). Before using `--cleanup`, review its destructive behavior in the [CLI guide](docs/cli.md#destructive-cleanup).

## Documentation

- [Documentation overview](docs/index.md): Complete package documentation.
- [Programmatic API](docs/api.md): Public exports, path rules, and failures.
- [CLI installer](docs/cli.md): Options, destinations, and harness behavior.
- [Skill format and catalog](docs/skills.md): Supported assets and bundled inventory.

## Requirements

- Node.js 24 or newer.
- Filesystem permission to read source skills and modify selected destinations.
- A TTY for the interactive wizard; explicit CLI options support automation.

## Notes

- Existing files are merged and overwritten by default; stale files are not removed unless `--cleanup` is used.
- `--cleanup` recursively removes each selected harness's entire skills directory before installation.

## License

Licensed under Apache-2.0. Bundled skills include adapted third-party material; see [NOTICE](NOTICE) and [skill provenance](docs/provenance.md).

<!-- Source: docs/index.md -->

# Install and manage agent skills

`@codenhub/skills` provides a curated collection of AI agent skills, a CLI that installs them into supported harnesses, and Node.js utilities for discovering and copying skill directories.

## Setup

### Installation

Run the installer without adding it to a project:

```sh
pnpm dlx @codenhub/skills@latest
```

The npm equivalent is `npx @codenhub/skills@latest`.

### Quick start

Run the command from the workspace where the skills should be installed. With no arguments in a TTY, the wizard lets you choose scope, skills, harnesses, and cleanup behavior.

For automation, provide explicit options. This installs two skills into every supported workspace harness without prompting:

```sh
pnpm dlx @codenhub/skills@latest --local --all-harnesses --skills=brainstorming,test-driven-development
```

Review the [CLI installer](docs/cli.md) before choosing destinations or automating cleanup.

### Configuration

Use `--local`, `--global`, or `--both` to select scope. Select skills with `--skills` or `--all-skills`, and destinations with `--harnesses` or `--all-harnesses`. Without arguments outside a TTY, the CLI installs all skills to detected harnesses in the local scope and fails if none are detected.

## Requirements

- Node.js 24 or newer.
- Filesystem permission to read source skills and modify every selected destination.
- A TTY for the interactive wizard. Explicit CLI options support automation.

## Filesystem safety

Installation and copying write directly to local filesystem trees and are not transactional. Existing files are merged and overwritten by default. The `--cleanup` option first removes each selected harness's entire skills directory, including content not managed by this package. Cleanup failures do not by themselves produce a nonzero exit code.

Read [Security and failure behavior](docs/security-and-failures.md) for path and symlink constraints, partial-write behavior, cleanup risks, and CLI exit semantics before copying untrusted trees or automating installation.

## Next steps

- [CLI installer](docs/cli.md): Review interactive and automated modes, options, destinations, harness behavior, and destructive cleanup.
- [Programmatic API](docs/api.md): Use synchronous parsing, discovery, and recursive copy utilities in custom Node.js workflows.
- [Skill format and catalog](docs/skills.md): Evaluate or author compatible `SKILL.md` assets and inspect the bundled inventory.
- [Skill provenance](docs/provenance.md): Review origins, licenses, package notices, and the per-skill `NOTICE` files copied during installation.

<!-- Source: docs/api.md -->

# Programmatic API

Import all public symbols from `@codenhub/skills`:

```ts
import { copyRecursiveSync, getSkills, parseFrontmatter, type CopyRecursiveOptions, type Skill } from "@codenhub/skills";
```

All operations are synchronous and require Node.js 24 or newer.

## `parseFrontmatter`

```ts
function parseFrontmatter(content: string): Record<string, string>;
```

Parses a limited, flat frontmatter block at the beginning of a Markdown string. An optional leading byte-order mark is accepted. The opening and closing `---` delimiters must occupy their own lines.

Each line is split at its first colon. Values remain strings. Matching single or double quotes are removed, and an unquoted value drops a trailing comment that starts with whitespace followed by `#`. Nested YAML, arrays, multiline values, type coercion, escapes, and general YAML syntax are not supported.

It returns an empty object when there is no matching frontmatter block. Lines without a colon are ignored.

## `getSkills`

```ts
function getSkills(srcDir: string): Skill[];
```

Reads the immediate child directories of `srcDir`. A child is included only when it contains a file named exactly `SKILL.md`. Other files and nested skills are ignored.

For each included directory, the function parses `SKILL.md` and returns:

```ts
interface Skill {
  id: string;
  name: string;
  description: string;
  path: string;
}
```

- `id` is the child directory name.
- `name` is frontmatter `name`, falling back to `id` when absent or empty.
- `description` is frontmatter `description`, falling back to an empty string.
- `path` is the path formed by joining `srcDir` and `id`; it is absolute only when `srcDir` is absolute.

The function returns an empty array when `srcDir` does not exist. Results follow the filesystem's directory enumeration order and are not explicitly sorted. Unreadable directories or files and other filesystem failures throw.

## `copyRecursiveSync`

```ts
interface CopyRecursiveOptions {
  src: string;
  dest: string;
  ignoreList?: string[];
}

function copyRecursiveSync(options: CopyRecursiveOptions): void;
```

Copies one file or a directory tree from `src` to `dest`. Missing destination directories are created. Existing files at matching paths are overwritten; existing directories are merged. Entries that exist only at the destination are left in place.

`ignoreList` contains exact base names to skip at every directory depth. It does not accept path patterns or globs. Matching uses the platform's JavaScript string comparison and is case-sensitive.

The copy follows source symlinks that remain within the source tree and copies their resolved contents. It rejects a symlink that resolves outside the source tree. It also rejects destinations that resolve to the source itself or inside the source. See [Security and failure behavior](docs/security-and-failures.md) before copying untrusted trees.

The function throws when `src` does not exist, a path constraint is violated, or another filesystem operation fails. It does not roll back files copied before a failure.

<!-- Source: docs/cli.md -->

# CLI Installer

The `codenhub-skills` executable copies bundled skill directories into supported agent harness locations. Run it through a package executor:

```sh
pnpm dlx @codenhub/skills@latest
```

Use `npx @codenhub/skills@latest` for the npm equivalent. Node.js 24 or newer is required.

## Modes

With no arguments and a TTY, the CLI opens a wizard for scope, skills, harnesses, and cleanup. Existing harness paths are preselected, but the user can change the selection.

When stdin is not a TTY, or when any argument other than `--include-drafts` is supplied, the CLI does not prompt. It installs all skills unless `--skills` selects a subset. Without an explicit harness selection, it installs to harnesses detected for the selected scope. Detection succeeds when the destination or its parent directory exists. If none are detected, the command fails rather than writing to every possible destination; use `--all-harnesses` to opt into all destinations.

## Options

| Option               | Behavior                                                               |
| -------------------- | ---------------------------------------------------------------------- |
| `--local`            | Use workspace destinations. This is the default scope.                 |
| `--global`           | Use destinations under the current user's home directory.              |
| `--both`             | Include both workspace and global destinations.                        |
| `--skills=<list>`    | Install comma-separated, case-sensitive skill IDs.                     |
| `--all-skills`       | Install every bundled skill.                                           |
| `--harnesses=<list>` | Install to comma-separated harness labels, matched case-insensitively. |
| `--all-harnesses`    | Select every harness valid for the chosen scope.                       |
| `--cleanup`          | Remove selected destination roots before copying.                      |
| `--include-drafts`   | Also offer draft skills. Works only from a repository checkout.        |
| `--help`, `-h`       | Print command help.                                                    |

Harness labels include their scope, for example `OpenCode Workspace` and `OpenCode Global`. A label supplied to `--harnesses` must be valid for the selected scope.

## Install Destinations

Workspace paths resolve from the process's current working directory. Global paths resolve from the current user's home directory. The `Agent Skills` destinations are the cross-harness standard locations (`.agents/skills`) that most harnesses read natively; prefer them when a harness appears in both lists.

| Harness      | Workspace destination | Global destination           |
| ------------ | --------------------- | ---------------------------- |
| Agent Skills | `.agents/skills`      | `~/.agents/skills`           |
| Antigravity  | `.agents/skills`      | `~/.gemini/config/skills`    |
| Claude       | `.claude/skills`      | `~/.claude/skills`           |
| Cline        | `.cline/skills`       | `~/.cline/skills`            |
| Codex        | `.agents/skills`      | `~/.agents/skills`           |
| Copilot      | `.github/skills`      | `~/.copilot/skills`          |
| Cursor       | `.cursor/skills`      | `~/.cursor/skills`           |
| Gemini CLI   | `.gemini/skills`      | `~/.gemini/skills`           |
| Kiro         | `.kiro/skills`        | `~/.kiro/skills`             |
| OpenCode     | `.opencode/skills`    | `~/.config/opencode/skills`  |
| Trae         | `.trae/skills`        | `~/.trae/skills`             |
| Windsurf     | `.windsurf/skills`    | `~/.codeium/windsurf/skills` |
| ZCode        | `.zcode/skills`       | `~/.zcode/skills`            |

Several labels resolve to the same directory because the harnesses read it too: `Agent Skills Workspace`, `Antigravity Workspace`, and `Codex Workspace` share `.agents/skills`; `Agent Skills Global` and `Codex Global` share `~/.agents/skills`. Selecting labels that share a destination installs each skill once rather than copying it repeatedly.

The installer creates a child directory named after each skill ID. By default, it merges into existing directories and overwrites files with matching paths; it does not remove stale files.

## Harness Behavior

Destinations selected through a Codex label receive the complete bundled skill directory, including an `agents` directory when a skill has one. Every other destination excludes entries whose base name is exactly `agents` at any depth. When a Codex label shares a destination with other selected labels, the shared copy keeps the `agents` directory. Other references, examples, notices, and supporting files are copied unchanged.

The package does not validate that a harness can interpret every bundled file.

## Destructive Cleanup

`--cleanup` recursively removes each selected harness's entire skills destination before installation. This deletes all content in that directory, including skills and files not managed by `@codenhub/skills`. For example, selecting `OpenCode Workspace` removes `.opencode/skills` as a whole. Labels that share a destination, such as `Codex Workspace` and `Agent Skills Workspace`, remove that one directory.

Cleanup occurs before any skill is copied. A cleanup failure is printed and the installer continues, so the affected destination may contain a mixture of old and newly copied content. Do not use this option on a shared or manually managed skills directory without a backup.

## Draft Skills

Draft skills live in the repository beside the bundled ones, in `packages/skills/drafts/`, and are not published. The installer ignores them unless `--include-drafts` is given, which adds them to the skills it offers, each labeled `(draft)` in the wizard. The flag says where skills come from rather than what to install, so on its own it keeps the wizard; with other options, `--all-skills` and the default selection include the drafts too.

Run it from a checkout after building the package, from the directory to install into:

```sh
pnpm build skills
node <checkout>/packages/skills/dist/cli.js --include-drafts
```

From a published install, which has no drafts, the flag fails with exit code `1`. So does a draft whose ID matches a bundled skill.

## Automation Example

Install two skills into every workspace harness without prompts:

```sh
pnpm dlx @codenhub/skills@latest --local --all-harnesses --skills=brainstorming,test-driven-development
```

For validation errors, cancellation codes, partial writes, and filesystem failures, see [Security and failure behavior](docs/security-and-failures.md).

<!-- Source: docs/provenance.md -->

# Skill Provenance

This page records the origin and license context of skill assets shipped by `@codenhub/skills`. The package-level legal terms are in [NOTICE](NOTICE). Each adapted skill also carries its attribution and upstream license text in its own directory, in `NOTICE` and, where the license is long, `LICENSE`, so both are copied when the installer copies that skill alone.

| Skill                     | Origin                                 | License    |
| ------------------------- | -------------------------------------- | ---------- |
| `agents-md-improver`      | Original Coden Agency work             | Apache-2.0 |
| `audit`                   | Adapted from [JuliusBrussee/caveman]   | MIT        |
| `babysit-pr`              | Original Coden Agency work             | Apache-2.0 |
| `brainstorming`           | Adapted from [obra/superpowers]        | MIT        |
| `branding`                | Original Coden Agency work             | Apache-2.0 |
| `caveman`                 | Adapted from [JuliusBrussee/caveman]   | MIT        |
| `caveman-commit`          | Adapted from [JuliusBrussee/caveman]   | MIT        |
| `design`                  | Original Coden Agency work             | Apache-2.0 |
| `logo-design`             | Original Coden Agency work             | Apache-2.0 |
| `motion-graphics`         | Original Coden Agency work             | Apache-2.0 |
| `naming`                  | Original Coden Agency work             | Apache-2.0 |
| `playful-tone`            | Original Coden Agency work             | Apache-2.0 |
| `ponytail`                | Adapted from [DietrichGebert/ponytail] | MIT        |
| `ponytail-review`         | Adapted from [DietrichGebert/ponytail] | MIT        |
| `project-template`        | Original Coden Agency work             | Apache-2.0 |
| `subagent-specialist`     | Adapted from [obra/superpowers]        | MIT        |
| `test-driven-development` | Adapted from [obra/superpowers]        | MIT        |
| `writing-skills`          | Adapted from [obra/superpowers]        | MIT        |

The package `NOTICE` contains the applicable attribution blocks and bundled MIT license text. Per-skill notices are product assets and remain included when the installer copies an individual skill. For the current shipped inventory and format, see [Skill format and catalog](docs/skills.md).

[dietrichgebert/ponytail]: https://github.com/DietrichGebert/ponytail
[juliusbrussee/caveman]: https://github.com/JuliusBrussee/caveman
[obra/superpowers]: https://github.com/obra/superpowers

<!-- Source: docs/security-and-failures.md -->

# Security And Failure Behavior

The package reads and writes local filesystem trees synchronously. Callers and CLI users must choose trusted sources and destinations and grant only the required filesystem permissions.

## Path Constraints

`copyRecursiveSync` canonicalizes the source and as much of the destination as currently exists. It rejects a destination that resolves to the source itself or within the source, preventing recursive self-copying through ordinary paths or existing destination symlinks.

During directory copies, a source symlink must resolve within the canonical source tree. A symlink that resolves outside that tree throws a directory traversal error. Accepted symlinks are followed and their resolved file or directory contents are copied. Revisited canonical directories are skipped to avoid symlink cycles.

These checks constrain reads performed through source symlinks. They do not turn the API into a sandbox or validate that caller-provided destinations are appropriate. Avoid copying attacker-controlled trees into sensitive locations. Filesystem state can also change between synchronous checks and operations.

## Copy Failure Behavior

The programmatic API throws when:

- The source path does not exist.
- The destination resolves to the source or one of its descendants.
- A source symlink resolves outside the source tree.
- Reading, resolving, creating, deleting, or writing a filesystem entry fails.

Copies are not transactional. Files written before an error remain at the destination, and overwritten files are not restored. Existing destination-only files remain unless the CLI cleanup option removes the whole destination first.

## CLI Failure Behavior

The CLI exits with code `1` for invalid arguments, unknown skill IDs, harnesses that do not match the selected scope, no detected harness, missing bundled skills, unhandled exceptions, or any skill copy failure. Copy failures are reported individually, and installation continues for the remaining selected skills and harnesses before the final nonzero exit.

Pressing Ctrl+C in the interactive wizard exits with code `130`. Leaving the wizard with no selected skills or harnesses prints a message and exits with code `0` without installing.

Cleanup failures are reported but do not by themselves set a nonzero exit code. The installer continues to copy into that destination. Consumers automating `--cleanup` must inspect output as well as the final exit code.

## Destructive Cleanup

The CLI's `--cleanup` option uses recursive forced removal on every selected harness skills root. It removes unmanaged content as well as previously installed package content. Destination paths are fixed by the selected harness and scope, but workspace destinations are resolved from the current working directory. Confirm both before running cleanup.

See the [CLI installer](docs/cli.md#destructive-cleanup) for destinations and safe-use guidance.

<!-- Source: docs/skills.md -->

# Skill Format And Catalog

The `skills/` tree is shipped product content. Its Markdown files are executable instructions and supporting material consumed by agent harnesses, not canonical package-documentation pages. The package documentation describes how those assets are discovered and installed without republishing every skill body.

## Supported Format

Each skill occupies one immediate child directory under a source skills directory and must contain `SKILL.md` with that exact casing:

```text
skills/
  example-skill/
    SKILL.md
    NOTICE
    agents/
    references/
    scripts/
    assets/
```

The programmatic discovery API recognizes the directory solely by the presence of `SKILL.md`. The installer copies the whole directory subject to its harness-specific `agents` exclusion.

The supported metadata is a flat frontmatter block at the beginning of `SKILL.md`:

```markdown
---
name: example-skill
description: Use when an agent needs the example workflow.
---
```

`name` and `description` are the fields consumed by current package tooling. `name` falls back to the directory ID, and `description` falls back to an empty string. The parser is intentionally narrower than YAML; see the [programmatic API](docs/api.md#parsefrontmatter) for exact parsing rules.

Supporting Markdown, YAML, notices, examples, and reference files may accompany `SKILL.md`. Their meaning is harness- or skill-specific and is not interpreted by the package.

## Quality Rules

Bundled skills follow the [Agent Skills specification](https://agentskills.io/specification) and the authoring guidance in the bundled `writing-skills` skill. The package test suite enforces the rules that can be checked mechanically, so `pnpm test skills` fails when a bundled skill breaks one:

- `name` matches the directory, uses lowercase letters, digits, and single hyphens, is at most 64 characters, and contains neither `anthropic` nor `claude`.
- `description` is a single line of 1 to 1024 characters without XML tags.
- Frontmatter uses only the specification's keys: `name`, `description`, `license`, `compatibility`, `metadata`, and `allowed-tools`.
- The `SKILL.md` body is under 500 lines.
- A skill holds only `SKILL.md`, `NOTICE`, `LICENSE`, `agents/`, `references/`, `scripts/`, and `assets/`.
- Files that `SKILL.md` references exist and use forward slashes, and every file in `references/` is referenced from `SKILL.md`.
- Reference files do not reference other files in the skill, and those over 100 lines open with a `## Contents` section.
- A skill's Markdown files do not name another bundled skill, since the user may not have it installed.
- `agents/openai.yaml` defines `display_name`, `short_description`, and `default_prompt`.

The rest of the authoring guidance, such as how a description is phrased or whether a change was evaluated, needs judgment and is covered in review. Drafts are checked for valid metadata only.

## Bundled Inventory

| Skill ID                  | Purpose                                                                       |
| ------------------------- | ----------------------------------------------------------------------------- |
| `agents-md-improver`      | Audits and improves repository `AGENTS.md` guidance.                          |
| `audit`                   | Audits and reviews code, classifying findings consistently.                   |
| `babysit-pr`              | Sees a pull request through CI and review until it is ready to merge.         |
| `brainstorming`           | Explores requirements and design before implementation.                       |
| `branding`                | Builds brand strategy and identity systems, from positioning to guidelines.   |
| `caveman`                 | Provides an ultra-compressed communication mode.                              |
| `caveman-commit`          | Generates terse Conventional Commit messages.                                 |
| `design`                  | Guides visual and interface design: hierarchy, type, space, color, behavior.  |
| `logo-design`             | Designs logos and marks from concept to outlined SVG files and usage rules.   |
| `motion-graphics`         | Storyboards, animates, and renders motion graphics frame by frame.            |
| `naming`                  | Finds meaningful, memorable, ownable names for anything.                      |
| `playful-tone`            | Gives docs and public text a natural, playful tone in any language.           |
| `ponytail`                | Builds the simplest solution that works, nothing speculative.                 |
| `ponytail-review`         | Finds over-engineering and ledgers deferred work.                             |
| `project-template`        | Creates, syncs, and adopts projects built on the shared project template.     |
| `subagent-specialist`     | Decides what to delegate, then briefs, reviews, and integrates subagent work. |
| `test-driven-development` | Applies fail-first red-green-refactor development.                            |
| `writing-skills`          | Authors, reviews, and evaluates skills against the rules.                     |

`design` replaces the former `frontend-design` skill. Installing over an earlier version keeps `frontend-design` in place, because the installer does not remove stale directories. Delete the `frontend-design` directory from each skills destination by hand. Do not use `--cleanup` for this, since it removes the whole destination, including skills this package does not manage.

## Versioning

From 1.0, the version of a release says what changes for someone who has the skills installed:

- **Major:** a skill is removed or renamed. A skill ID is the directory the installer writes, and the installer leaves an old directory in place, so a removed or renamed skill stays installed until someone deletes it.
- **Minor:** a skill is added, or an existing skill's triggers, rules, or workflow change.
- **Patch:** editorial changes to a skill, such as wording, formatting, or links, with no intended change in behavior.

The CLI and the programmatic API follow SemVer as usual. Rejected: treating every change to a skill's behavior as breaking. Nearly every skill change alters what an agent does, so that rule would make almost every release a major one, and the version would no longer tell consumers which upgrades need their attention.

Use the installed `SKILL.md` and accompanying assets as the authoritative skill content for the installed package version.

## Drafts

Skills still in development live in `drafts/` in the repository, in the same format. They are not published, not listed here, and not installed unless the CLI is run from a checkout with `--include-drafts` (see the [CLI guide](docs/cli.md#draft-skills)). Promoting a draft means moving its directory to `skills/` and adding it to this inventory and to [Skill provenance](docs/provenance.md).

## Third-Party Material

Most bundled skills adapt third-party material. Package and per-skill notices travel with the relevant assets. See [Skill provenance](docs/provenance.md) and the package [NOTICE](NOTICE) before redistributing or modifying them.

<!-- Source: docs/changelog/0.2.0.md -->

# 0.2.0

## Added

- `audit`, which audits and reviews code, pull requests, and packages and classifies every finding the same way. It replaces `caveman-review`.
- `design`, which guides visual and interface design in any medium: hierarchy, typography, space, color, interaction, and interface motion. It replaces `frontend-design`.
- `naming`, which generates, researches, and judges names for products, packages, tools, and code identifiers, and verifies each presented name's meaning, pronunciation, and collisions.
- `branding`, which builds brand strategy and identity systems, from positioning and voice to visual identity, guidelines, and presentations.
- `logo-design`, which designs logos from written concepts to outlined SVG files and usage rules, with a script that outlines lettering with the font's kerning.
- `motion-graphics`, which storyboards, animates, and renders videos frame by frame from a seekable timeline, with any encoder the environment has.
- `ponytail` and `ponytail-review`, which keep code to the simplest solution that works and review a diff for over-engineering.
- `babysit-pr`, which sees a pull request through CI and review until it is ready to merge, fixing failing checks and answering reviewers.
- `project-template`, which creates, syncs, and adopts projects built on the shared project template.
- `playful-tone`, which gives docs and public text a natural, playful tone in any language.
- **Stable.** The package is no longer experimental.
- The installer covers Cursor, Gemini CLI, Copilot, Windsurf, Trae, Cline, Kiro, ZCode, and the cross-harness Agent Skills location (`.agents/skills`). Harnesses that read the same directory get one copy of each skill.
- A CLI guide, a skill format and catalog page, and a provenance page.

## Changed

- **Breaking.** Node.js 24 or newer is required, up from 18.
- **Breaking.** Codex skills install to `.agents/skills` in the workspace and `~/.agents/skills` globally, where Codex now reads them, instead of `.codex/skills` and `~/.codex/skills`. Skills installed by 0.1.0 stay in the old directory until you delete them.
- `writing-skills`, `agents-md-improver`, `subagent-specialist`, `test-driven-development`, `brainstorming`, `caveman`, and `caveman-commit` are rewritten or revised. `writing-skills` is organized around the Agent Skills specification's rules and an evaluation procedure.
- Bundled skills no longer name other skills, since the user may not have them installed.

## Removed

- **Breaking.** `frontend-design`, replaced by `design`, and `caveman-review`, folded into `audit`. The installer does not remove a skill's old directory, so delete `frontend-design` and `caveman-review` from each skills destination by hand.
