[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>
This commit is contained in:
Dotta
@@ -4,16 +4,21 @@ Use this reference when a board user, CEO, or manager asks you to find a skill,
|
||||
|
||||
## What Exists
|
||||
|
||||
- Company skill library: install, inspect, update, and read imported skills for the whole company.
|
||||
- App-shipped catalog: a curated set of company skills in `@paperclipai/skills-catalog`, browseable and installable without leaving Paperclip.
|
||||
- Company skill library: install, inspect, update, audit, reset, and read company skills for the whole company.
|
||||
- Agent skill assignment: add or remove company skills on an existing agent.
|
||||
- Hire/create composition: pass `desiredSkills` when creating or hiring an agent so the same assignment model applies immediately.
|
||||
|
||||
The canonical model is:
|
||||
|
||||
1. install the skill into the company
|
||||
2. assign the company skill to the agent
|
||||
1. add the skill to the company library — either from the app catalog (`skills install`), an external source (`skills import`), or a managed local skill (`skills create`/`skills scan-projects`)
|
||||
2. attach the company skill to the agent (`skills agent sync`)
|
||||
3. optionally do step 2 during hire/create with `desiredSkills`
|
||||
|
||||
Catalog install ≠ agent attach. Installing a catalog skill only adds the row to
|
||||
`company_skills`. The agent will not use it until you sync the agent's desired
|
||||
set.
|
||||
|
||||
## Permission Model
|
||||
|
||||
- Company skill reads: any same-company actor
|
||||
@@ -22,18 +27,78 @@ The canonical model is:
|
||||
|
||||
## Core Endpoints
|
||||
|
||||
App-shipped catalog (read-only browse + company install):
|
||||
|
||||
- `GET /api/skills/catalog`
|
||||
- `GET /api/skills/catalog/:catalogId`
|
||||
- `GET /api/skills/catalog/ref?ref=<id|key|slug>`
|
||||
- `GET /api/skills/catalog/:catalogId/files?path=SKILL.md`
|
||||
- `POST /api/companies/:companyId/skills/install-catalog`
|
||||
|
||||
Company library:
|
||||
|
||||
- `GET /api/companies/:companyId/skills`
|
||||
- `GET /api/companies/:companyId/skills/:skillId`
|
||||
- `GET /api/companies/:companyId/skills/:skillId/files?path=SKILL.md`
|
||||
- `POST /api/companies/:companyId/skills` (managed local create)
|
||||
- `POST /api/companies/:companyId/skills/import`
|
||||
- `POST /api/companies/:companyId/skills/scan-projects`
|
||||
- `GET /api/companies/:companyId/skills/:skillId/update-status`
|
||||
- `POST /api/companies/:companyId/skills/:skillId/install-update`
|
||||
- `POST /api/companies/:companyId/skills/:skillId/audit`
|
||||
- `POST /api/companies/:companyId/skills/:skillId/reset`
|
||||
- `DELETE /api/companies/:companyId/skills/:skillId`
|
||||
|
||||
Agent attach and hire/create composition:
|
||||
|
||||
- `GET /api/agents/:agentId/skills`
|
||||
- `POST /api/agents/:agentId/skills/sync`
|
||||
- `POST /api/companies/:companyId/agent-hires`
|
||||
- `POST /api/companies/:companyId/agents`
|
||||
|
||||
If a board user, CEO, or manager is driving locally, prefer the
|
||||
`paperclipai skills` CLI documented in `doc/CLI.md` — it wraps every endpoint
|
||||
above, accepts company skill or catalog refs by `id`/`key`/`slug`, and prints
|
||||
the same JSON these endpoints return when called with `--json`.
|
||||
|
||||
## Install A Skill Into The Company
|
||||
|
||||
Two paths cover the common cases:
|
||||
|
||||
1. **App-shipped catalog** (preferred when the right skill exists in the
|
||||
bundled/optional catalog) — browse it first, then install with the catalog
|
||||
install endpoint. No external network fetch happens.
|
||||
2. **External source** (skills.sh, GitHub, local path, or URL) — use the
|
||||
import endpoint below.
|
||||
|
||||
### App-shipped catalog
|
||||
|
||||
Browse, inspect, and install catalog skills before reaching for an external
|
||||
source. Bundled skills are the curated defaults for any company; optional
|
||||
skills are role- or domain-specific.
|
||||
|
||||
```sh
|
||||
curl -sS "$PAPERCLIP_API_URL/api/skills/catalog?kind=bundled" \
|
||||
-H "Authorization: Bearer $PAPERCLIP_API_KEY"
|
||||
|
||||
curl -sS "$PAPERCLIP_API_URL/api/skills/catalog/ref?ref=github-pr-workflow" \
|
||||
-H "Authorization: Bearer $PAPERCLIP_API_KEY"
|
||||
|
||||
curl -sS -X POST "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/skills/install-catalog" \
|
||||
-H "Authorization: Bearer $PAPERCLIP_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"catalogSkillId": "paperclipai:bundled:software-development:github-pr-workflow"
|
||||
}'
|
||||
```
|
||||
|
||||
The install response records provenance (`catalogId`, `catalogKey`,
|
||||
`packageVersion`, `originHash`) on the company skill so update/audit/reset
|
||||
flows know the pinned origin. `force: true` may replace a same-key
|
||||
catalog-managed skill but never bypasses hard-stop audit findings.
|
||||
|
||||
### External source import
|
||||
|
||||
Import using a **skills.sh URL**, a key-style source string, a GitHub URL, or a local path.
|
||||
|
||||
### Source types (in order of preference)
|
||||
|
||||
Reference in New Issue
Block a user