Files

T

Dotta 9eac727cf1 [codex] Add skills CLI and catalog management (#6782 )

## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies through
company-scoped control-plane workflows.
> - Agents need reusable, inspectable skills that can be installed,
reset, audited, exported, and assigned without bespoke local setup.
> - The existing skill truth model needed cleanup so bundled skills,
optional catalog skills, runtime skills, and adapter-provided skills
have clear provenance.
> - Operators also need a practical CLI and board UI for discovering and
managing company skills.
> - This pull request adds the skills CLI, packaged skills catalog,
company skills APIs, and catalog-aware board UI.
> - The benefit is a more reusable Paperclip company setup where skills
are portable, auditable, and easier for operators and agents to manage.

## What Changed

- Added `paperclipai skills` CLI commands and coverage for catalog
listing, installing, resetting, and inspecting company skills.
- Added a packaged `@paperclipai/skills-catalog` workspace with bundled
and optional skill content plus validation/build tests.
- Added shared company-skill types and validators used across CLI,
server, and UI contracts.
- Added server catalog APIs/services for company skill catalog
operations, reset semantics, audit behavior, and portability provenance.
- Updated adapter skill handling so runtime/catalog provenance remains
explicit across local adapters.
- Added board UI support for browsing and managing catalog-backed
company skills.
- Updated docs for the skills CLI/catalog flow and the company skills
Paperclip skill reference.
- Rebased the branch onto current `paperclipai/paperclip:master`; no
`pnpm-lock.yaml`, `.github/workflows`, or migration files are included
in the final PR diff.

## Verification

- Passed: `pnpm run preflight:workspace-links && pnpm exec vitest run
cli/src/__tests__/skills.test.ts
packages/skills-catalog/src/catalog-builder.test.ts
packages/skills-catalog/src/shipped-catalog.test.ts
packages/shared/src/validators/company-skill.test.ts
packages/adapter-utils/src/server-utils.test.ts
packages/plugins/create-paperclip-plugin/src/entrypoints.test.ts
server/src/__tests__/company-skills-catalog-service.test.ts
server/src/__tests__/company-skills-routes.test.ts
server/src/__tests__/company-portability.test.ts`.
- Passed: `pnpm exec vitest run
server/src/__tests__/workspace-runtime.test.ts -t "default
branch|origin/master|symbolic-ref"`.
- Attempted: full `server/src/__tests__/workspace-runtime.test.ts`. Four
provisioning tests failed while seeding an isolated worktree database
from the local Paperclip instance because the local plugin schema dump
contains a duplicate-column foreign key
(`plugin_content_machine_18a7bc327b.content_case_signals`). The
default-branch tests touched by the rebase conflict passed in the
focused run above.
- Checked final diff: no `pnpm-lock.yaml`, no `.github/workflows`, and
no migration-file changes relative to `master`.

## Risks

- Medium: this is a broad skills/catalog change touching CLI, server
APIs, shared contracts, adapter skill sync, and UI.
- Catalog validation and reset semantics need careful reviewer attention
because they affect reusable company setup and portability.
- No database migrations are included in this PR, so there is no
migration ordering/idempotency risk in the final diff.
- No lockfile is included by design; dependency resolution will be
handled by the repository lockfile workflow.

## Model Used

- OpenAI Codex coding agent based on GPT-5, running in Paperclip via the
`codex_local` adapter with shell, git, GitHub CLI, and code-editing tool
access. Exact hosted model build/context-window metadata is not exposed
in this runtime.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have run targeted tests locally and documented the local
workspace-runtime seed failure above
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, screenshots were intentionally
omitted per PAP-10124 instructions; UI behavior is covered by tests and
reviewer inspection
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

2026-05-28 07:33:51 -10:00

9.7 KiB

Raw Blame History

2026-03-14 Adapter Skill Sync Rollout

Status: Implemented for local adapters; gateway remains unsupported Date: 2026-03-14 Audience: Product and engineering Related:

doc/plans/2026-03-14-skills-ui-product-plan.md
doc/plans/2026-03-13-company-import-export-v2.md
docs/companies/companies-spec.md

1. Purpose

This document defines the rollout plan for adapter-wide skill support in Paperclip.

The goal is not just “show a skills tab.” The goal is:

every adapter has a deliberate skill-sync truth model
the UI tells the truth for that adapter
Paperclip stores desired skill state consistently even when the adapter cannot fully reconcile it
unsupported adapters degrade clearly and safely

2. Current Adapter Matrix

Paperclip currently has these adapters:

claude_local
codex_local
cursor
gemini_local
grok_local
acpx_local
opencode_local
pi_local
openclaw_gateway

The current skill API supports:

unsupported
persistent
ephemeral

Current implementation state:

codex_local: implemented, ephemeral
claude_local: implemented, ephemeral
cursor: implemented, persistent
gemini_local: implemented, persistent
pi_local: implemented, persistent
opencode_local: implemented, persistent, with shared Claude skills home caveats
acpx_local: implemented, ephemeral for Claude/Codex sub-agents and unsupported for custom commands
grok_local: implemented, ephemeral
openclaw_gateway: not yet implemented; blocked on gateway protocol support, so unsupported for now

3. Product Principles

Desired skills live in Paperclip for every adapter.
Adapters may expose different truth models, and the UI must reflect that honestly.
Persistent adapters should read and reconcile actual installed state.
Ephemeral adapters should report effective runtime state, not pretend they own a persistent install.
Shared-home adapters need stronger safeguards than isolated-home adapters.
Gateway or cloud adapters must not fake local filesystem sync.

4. Adapter Classification

4.1 Persistent local-home adapters

These adapters have a stable local skills directory that Paperclip can read and manage.

Candidates:

cursor
gemini_local
pi_local
opencode_local with caveats

Expected UX:

show actual installed skills
show managed vs external skills
support sync
support stale removal
preserve unknown external skills

4.2 Ephemeral mount adapters

These adapters do not have a meaningful Paperclip-owned persistent install state.

Current adapter:

codex_local
claude_local
acpx_local when configured for Claude or Codex
grok_local

Expected UX:

show desired Paperclip skills
show any discoverable external dirs if available
say “mounted on next run” instead of “installed”
do not imply a persistent adapter-owned install state

4.3 Unsupported / remote adapters

These adapters cannot support skill sync without new external capabilities.

Current adapter:

acpx_local when configured for custom commands
openclaw_gateway

Expected UX:

company skill library still works
agent attachment UI still works at the desired-state level
actual adapter state is unsupported
sync button is disabled or replaced with explanatory text

5. Per-Adapter Plan

5.1 Codex Local

Target mode:

ephemeral

Current state:

already implemented

Requirements to finish:

keep runtime-mounted snapshots separate from persistent install snapshots
ensure imported company skills can be attached and mounted without manual path work
keep CODEX_HOME/skills mutation scoped to heartbeat execution, not skills/sync

Success criteria:

desired skills are stored in Paperclip
selected skills are linked into the effective CODEX_HOME/skills during runs
no persistent installed/stale state is reported from skills/sync

5.2 Claude Local

Target mode:

ephemeral

Current state:

already implemented

Requirements to finish:

polish status language in UI
clearly distinguish “desired” from “mounted on next run”
optionally surface configured external skill dirs if Claude exposes them

Success criteria:

desired skills stored in Paperclip
selected skills mounted per run
no misleading “installed” language

5.3 Cursor Local

Target mode:

persistent

Technical basis:

Paperclip reconciles desired skills into ~/.cursor/skills

Current state:

implemented

Testing:

unit tests for discovery
unit tests for sync and stale removal
verify shared auth/session setup is not disturbed

Success criteria:

Cursor agents show real installed state
syncing from the agent Skills tab works

5.4 Gemini Local

Target mode:

persistent

Technical basis:

Paperclip reconciles desired skills into ~/.gemini/skills

Current state:

implemented

Potential caveat:

if Gemini treats that skills directory as shared user state, the UI should warn before removing stale managed skills

Success criteria:

Gemini agents can reconcile desired vs actual skill state

5.5 Pi Local

Target mode:

persistent

Technical basis:

Paperclip reconciles desired skills into ~/.pi/agent/skills

Current state:

implemented

Success criteria:

Pi agents expose actual installed skill state
Paperclip can sync desired skills into Pi’s persistent home

5.6 OpenCode Local

Target mode:

persistent

Special case:

OpenCode currently injects Paperclip skills into ~/.claude/skills

This is product-risky because:

it shares state with Claude
Paperclip may accidentally imply the skills belong only to OpenCode when the home is shared

Plan:

implemented listSkills and syncSkills
treat it as persistent
explicitly label the home as shared in UI copy
only remove stale managed Paperclip skills that are clearly marked as Paperclip-managed

Phase 2:

investigate whether OpenCode supports its own isolated skills home
if yes, migrate to an adapter-specific home and remove the shared-home caveat

Success criteria:

OpenCode agents show real state
shared-home risk is visible and bounded

5.7 OpenClaw Gateway

Target mode:

unsupported until gateway protocol support exists

Required external work:

gateway API to list installed/available skills
gateway API to install/remove or otherwise reconcile skills
gateway metadata for whether state is persistent or ephemeral

Until then:

Paperclip stores desired skills only
UI shows unsupported actual state
no fake sync implementation

Future target:

likely a fourth truth model eventually, such as remote-managed persistent state
for now, keep the current API and treat gateway as unsupported

5.8 ACPX Local

Target mode:

ephemeral for built-in Claude/Codex ACPX sub-agents
unsupported for custom ACP commands

Success criteria:

Claude/Codex ACPX snapshots show skills as configured for the next session
custom command snapshots keep desired skills tracked only and do not imply runtime sync

5.9 Grok Local

Target mode:

ephemeral

Success criteria:

desired skills are stored in Paperclip
selected skills are copied into the execution workspace for the next run
no persistent installed/stale state is reported from skills/sync

6. API Plan

6.1 Keep the current minimal adapter API

Near-term adapter contract remains:

listSkills(ctx)
syncSkills(ctx, desiredSkills)

This is enough for all local adapters.

6.2 Optional extension points

Add only if needed after the first broad rollout:

skillHomeLabel
sharedHome: boolean
supportsExternalDiscovery: boolean
supportsDestructiveSync: boolean

These should be optional metadata additions to the snapshot, not required new adapter methods.

7. UI Plan

The company-level skill library can stay adapter-neutral.

The agent-level Skills tab must become adapter-aware by copy and status:

persistent: installed / missing / stale / external
ephemeral: mounted on next run / external / desired only
unsupported: desired only, adapter cannot report actual state

Additional UI requirement for shared-home adapters:

show a small warning that the adapter uses a shared user skills home
avoid destructive wording unless Paperclip can prove a skill is Paperclip-managed

8. Rollout Phases

Phase 1: Finish the local filesystem family

Ship:

cursor
gemini_local
pi_local

Status:

implemented

Phase 2: OpenCode shared-home support

Ship:

opencode_local

Status:

implemented with shared Claude skills-home warning

Phase 3: Gateway support decision

Decide:

keep openclaw_gateway unsupported for V1
or extend the gateway protocol for remote skill management

My recommendation:

do not block V1 on gateway support
keep it explicitly unsupported until the remote protocol exists

9. Definition Of Done

Adapter-wide skill support is ready when all are true:

Every adapter has an explicit truth model:
- persistent
- ephemeral
- unsupported
The UI copy matches that truth model.
All local persistent adapters implement:
- listSkills
- syncSkills
Tests cover:
- desired-state storage
- actual-state discovery
- managed vs external distinctions
- stale managed-skill cleanup where supported
openclaw_gateway is either:
- explicitly unsupported with clean UX
- or backed by a real remote skill API

10. Recommendation

The recommended immediate order is:

cursor
gemini_local
pi_local
opencode_local
defer openclaw_gateway

The local-adapter family now has explicit truth models. The remaining V1 boundary is openclaw_gateway, which should stay unsupported until the gateway protocol can report real remote skill state.

9.7 KiB Raw Blame History Unescape Escape

2026-03-14 Adapter Skill Sync Rollout

1. Purpose

2. Current Adapter Matrix

3. Product Principles

4. Adapter Classification

4.1 Persistent local-home adapters

4.2 Ephemeral mount adapters

4.3 Unsupported / remote adapters

5. Per-Adapter Plan

5.1 Codex Local

5.2 Claude Local

5.3 Cursor Local

5.4 Gemini Local

5.5 Pi Local

5.6 OpenCode Local

5.7 OpenClaw Gateway

5.8 ACPX Local

5.9 Grok Local

6. API Plan

6.1 Keep the current minimal adapter API

6.2 Optional extension points

7. UI Plan

8. Rollout Phases

Phase 1: Finish the local filesystem family

Phase 2: OpenCode shared-home support

Phase 3: Gateway support decision

9. Definition Of Done

10. Recommendation

9.7 KiB

Raw Blame History