SKILL.md
Polpo Projects
Treat the checked-out project and the installed CLI as authoritative. Do not recreate legacy .polpo/polpo.json or .polpo/agents.json layouts except when explicitly migrating them.
Workflow
- Inspect the repository,
.polpo/, package.json, and the installed polpo CLI version.
- Preserve an existing linked project. Create or link only when the user requests it or no
project exists.
- Author resources in layout v2: project metadata, one directory per agent, project Loop
definitions, teams, skills, and the skill lockfile.
- Validate locally before deployment. Resolve unknown references and packaging failures rather
than relying on a second identical deploy.
- Deploy through the CLI or supported workflow. Never place provider secrets in project files.
- Report the project, resources changed, validation performed, and whether anything still
requires Cloud provisioning or rollout.
Project Boundaries
- OSS owns portable contracts, schemas, runtime behavior, SDKs, CLI behavior, and self-hosted
adapters.
- Cloud owns managed tenancy, billing, rollout, hosted storage, provider automation, secure
credential custody, and managed reconciliation.
- A Cloud feature should consume an OSS primitive when the behavior is generally useful to a
self-hosted runtime. Do not model portable runtime behavior as dashboard-only configuration.
References
- Read [references/project-layout.md](references/project-layout.md) before creating or migrating
.polpo/ files.
- Read [references/cli-and-deploy.md](references/cli-and-deploy.md) for bootstrap, linking,
validation, deployment, pull, skills, and failure semantics.
- Read [references/platform-boundaries.md](references/platform-boundaries.md) when deciding OSS
versus Cloud ownership or diagnosing managed-only behavior.
- Read [references/contract-version.md](references/contract-version.md) before relying on exact
fields or commands in a different Polpo release.
Specialized Skills
polpo-agents: agent definitions, models, policies, skills, memory, and sandbox defaults.
polpo-runtime: completions, Sessions, durable runs, Project Loops, steering, and schedules.
polpo-channels: messaging providers, provisioning, routing, media, and trusted identity.
polpo-integrations: Connections, custom tools, hidden bindings, MCP, and OAuth.
polpo-react: React hooks, chat UI, durable reconnect, interactions, and client tools.