@playstack/skills

@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:

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

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

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

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:

The package has no runtime state, events, environment access, or application bridge. Installation and drift reporting belong to @playstack/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.

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.

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. For API lookup and partial-example conventions, see Reading the reference. Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.