@crossplatformai/skills/README.md

Reusable Agent Skills for CrossPlatform.ai projects.

# @crossplatformai/skills

Reusable Agent Skills for CrossPlatform.ai projects.

This package is intentionally no-build. It publishes TypeScript metadata from `src/` and concrete Agent Skill directories from `skills/`.

## Installation

After publication, install it like any other public package:

```sh
pnpm add -D @crossplatformai/skills
```

For local testing before publication, use a consumer-local `link:` dependency with a path relative
to the consumer repository:

```json
{
  "devDependencies": {
    "@crossplatformai/skills": "link:../framework/packages/skills"
  }
}
```

Then install from the consumer root:

```sh
pnpm --dir "/path/to/consumer" install
```

Commit approved unpublished-package validation state by default. Complete implementation, QA, and
production-mode validation builds may continue against the link. AI agents never publish or unlink;
the user may publish the validated framework package while the consumer remains linked, then owns
replacement with and verification of the exact registry version before consumer production release.
Load `@crossplatformai/skills#temporary-pnpm-package-links` for the complete contract.

## Admission CLI

The package exposes a dependency-free ESM executable for read-only Post-to-Build admission:

```sh
pbs-admit [--file <path>] [--mode portable|managed] [--tier 1|2|3] [--json]
```

It reads the packet from `--file` or stdin and returns a transport-normalized input digest plus
blockers, warnings, and defaults. Exit `0` means admissible, `1` means substantive blockers, and `2`
means invalid invocation or unreadable input. The digest establishes packet correspondence only;
Authorizing User approval remains the sole Build authority.

## Available Skills

### Workflow skills — Post.Build.Ship.

A three-phase outcome workflow plus a direct-user commit path: `post` investigates and defines proof,
`build` implements adaptively, and `ship` validates the final tree and commit story. Approval from
the Authorizing User is the sole authority to enter Build.

Invoke a route explicitly with its final period: `Post.`, `Build.`, `Ship.`, `Post.Build.`,
`Build.Ship.`, or `Post.Build.Ship.`. Ordinary prose and undotted aliases do not invoke the workflow.
`post-build-ship` remains the skill identifier. Post. returns an approval packet; Build. and
Post.Build. stop after approved implementation and QA; routes containing Ship. perform final
validation and coherent commits. A phase name alone does not spawn an agent.

Peer review is optional and runs only when the Authorizing User explicitly requests it. Existing review
findings may supplement the packet, but missing review, reviewer metadata, receipts, digests, or
unused review routes never block Build or Ship. A material issue still blocks because it affects
correctness or safety.

Portable Post packets use five compact sections: objective/evidence, outcomes/proof,
scope/boundaries, risks/rules, and execution/QA. Managed Workspace PBS v1 retains its existing
thirteen identities only at the provider boundary. Risk tiers control planning depth and QA breadth,
not review requirements.

Build may adapt implementation approach, files, focused tests, commands, recovery tactics, and
narrative commit partitions while preserving objective, observable acceptance, public contracts,
material boundaries, and risk. QA is reusable until a relevant source, dependency, configuration,
toolchain, fixture, generated output, or runtime state changes; a commit alone never invalidates it.
Ship validates Authorizing User authority, final-tree ownership, required QA, material drift,
temporary-link policy, and commit coherence directly.

The complete system lives under `skills/post-build-ship/`.

- `@crossplatformai/skills#post-build-ship`: Dispatch explicit `Post.`, `Build.`, `Ship.`, `Post.Build.`, `Build.Ship.`, and `Post.Build.Ship.` workflow requests.
- `@crossplatformai/skills#post-build-ship/post`: Investigate and produce Authorizing User-approvable outcome packets for Build.
- `@crossplatformai/skills#post-build-ship/build`: Implement Authorizing User-approved outcomes adaptively and prove them with proportionate QA.
- `@crossplatformai/skills#post-build-ship/ship`: Validate final ownership, QA, drift, and commit coherence, then ship authorized work.

### Guidance skills

Standalone, task-matched knowledge an agent loads on its own when a task matches:

- `@crossplatformai/skills#temporary-pnpm-package-links`: Temporary pnpm package-link guidance for consumer-local links, linked-source validation, committed development state, AI publication and unlink prohibitions, and registry verification before consumer production release.
- `@crossplatformai/skills#no-local-exemptions`: Review environment branches for hidden local exemptions when required values, guards, service contracts, or failure paths differ across environments. Require explicit, purpose-limited variance and fail-fast handling. Not for setup drift, test-layer or harness concerns, visual verification, host-OS portability, or Post.Build.Ship workflow gates.
- `@crossplatformai/skills#react-native-web-styling`: Decide whether web, Electron, shared, or mobile UI should use DOM or React Native, and guide existing React Native Web and Uniwind styling, className precedence, spacing, reset, and compatibility fixes.
- `@crossplatformai/skills#web-first-components`: Author shared UI web-first - the default `.tsx` file is plain DOM with Tailwind, and `.native.tsx`, `.ios.tsx`, or `.android.tsx` files are the React Native overrides - with reference implementations (zeego, solito, react-strict-dom) to emulate, a characterization-test-first migration workflow, and a strangler-fig migration posture.
- `@crossplatformai/skills#playwright-visual-verification`: Verify local browser-visible layout and styling with accessibility snapshots, screenshots, and computed-style checks using Playwright.
- `@crossplatformai/skills#test-layer-fit`: Choose the lowest meaningful test layer and design deterministic test harness ownership. Use for unit, component, adapter-contract, integration, or E2E placement; suite-load or CI-only failures; timeout, retry, sleep, serialization, warmup, timing-workaround, or suite/config-splitting proposals; and browser, Electron, mobile, subprocess, server, port, process, isolation, readiness, diagnostic, or cleanup ownership. Covers cross-platform proof boundaries and integration-suite reachability. Not for test-framework selection, coverage thresholds, general mocking or assertion style, visual verification, host-OS path or quoting mechanics, or Post.Build.Ship gate and receipt policy.
- `@crossplatformai/skills#desktop-electron-dev-attach`: Interactively attach to an already-running Electron app through stable `DESKTOP_CDP_PORT` for local development or requested desktop happy-path verification with Playwright or OpenCode MCP.
- `@crossplatformai/skills#multi-agent-hunk-ownership`: Multi-agent hunk-ownership guidance for preserving user and other-agent changes while editing, formatting, staging, and committing.
- `@crossplatformai/skills#documentation-writing`: Durable evergreen documentation guidance with change-oriented framing when change history is needed.
- `@crossplatformai/skills#reconcile-setup`: Idempotent run-once setup should be reconciled with an event-triggered, fail-loud QA drift-check.
- `@crossplatformai/skills#rule-of-three`: Structure complexity into about three memorable chunks with a rhythm - the phone-number principle.
- `@crossplatformai/skills#see-something-say-something`: See or smell something off, even outside your scope, and surface it - do not silently fix it or silently ignore it.
- `@crossplatformai/skills#thinking-is-not-knowing`: Before asserting a claim or recommendation, check whether you can say "I know" and name the failure mode it prevents - if not, it is a guess; verify before presenting it. When research has already grounded the options and user judgment remains, use research-before-asking.
- `@crossplatformai/skills#i-dont-know-is-the-answer`: When you lack a grounded answer, say "I do not know" instead of hedging - and make it pull its weight with "I do not know yet, here is how I will find out, by when." When research has already grounded the options and user judgment remains, use research-before-asking.
- `@crossplatformai/skills#research-before-asking`: Research and carry decisions before asking the user. Use for ambiguous requirements, missing specifications, ‘which approach’ or ‘should I use X or Y’ choices, or taste, priority, private facts, credentials, or authorization that remain after proportionate research. Present viable options, tradeoffs, a strong recommendation, and its flip condition. Not for verifying claims, responding to an ungrounded unknown, or Post.Build.Ship approval and gate policy; use thinking-is-not-knowing or i-dont-know-is-the-answer.
- `@crossplatformai/skills#collective-intelligence`: Use when a consequential, uncertain, complex, or creative decision benefits from task-relevant independent perspectives and explicit synthesis. Guide perspective selection, anti-anchoring, and transparent integration without defaulting to consensus or vote-counting. Not for routine well-supported work, factual verification (use thinking-is-not-knowing), evidence-backed research or decision-carrying (use research-before-asking), Post.Build.Ship workflow authority, or claiming that unperformed collaboration occurred.
- `@crossplatformai/skills#move-them-lose-them`: Keep users in their current task context when they can satisfy a prerequisite or create missing data without leaving what they are trying to finish.
- `@crossplatformai/skills#revalidate-without-reset`: Refresh an already-rendered stateful application view in place without discarding valid user context.
- `@crossplatformai/skills#do-not-abbreviate`: Require complete words in newly authored human-facing copy, names, labels, documentation, messages, and explanatory comments, with authorization before a shortened form; do not rewrite existing exact text, machine-facing tokens, or user-provided strings.

The package metadata exports the relative paths to these skill directories. It does not scan the filesystem or provide a runtime skill loader.

## Artifact Kinds

Three kinds of artifact, distinguished by who decides to load them:

1. **Workflow skills** — orchestration entrypoints and phase owners (`post-build-ship`, `post`, `build`, `ship`). The user invokes these.
2. **Guidance skills** — standalone knowledge the agent loads on its own when a task matches. Peers to the workflow, not internals.
3. **References** — non-invokable supporting docs cited by a workflow skill, under `skills/post-build-ship/references/`. The workflow pulls them in; they are not addressable skills and are not exported in the metadata.

Workflow spines stay lean: Authorizing User authority, outcome boundaries, adaptive Build, proportionate
QA, and Ship checks stay inline; situational recipes, checklists, and feature-specific policies (framework
release, PNPM audit, happy-path testing, fail-fast, and subagent delegation terms) live in
references. Temporary pnpm package links are a standalone guidance skill because agents load that
policy directly whenever linked-source testing or manual release-finalization ownership is in scope.

`test-layer-fit` is the sole active reference-promotion pilot. Before any second promotion, review
its real or forward-tested routing, false positives, overlap, duplicated normative content, context
cost, and whether Post.Build.Ship still owns its admission and QA policy.

## Publishing Model

The package publishes these files:

- `src/`: lightweight TypeScript metadata.
- `skills/`: concrete Agent Skill directories and `SKILL.md` payloads.
- `bin/pbs-admit.js`: the dependency-free ESM admission executable.
- `README.md` and `LICENSE`.

There is no build step, prepack step, CommonJS export, or generated runtime artifact.

## Pattern Inspiration

This package follows the same general package-distributed skill pattern used by TanStack Intent. It is not affiliated with TanStack Intent or TanStack.