Update skill package docs and plans
This commit is contained in:
Dotta
@@ -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
418
doc/plans/2026-03-14-skills-ui-product-plan.md
Normal 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.
|
||||
Reference in New Issue
Block a user