popski-platform

An Agent Skill for building, deploying, and managing static apps on apps.pop.ski — the self-hosted platform behind pop.ski. Teaches AI coding agents (Claude Code, OpenCode, Cursor, Copilot, and others) the full lifecycle: Forgejo repo creation, registry.yaml configuration, the typed SQLite data API (sqlc-generated), wiring up LLM agents, OpenTelemetry instrumentation, and platform debugging.

Install as an Agent Skill

npx skills add https://git.pop.ski/peter/popski-platform

Contents

• SKILL.md — architecture overview, auth model, typed data API.
• references/create-app.md — step-by-step app lifecycle.
• references/design-guide.md — UI/UX design guide, Basecoat UI component library.
• references/registry-schema.md — full registry.yaml field reference.
• references/structured-data-api.md — schema.sql/queries.sql, sqlc, wire format.
• references/agent-api.md — LLM agent HTTP endpoints, SSE events.
• references/authentication.md — Authentik sessions, canonical accounts, roles, and workspace boundaries.
• references/forgejo-cli.md — using fgj/tea for git.pop.ski.
• references/distributed-tracing.md — OpenTelemetry setup and trace viewing.

Source of truth

This repo is the canonical, standalone copy. It was previously embedded and served directly from the apps.pop.ski app-registry service; it now lives here so it installs the normal way via npx skills add <git-url>.

Plugin and marketplace packaging

This repository is also a skills-only plugin and a private one-plugin marketplace for Codex/ChatGPT and Claude Code. It has no MCP server, lifecycle hooks, bundled credentials, or automatic installation. Host marketplace availability varies; this is not a listing in a universal public directory.

The portable root plugin.json and Codex compatibility manifest both load the single canonical skills/popski-platform directory. Claude uses its own plugin manifest and the same skills directory. Separate .agents/plugins/marketplace.json and .claude-plugin/marketplace.json catalogs describe the same popski marketplace.

For Codex CLI:

codex plugin marketplace add git@git.pop.ski:peter/popski-platform.git
codex plugin marketplace list
codex plugin add popski-platform@popski

In supported ChatGPT desktop clients, register this repository as a marketplace source through the client's plugin settings, then install popski-platform from popski. The .agents/plugins/marketplace.json file supplies its catalog; committing the file alone does not register the source in your client.

For Claude Code:

/plugin marketplace add git@git.pop.ski:peter/popski-platform.git
/plugin install popski-platform@popski

Access to this private Forgejo repo requires your own Git/SSH credentials. Plugin installation does not grant access to the platform, enroll devices, deploy apps, or connect accounts. Use either the plugin or the standalone skill installation in a host, rather than installing both copies. Hosted plugin installations are cached; after updates, refresh the marketplace and update the installed plugin.

Maintainer validation

Keep the plugin manifests, marketplace entry and skill version in sync. Run:

uv run --with pyyaml --no-project python scripts/validate.py
claude plugin validate .

These checks validate package structure, references and examples; they do not install the plugin or verify authentication against the live platform. Public directory submission is separate: the repository currently has no declared license or listing icon, which Claude reports in its directory submission checks. Choose a license before submitting it publicly.

The skill uses the current Authentik/capability contract. Workspace instructions require an app-registry image containing PR #25; verify the deployed revision before creating a private app or assuming a merge has deployed.