aevgarik/paperclip
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update skill package docs and plans

Browse Source
This commit is contained in:
Dotta
2026-03-14 10:13:20 -05:00
parent 1d8f514d10
commit 58a9259a2e
3 changed files with 472 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
doc/plans/2026-03-13-company-import-export-v2.md
View File

@@ -45,7 +45,8 @@ The new direction is:
7. an always-emitted `.paperclip.yaml` sidecar for high-fidelity Paperclip-specific details
8. package graph resolution at import time
9. entity-level import UI with dependency-aware tree selection
10. adapter-aware skill sync surfaces so Paperclip can read, diff, enable, disable, and reconcile skills where the adapter supports it
10. `skills.sh` compatibility is a V1 requirement for skill packages and skill installation flows
11. adapter-aware skill sync surfaces so Paperclip can read, diff, enable, disable, and reconcile skills where the adapter supports it
## 3. Product Goals
@@ -59,6 +60,7 @@ The new direction is:
- agent definitions
- optional starter projects and tasks
- reusable skills
- V1 skill support is compatible with the existing `skills.sh` / Agent Skills ecosystem.
- A user can import into:
- a new company
- an existing company
@@ -130,8 +132,23 @@ Rules:
- the base package is vendor-neutral and intended for any agent-company runtime
- Paperclip-specific fidelity lives in `.paperclip.yaml`
- Paperclip may resolve and install `SKILL.md` packages, but it must not require a Paperclip-only skill format
- `skills.sh` compatibility is a V1 requirement, not a future nice-to-have
### 5.3 Base Package Vs Paperclip Extension
### 5.3 Agent-To-Skill Association
`AGENTS.md` should associate skills by skill shortname or slug, not by verbose path in the common case.
Preferred example:
- `skills: [review, react-best-practices]`
Resolution model:
- `review` resolves to `skills/review/SKILL.md` by package convention
- if the skill is external or referenced, the skill package owns that complexity
- exporters should prefer shortname-based associations in `AGENTS.md`
- importers should resolve the shortname against local package skills first, then referenced or installed company skills
### 5.4 Base Package Vs Paperclip Extension
The repo format should have two layers:
@@ -144,7 +161,7 @@ The repo format should have two layers:
- adapter/runtime/permissions/budget/workspace fidelity
- emitted by Paperclip tools as a sidecar while the base package stays readable
### 5.4 Relationship To Current V1 Manifest
### 5.5 Relationship To Current V1 Manifest
`paperclip.manifest.json` is not part of the future package direction.
@@ -513,11 +530,17 @@ If importing a team into an existing company:
### 13.3 Skills UX
See also:
- `doc/plans/2026-03-14-skills-ui-product-plan.md`
If importing skills:
- show whether each skill is local, vendored, or referenced
- show whether it contains scripts/assets
- preserve Agent Skills compatibility in presentation and export
- preserve `skills.sh` compatibility in both import and install flows
- show agent skill attachments by shortname/slug rather than noisy file paths
- show current adapter-reported skills when supported
- show desired package skills separately from actual adapter state
- offer reconcile actions when the adapter supports sync
@@ -536,6 +559,9 @@ If importing skills:
- support `COMPANY.md` / `TEAM.md` / `AGENTS.md` root detection
- build internal graph from markdown-first packages
- support local folder and GitHub repo inputs natively
- support agent skill references by shortname/slug
- resolve local `skills/<slug>/SKILL.md` packages by convention
- support `skills.sh`-compatible skill repos as V1 package sources
### Phase 3: Graph-Based Import UX And Skill Surfaces
@@ -543,6 +569,7 @@ If importing skills:
- checkbox selection
- team subtree attach flow
- licensing/trust/reference warnings
- company skill library groundwork
- adapter skill read/sync UI groundwork
### Phase 4: New Export Model

418
doc/plans/2026-03-14-skills-ui-product-plan.md Normal file
View File

@@ -0,0 +1,418 @@
# 2026-03-14 Skills UI Product Plan
Status: Proposed
Date: 2026-03-14
Audience: Product and engineering
Related:
- `doc/plans/2026-03-13-company-import-export-v2.md`
- `docs/companies/companies-spec.md`
- `ui/src/pages/AgentDetail.tsx`
## 1. Purpose
This document defines the product and UI plan for skill management in Paperclip.
The goal is to make skills understandable and manageable in the website without pretending that all adapters behave the same way.
This plan assumes:
- `SKILL.md` remains Agent Skills compatible
- `skills.sh` compatibility is a V1 requirement
- Paperclip company import/export can include skills as package content
- adapters may support persistent skill sync, ephemeral skill mounting, read-only skill discovery, or no skill integration at all
## 2. Current State
There is already a first-pass agent-level skill sync UI on `AgentDetail`.
Today it supports:
- loading adapter skill sync state
- showing unsupported adapters clearly
- showing managed skills as checkboxes
- showing external skills separately
- syncing desired skills for adapters that implement the new API
Current limitations:
1. There is no company-level skill library UI.
2. There is no package import flow for skills in the website.
3. There is no distinction between skill package management and per-agent skill attachment.
4. There is no multi-agent desired-vs-actual view.
5. The current UI is adapter-sync-oriented, not package-oriented.
6. Unsupported adapters degrade safely, but not elegantly.
## 3. Product Principles
1. Skills are company assets first, agent attachments second.
2. Package management and adapter sync are different concerns and should not be conflated in one screen.
3. The UI must always tell the truth about what Paperclip knows:
- desired state in Paperclip
- actual state reported by the adapter
- whether the adapter can reconcile the two
4. Agent Skills compatibility must remain visible in the product model.
5. Agent-to-skill associations should be human-readable and shortname-based wherever possible.
6. Unsupported adapters should still have a useful UI, not just a dead end.
## 4. User Model
Paperclip should treat skills at two scopes:
### 4.1 Company skills
These are reusable skills known to the company.
Examples:
- imported from a GitHub repo
- added from a local folder
- installed from a `skills.sh`-compatible repo
- created locally inside Paperclip later
These should have:
- name
- description
- slug or package identity
- source/provenance
- trust level
- compatibility status
### 4.2 Agent skills
These are skill attachments for a specific agent.
Each attachment should have:
- shortname
- desired state in Paperclip
- actual state in the adapter when readable
- sync status
- origin
Agent attachments should normally reference skills by shortname or slug, for example:
- `review`
- `react-best-practices`
not by noisy relative file path.
## 5. Core UI Surfaces
The product should have two primary skill surfaces.
### 5.1 Company Skills page
Add a company-level page, likely:
- `/companies/:companyId/skills`
Purpose:
- manage the company skill library
- import and inspect skill packages
- understand provenance and trust
- see which agents use which skills
#### A. Skill library list
Each skill row should show:
- name
- short description
- source badge
- trust badge
- compatibility badge
- number of attached agents
Suggested source states:
- local
- github
- imported package
- external reference
- adapter-discovered only
Suggested compatibility states:
- compatible
- paperclip-extension
- unknown
- invalid
Suggested trust states:
- markdown-only
- assets
- scripts/executables
#### B. Import actions
Allow:
- import from local folder
- import from GitHub URL
- import from direct URL
Future:
- install from `companies.sh`
- install from `skills.sh`
#### C. Skill detail drawer or page
Each skill should have a detail view showing:
- rendered `SKILL.md`
- package source and pinning
- included files
- trust and licensing warnings
- who uses it
- adapter compatibility notes
### 5.2 Agent Skills panel
Keep and evolve the existing `AgentDetail` skills section.
Purpose:
- attach/detach company skills to one agent
- inspect adapter reality for that agent
- reconcile desired vs actual state
- keep the association format readable and aligned with `AGENTS.md`
#### A. Desired skills
Show company-managed skills attached to the agent.
Each row should show:
- skill name
- shortname
- sync state
- source
- last adapter observation if available
#### B. External or discovered skills
Show skills reported by the adapter that are not company-managed.
This matters because Codex and similar adapters may already have local skills that Paperclip did not install.
These should be clearly marked:
- external
- not managed by Paperclip
#### C. Sync controls
Support:
- sync
- reset draft
- detach
Future:
- import external skill into company library
- promote ad hoc local skill into a managed company skill
## 6. Skill State Model In The UI
Each skill attachment should have a user-facing state.
Suggested states:
- `in_sync`
- `desired_only`
- `external`
- `drifted`
- `unmanaged`
- `unknown`
Definitions:
- `in_sync`: desired and actual match
- `desired_only`: Paperclip wants it, adapter does not show it yet
- `external`: adapter has it but Paperclip does not manage it
- `drifted`: adapter has a conflicting or unexpected version/location
- `unmanaged`: adapter does not support sync, Paperclip only tracks desired state
- `unknown`: adapter read failed or state cannot be trusted
## 7. Adapter Presentation Rules
The UI should not describe all adapters the same way.
### 7.1 Persistent adapters
Example:
- Codex local
Language:
- installed
- synced into adapter home
- external skills detected
### 7.2 Ephemeral adapters
Example:
- Claude local
Language:
- will be mounted on next run
- effective runtime skills
- not globally installed
### 7.3 Unsupported adapters
Language:
- this adapter does not implement skill sync yet
- Paperclip can still track desired skills
- actual adapter state is unavailable
This state should still allow:
- attaching company skills to the agent as desired state
- export/import of those desired attachments
## 8. Information Architecture
Recommended navigation:
- company nav adds `Skills`
- agent detail keeps `Skills` inside configuration for now
Later, if the skill system grows:
- company-level `Skills` page
- optional skill detail route
- optional skill usage graph view
Recommended separation:
- Company Skills page answers: “What skills do we have?”
- Agent Skills panel answers: “What does this agent use, and is it synced?”
## 9. Import / Export Integration
Skill UI and package portability should meet in the company skill library.
Import behavior:
- importing a company package with `SKILL.md` content should create or update company skills
- agent attachments should primarily come from `AGENTS.md` shortname associations
- `.paperclip.yaml` may add Paperclip-specific fidelity, but should not replace the base shortname association model
- referenced third-party skills should keep provenance visible
Export behavior:
- exporting a company should include company-managed skills when selected
- `AGENTS.md` should emit skill associations by shortname or slug
- `.paperclip.yaml` may add Paperclip-specific skill fidelity later if needed, but should not be required for ordinary agent-to-skill association
- adapter-only external skills should not be silently exported as managed company skills
## 10. Data And API Shape
This plan implies a clean split in backend concepts.
### 10.1 Company skill records
Paperclip should have a company-scoped skill model or managed package model representing:
- identity
- source
- files
- provenance
- trust and licensing metadata
### 10.2 Agent skill attachments
Paperclip should separately store:
- agent id
- skill identity
- desired enabled state
- optional ordering or metadata later
### 10.3 Adapter sync snapshot
Adapter reads should return:
- supported flag
- sync mode
- entries
- warnings
- desired skills
This already exists in rough form and should be the basis for the UI.
## 11. UI Phases
### Phase A: Stabilize current agent skill sync UI
Goals:
- keep current `AgentDetail` panel
- improve status language
- support desired-only state even on unsupported adapters
- polish copy for persistent vs ephemeral adapters
### Phase B: Add Company Skills page
Goals:
- company-level skill library
- import from GitHub/local folder
- basic detail view
- usage counts by agent
### Phase C: Connect skills to portability
Goals:
- importing company packages creates company skills
- exporting selected skills works cleanly
- agent attachments round-trip through `.paperclip.yaml`
### Phase D: External skill adoption flow
Goals:
- detect adapter external skills
- allow importing them into company-managed state where possible
- make provenance explicit
### Phase E: Advanced sync and drift UX
Goals:
- desired-vs-actual diffing
- drift resolution actions
- multi-agent skill usage and sync reporting
## 12. Design Risks
1. Overloading the agent page with package management will make the feature confusing.
2. Treating unsupported adapters as broken rather than unmanaged will make the product feel inconsistent.
3. Mixing external adapter-discovered skills with company-managed skills without clear labels will erode trust.
4. If company skill records do not exist, import/export and UI will remain loosely coupled and round-trip fidelity will stay weak.
## 13. Recommendation
The next product step should be:
1. keep the current agent-level skill sync panel as the short-term attachment UI
2. add a dedicated company-level `Skills` page as the library and package-management surface
3. make company import/export target that company skill library, not the agent page directly
4. preserve adapter-aware truth in the UI by clearly separating:
- desired
- actual
- external
- unmanaged
That gives Paperclip one coherent skill story instead of forcing package management, adapter sync, and agent configuration into the same screen.

26
docs/companies/companies-spec.md
View File

@@ -191,17 +191,38 @@ name: CEO
title: Chief Executive Officer
reportsTo: null
skills:
- ../../skills/plan-ceo-review/SKILL.md
- plan-ceo-review
- review
```
### Semantics
- body content is the canonical default instruction content for the agent
- `docs` points to sibling markdown docs when present
- `skills` references reusable `SKILL.md` packages
- `skills` references reusable `SKILL.md` packages by skill shortname or slug
- a bare skill entry like `review` should resolve to `skills/review/SKILL.md` by convention
- if a package references external skills, the agent should still refer to the skill by shortname; the skill package itself owns any source refs, pinning, or attribution details
- tools may allow path or URL entries as an escape hatch, but exporters should prefer shortname-based skill references in `AGENTS.md`
- vendor-specific adapter/runtime config should not live in the base package
- local absolute paths, machine-specific cwd values, and secret values must not be exported as canonical package data
### Skill Resolution
The preferred association standard between agents and skills is by skill shortname.
Suggested resolution order for an agent skill entry:
1. a local package skill at `skills/<shortname>/SKILL.md`
2. a referenced or included skill package whose declared slug or shortname matches
3. a tool-managed company skill library entry with the same shortname
Rules:
- exporters should emit shortnames in `AGENTS.md` whenever possible
- importers should not require full file paths for ordinary skill references
- the skill package itself should carry any complexity around external refs, vendoring, mirrors, or pinned upstream content
- this keeps `AGENTS.md` readable and consistent with `skills.sh`-style sharing
## 9. PROJECT.md
`PROJECT.md` defines a lightweight project package.
@@ -313,6 +334,7 @@ Rules:
- Paperclip must not require extra top-level fields for skill validity
- Paperclip-specific extensions must live under `metadata.paperclip` or `metadata.sources`
- a skill directory may include `scripts/`, `references/`, and `assets/` exactly as the Agent Skills ecosystem expects
- tools implementing this spec should treat `skills.sh` compatibility as a first-class goal rather than inventing a parallel skill format
In other words, this spec extends Agent Skills upward into company/team/agent composition. It does not redefine skill package semantics.