---
title: "@playstack/skills"
description: "Versioned, repository-installed guidance for composing Playstack packages safely."
tags: ["package","foundation","skills","agents","tooling","free"]
---

{/* package-access:start */}

> **Free.** MIT licensed. Check preview availability before installing. See [package access](/docs/packages#access-policy).

{/* package-access:end */}

`@playstack/skills` gives coding agents the architectural context needed to make judgement calls across Playstack packages. It is a versioned Markdown corpus—not a runtime agent framework, autonomous workflow, or replacement for deterministic lint and `playstack doctor` checks.

## Install the corpus

Install the Skills package and the CLI as development dependencies:

```sh
npm install --save-dev @playstack/skills @playstack/cli
npx playstack init
npx playstack skills sync
```

The default target is `.agents/skills`. Installed files remain in the repository so developers and agents can review the exact guidance in use.

## Configure targets and overrides

```json
{
  "$schema": "./node_modules/@playstack/cli/playstack.schema.json",
  "skills": {
    "targets": [".agents/skills"],
    "overrides": {
      "event-design": ".playstack-overrides/event-design"
    }
  }
}
```

| Property | Type | Purpose |
| --- | --- | --- |
| `skills.targets` | `string[]` | One or more repository-relative directories that receive the corpus. |
| `skills.overrides` | `Record<skillId, path>?` | User-owned skill directories that shadow a packaged skill by stable ID. |

An override must stay inside the repository, include its own `SKILL.md`, and use an ID declared by the installed package. It shadows the managed source without modifying it.

## Synchronize and verify

```sh
npx playstack skills sync
npx playstack skills sync --diff
npx playstack skills sync --check
npx playstack doctor --check
```

The CLI validates the package manifest and content hashes before copying anything. It records the package version, skill ID, source, file hashes, and aggregate content hash in `.playstack/skills.json`.

A clean second sync makes no changes. If a managed copy was edited locally, sync reports an unsafe conflict and refuses to overwrite it. Use an explicit override for repository-specific guidance; reserve `--force` for deliberately replacing a managed copy.

## Included skills

### `playstack-conventions`

Reviews integration boundaries for portable contracts, explicit dependencies, trace context, escape hatches, and standard adoption.

### `playstack-escalation`

Guides the progression from configuration, to replacing a seam, to ejecting package-owned source only when the earlier choices do not fit.

### `scope-review`

Examines multi-tenant ownership and lifecycle boundaries that cannot be proven by checking for a scope filter alone.

### `event-design`

Helps choose useful event names and granularity, including the boundary between transactional domain events and observational analytics events.

### `chakra-composition`

Reviews Chakra prop usage, recipe extraction, and whether a repeated pattern belongs locally, in a component, or in a shared theme.

### `extension-review`

Reviews browser-extension permissions, execution contexts, service-worker lifecycle, bundle weight, and common store-review traps.

### `structured-data`

Aligns JSON-LD, metadata, feeds, webmentions, and oEmbed representations around one application-owned content model.

## Manifest contract

`playstack.skills.json` is the package's public distribution contract. Schema version 1 declares:

| Property | Meaning |
| --- | --- |
| `packageVersion` | The exact corpus version being synchronized. |
| `skills[].id` | A stable lowercase kebab-case skill identifier. |
| `skills[].path` | The confined package-relative skill directory. |
| `skills[].files` | Ordered relative paths mapped to lowercase SHA-256 digests. |

The package has no runtime state, events, environment access, or application bridge. Installation and drift reporting belong to [`@playstack/cli`](/docs/cli).

## Boundary

Skills carry judgement that depends on product context. Deterministic violations—invalid wire values, missing trace metadata, undeclared events, unsafe extension permissions, or unscoped persistence—belong in lint rules, tests, and `doctor`. Keeping that split explicit prevents always-on guidance from spending context on checks the toolchain can enforce every time.

{/* package-reference:start */}

## API entry points and requirements

Reference snapshot: `@playstack/skills@0.1.0-beta.1`. Import only the entry point your runtime needs. Paths below are relative to the installed package; use **Go to Definition** in your editor to inspect exact parameters, return types and overloads. Do not import the declaration-file paths directly.

| Public entry point | Declaration file |
| --- | --- |
| `@playstack/skills` | `./dist/index.d.ts` |
| `@playstack/skills/playstack.skills.json` | No TypeScript declaration (asset or metadata export). |
| `@playstack/skills/package.json` | No TypeScript declaration (asset or metadata export). |

Node.js engine requirement: `>=20`. This is not a claim that every entry point works in browsers or Workers.

### Peer dependencies

This package declares no peer dependencies. Its ordinary dependencies are resolved by the package manager.

For a complete first program, start with [Getting started](/docs/getting-started). For API lookup and partial-example conventions, see [Reading the reference](/docs/packages#reading-the-reference). Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.

{/* package-reference:end */}