The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
Update skill package docs and plans
Dotta58a9259a2eab
diff --git a/doc/plans/2026-03-13-company-import-export-v2.md b/doc/plans/2026-03-13-company-import-export-v2.mdindex d492961786..5a3426659f 100644--- a/doc/plans/2026-03-13-company-import-export-v2.md+++ b/doc/plans/2026-03-13-company-import-export-v2.md@@ -45,7 +45,8 @@ The new direction is:7. an always-emitted `.paperclip.yaml` sidecar for high-fidelity Paperclip-specific details8. package graph resolution at import time9. 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 ExtensionThe 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 Modeldiff --git a/doc/plans/2026-03-14-skills-ui-product-plan.md b/doc/plans/2026-03-14-skills-ui-product-plan.mdnew file mode 100644index 0000000000..2dcdb52c36--- /dev/null+++ b/doc/plans/2026-03-14-skills-ui-product-plan.md@@ -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.diff --git a/docs/companies/companies-spec.md b/docs/companies/companies-spec.mdindex de7f9b03da..17fa8ef3b1 100644--- a/docs/companies/companies-spec.md+++ b/docs/companies/companies-spec.md@@ -191,17 +191,38 @@ name: CEOtitle: Chief Executive OfficerreportsTo: nullskills:- - ../../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 formatIn other words, this spec extends Agent Skills upward into company/team/agent composition. It does not redefine skill package semantics.