@agimon-ai/po-help

Activation-gated package guidance and help skills for Po and Pi extensions.

Packages

Package details

extensionskill

Install @agimon-ai/po-help from npm and Pi will load the resources declared by the package manifest.

$ pi install npm:@agimon-ai/po-help
Package
@agimon-ai/po-help
Version
0.0.0-alpha.183
Published
Nov 22, 2026
Downloads
31.1K/mo · 5,006/wk
Author
agiflow-ai
License
BUSL-1.1
Types
extension, skill
Size
842.4 KB
Dependencies
6 dependencies · 4 peers

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

@agimon-ai/po-help

Activation-gated package guidance and read-only diagnostics for Po agent setup and debugging.

Part of the Po distribution.

Alpha: Help contribution contracts may change between releases.

Requirements and installation

Requires Node.js 24 or newer and the Pi version declared in this package's peer dependencies. The distribution selects Help through default.packages in presets.yaml; it remains configurable rather than fixed host infrastructure.

Activate and diagnose

Use the mode menu, /mode help, or /po-help. Help is additive: unrelated tools, skills, and modes retain their existing activation and permission rules.

The mode detail reports applied skills and diagnostics, distinguishing pending discovery and degraded contributors from usable contributions.

Capability Owner Purpose
help_status Help Applied Help skills/tools, owners, availability, and bounded diagnostic codes.
diagnose_setup Distribution Saved configuration, installed packages, and sync drift for the current workspace.
diagnose_agent Log Bounded current-session captured failure and token-usage evidence.

Optional owners contribute only when present in the composition. The entry skill help-how-to-help routes to configuration, profile, mode, domain, skill, and debugging guidance rather than loading every document eagerly. Deactivating Help withdraws it from future discovery.

Diagnostics do not install packages, change configuration, authenticate servers, clear logs, or restart processes. Existing approval and permission boundaries apply to repairs. Empty or unavailable telemetry is not proof of health.

Deactivation withdraws Help-only capabilities and rejects stale references. It cancels supported in-flight work, but cannot undo completed effects or remove earlier guidance from conversation history.

Package-owned contributions

Use named routes under src/extensions/workspaces/sessions/(backend)/resource/ and tool/. Root files own shared state and lifecycle. Do not create a second tool registry inside Help or add executable callbacks to the documentation descriptor.

Human starter guides

The session help.guides typed data slot supplies human-readable starter guides on web and native. Help, Artifacts, Calendar, Goal, and Author each own two README-grounded guides. These are independent of Help-only agent skills and diagnostic tools; contributing guidance does not activate a mode or grant permissions.

Contribute a shared plain-data module under the owning fill's _lib/, then thin fill/<Label>.help.guides.web.ts and .native.ts routes using each platform's defineFill. Set slot: 'help.guides', a stable fill id, deterministic order, and data. No dependency on the optional Help package is needed: locally check the structural data with satisfies. Builds regenerate routed entries; never edit generated entries by hand.

The v1 data shape is { version: 1, label, guides }. Each guide has a stable id, question, plain-text answer, and optional keywords and numeric order. Labels and IDs are at most 80 characters, questions 240, answers 4,000, with at most 64 guides and 16 keywords of at most 64 characters each. Keep IDs unique within a set and all text nonempty. Invalid sets are rejected as a whole. Answers do not render Markdown or executable callbacks.

Keep wording grounded in the owning README and preserve approved question, answer, keyword, and ordering changes in contract tests. Runtime modules must never import story fixtures. The approved fixtures are test and story evidence only.

Skills

For the server, declare a normal skill resource with HELP_WHEN, a useful description, and path: packageResourcePath(import.meta.url, 'src/prompts/<name>/SKILL.md'). Its reader returns the same file. Validate required content and report unavailable resources rather than registering empty successful guidance. Keep package documents lazy; eager context is only for small live activation instructions.

Publish llms.txt and src/prompts in the package files allowlist. Relative links must remain inside the published package. Normal runtime skills retain their ordinary activation rules; content-only domain plugin schemas are not changed by this feature.

Tools

import { PO_HELP_WHEN as HELP_WHEN } from '@agimon-ai/po-core/help';

Contributor packages import the shared contract from Core, not the optional Help package, so the distribution does not acquire an unconditional mode dependency.

A server tool uses when: HELP_WHEN, remains owned by its normal server plugin, and checks the active host and Help selection at execution boundaries. Domain conditions can be combined with Help when both are required. Help does not bypass other restrictions.

The Log package's diagnose_agent routes are a first-party example. Provider replacement, late arrival, withdrawal, cancellation, and package shutdown must preserve owner cleanup. Adding Help never grants filesystem, shell, network, or remote MCP access.

Status data

The Help service binds the skill consumer's accepted inventory instead of assuming every resolved descriptor reaches the model. Server status reads the host's applied capability metadata. Neither status API exposes executable declarations, credentials, raw logs, or skill bodies.

Verification

pnpm nx run @agimon-ai/po-help:test
pnpm nx run @agimon-ai/po-help:typecheck
pnpm nx run @agimon-ai/po-help:lint

Tests cover contribution withdrawal and rollback, the real headless prompt and tool surface, explicit skill reading, deactivation, and remote MCP exclusion. Packed-install checks must also verify resource paths outside the checkout before release.

License

Business Source License 1.1: free for personal use, organisations under USD 1M revenue, non-profits and education. See LICENSE and https://agimon.ai/licensing.