Expand skills UI product plan

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

@@ -541,6 +541,7 @@ If importing skills:
 - 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
+- treat agent skills as a dedicated agent tab, not just another subsection of configuration
 - show current adapter-reported skills when supported
 - show desired package skills separately from actual adapter state
 - offer reconcile actions when the adapter supports sync
@@ -570,6 +571,7 @@ If importing skills:
 - team subtree attach flow
 - licensing/trust/reference warnings
 - company skill library groundwork
+- dedicated agent `Skills` tab groundwork
 - adapter skill read/sync UI groundwork
 
 ### Phase 4: New Export Model

doc/plans/2026-03-14-skills-ui-product-plan.md

@@ -42,6 +42,16 @@ Current limitations:
 5. The current UI is adapter-sync-oriented, not package-oriented.
 6. Unsupported adapters degrade safely, but not elegantly.
 
+## 2.1 V1 Decisions
+
+For V1, this plan assumes the following product decisions are already made:
+
+1. `skills.sh` compatibility is required.
+2. Agent-to-skill association in `AGENTS.md` is by shortname or slug.
+3. Company skills and agent skill attachments are separate concepts.
+4. Agent skills should move to their own tab rather than living inside configuration.
+5. Company import/export should eventually round-trip skill packages and agent skill attachments.
+
 ## 3. Product Principles
 
 1. Skills are company assets first, agent attachments second.
@@ -97,6 +107,18 @@ Agent attachments should normally reference skills by shortname or slug, for exa
 
 not by noisy relative file path.
 
+## 4.3 Primary user jobs
+
+The UI should support these jobs cleanly:
+
+1. “Show me what skills this company has.”
+2. “Import a skill from GitHub or a local folder.”
+3. “See whether a skill is safe, compatible, and who uses it.”
+4. “Attach skills to an agent.”
+5. “See whether the adapter actually has those skills.”
+6. “Reconcile desired vs actual skill state.”
+7. “Understand what Paperclip knows vs what the adapter knows.”
+
 ## 5. Core UI Surfaces
 
 The product should have two primary skill surfaces.
@@ -114,6 +136,27 @@ Purpose:
 - understand provenance and trust
 - see which agents use which skills
 
+#### Route
+
+- `/companies/:companyId/skills`
+
+#### Primary actions
+
+- import skill
+- inspect skill
+- attach to agents
+- detach from agents
+- export selected skills later
+
+#### Empty state
+
+When the company has no managed skills:
+
+- explain what skills are
+- explain `skills.sh` / Agent Skills compatibility
+- offer `Import from GitHub` and `Import from folder`
+- optionally show adapter-discovered skills as a secondary “not managed yet” section
+
 #### A. Skill library list
 
 Each skill row should show:
@@ -146,6 +189,14 @@ Suggested trust states:
 - assets
 - scripts/executables
 
+Suggested list affordances:
+
+- search by name or slug
+- filter by source
+- filter by trust level
+- filter by usage
+- sort by name, recent import, usage count
+
 #### B. Import actions
 
 Allow:
@@ -159,6 +210,10 @@ Future:
 - install from `companies.sh`
 - install from `skills.sh`
 
+V1 requirement:
+
+- importing from a `skills.sh`-compatible source should work without requiring a Paperclip-specific package layout
+
 #### C. Skill detail drawer or page
 
 Each skill should have a detail view showing:
@@ -170,9 +225,34 @@ Each skill should have a detail view showing:
 - who uses it
 - adapter compatibility notes
 
-### 5.2 Agent Skills panel
+Recommended route:
 
-Keep and evolve the existing `AgentDetail` skills section.
+- `/companies/:companyId/skills/:skillId`
+
+Recommended sections:
+
+- Overview
+- Contents
+- Usage
+- Source
+- Trust / licensing
+
+#### D. Usage view
+
+Each company skill should show which agents use it.
+
+Suggested columns:
+
+- agent
+- desired state
+- actual state
+- adapter
+- sync mode
+- last sync status
+
+### 5.2 Agent Skills tab
+
+Keep and evolve the existing `AgentDetail` skill sync UI, but move it out of configuration.
 
 Purpose:
 
@@ -181,6 +261,42 @@ Purpose:
 - reconcile desired vs actual state
 - keep the association format readable and aligned with `AGENTS.md`
 
+#### Route
+
+- `/agents/:agentId/skills`
+
+#### Agent tabs
+
+The intended agent-level tab model becomes:
+
+- `dashboard`
+- `configuration`
+- `skills`
+- `runs`
+
+This is preferable to hiding skills inside configuration because:
+
+- skills are not just adapter config
+- skills need their own sync/status language
+- skills are a reusable company asset, not merely one agent field
+- the screen needs room for desired vs actual state, warnings, and external skill adoption
+
+#### Tab layout
+
+The `Skills` tab should have three stacked sections:
+
+1. Summary
+2. Managed skills
+3. External / discovered skills
+
+Summary should show:
+
+- adapter sync support
+- sync mode
+- number of managed skills
+- number of external skills
+- drift or warning count
+
 #### A. Desired skills
 
 Show company-managed skills attached to the agent.
@@ -193,6 +309,13 @@ Each row should show:
 - source
 - last adapter observation if available
 
+Each row should support:
+
+- enable / disable
+- open skill detail
+- see source badge
+- see sync badge
+
 #### B. External or discovered skills
 
 Show skills reported by the adapter that are not company-managed.
@@ -204,6 +327,12 @@ These should be clearly marked:
 - external
 - not managed by Paperclip
 
+Each external row should support:
+
+- inspect
+- adopt into company library later
+- attach as managed skill later if appropriate
+
 #### C. Sync controls
 
 Support:
@@ -217,6 +346,12 @@ Future:
 - import external skill into company library
 - promote ad hoc local skill into a managed company skill
 
+Recommended footer actions:
+
+- `Sync skills`
+- `Reset`
+- `Refresh adapter state`
+
 ## 6. Skill State Model In The UI
 
 Each skill attachment should have a user-facing state.
@@ -239,6 +374,15 @@ Definitions:
 - `unmanaged`: adapter does not support sync, Paperclip only tracks desired state
 - `unknown`: adapter read failed or state cannot be trusted
 
+Suggested badge copy:
+
+- `In sync`
+- `Needs sync`
+- `External`
+- `Drifted`
+- `Unmanaged`
+- `Unknown`
+
 ## 7. Adapter Presentation Rules
 
 The UI should not describe all adapters the same way.
@@ -280,23 +424,43 @@ This state should still allow:
 - attaching company skills to the agent as desired state
 - export/import of those desired attachments
 
+## 7.4 Read-only adapters
+
+Some adapters may be able to list skills but not mutate them.
+
+Language:
+
+- Paperclip can see adapter skills
+- this adapter does not support applying changes
+- desired state can be tracked, but reconciliation is manual
+
 ## 8. Information Architecture
 
 Recommended navigation:
 
 - company nav adds `Skills`
-- agent detail keeps `Skills` inside configuration for now
+- agent detail adds `Skills` as its own tab
-
+- company skill detail gets its own route when the company library ships
-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?”
+- Agent Skills tab answers: “What does this agent use, and is it synced?”
+
+## 8.1 Proposed route map
+
+- `/companies/:companyId/skills`
+- `/companies/:companyId/skills/:skillId`
+- `/agents/:agentId/skills`
+
+## 8.2 Nav and discovery
+
+Recommended entry points:
+
+- company sidebar: `Skills`
+- agent page tabs: `Skills`
+- company import preview: link imported skills to company skills page later
+- agent skills rows: link to company skill detail
 
 ## 9. Import / Export Integration
 
@@ -316,6 +480,35 @@ Export behavior:
 - `.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
 
+## 9.1 Import workflows
+
+V1 workflows should support:
+
+1. import one or more skills from a local folder
+2. import one or more skills from a GitHub repo
+3. import a company package that contains skills
+4. attach imported skills to one or more agents
+
+Import preview for skills should show:
+
+- skills discovered
+- source and pinning
+- trust level
+- licensing warnings
+- whether an existing company skill will be created, updated, or skipped
+
+## 9.2 Export workflows
+
+V1 should support:
+
+1. export a company with managed skills included when selected
+2. export an agent whose `AGENTS.md` contains shortname skill associations
+3. preserve Agent Skills compatibility for each `SKILL.md`
+
+Out of scope for V1:
+
+- exporting adapter-only external skills as managed packages automatically
+
 ## 10. Data And API Shape
 
 This plan implies a clean split in backend concepts.
@@ -351,13 +544,127 @@ Adapter reads should return:
 
 This already exists in rough form and should be the basis for the UI.
 
-## 11. UI Phases
+### 10.4 UI-facing API needs
+
+The complete UI implies these API surfaces:
+
+- list company-managed skills
+- import company skills from path/URL/GitHub
+- get one company skill detail
+- list agents using a given skill
+- attach/detach company skills for an agent
+- list adapter sync snapshot for an agent
+- apply desired skills for an agent
+
+Existing agent-level skill sync APIs can remain the base for the agent tab.
+The company-level library APIs still need to be designed and implemented.
+
+## 11. Page-by-page UX
+
+### 11.1 Company Skills list page
+
+Header:
+
+- title
+- short explanation of compatibility with Agent Skills / `skills.sh`
+- import button
+
+Body:
+
+- filters
+- skill table or cards
+- empty state when none
+
+Secondary content:
+
+- warnings panel for untrusted or incompatible skills
+
+### 11.2 Company Skill detail page
+
+Header:
+
+- skill name
+- shortname
+- source badge
+- trust badge
+- compatibility badge
+
+Sections:
+
+- rendered `SKILL.md`
+- files and references
+- usage by agents
+- source / provenance
+- trust and licensing warnings
+
+Actions:
+
+- attach to agent
+- remove from company library later
+- export later
+
+### 11.3 Agent Skills tab
+
+Header:
+
+- adapter support summary
+- sync mode
+- refresh and sync actions
+
+Body:
+
+- managed skills list
+- external/discovered skills list
+- warnings / unsupported state block
+
+## 12. States And Empty Cases
+
+### 12.1 Company Skills page
+
+States:
+
+- empty
+- loading
+- loaded
+- import in progress
+- import failed
+
+### 12.2 Company Skill detail
+
+States:
+
+- loading
+- not found
+- incompatible
+- loaded
+
+### 12.3 Agent Skills tab
+
+States:
+
+- loading snapshot
+- unsupported adapter
+- read-only adapter
+- sync-capable adapter
+- sync failed
+- stale draft
+
+## 13. Permissions And Governance
+
+Suggested V1 policy:
+
+- board users can manage company skills
+- board users can attach skills to agents
+- agents themselves do not mutate company skill library by default
+- later, certain agents may get scoped permissions for skill attachment or sync
+
+## 14. UI Phases
 
 ### Phase A: Stabilize current agent skill sync UI
 
 Goals:
 
-- keep current `AgentDetail` panel
+- move skills to an `AgentDetail` tab
 - improve status language
 - support desired-only state even on unsupported adapters
 - polish copy for persistent vs ephemeral adapters
@@ -370,6 +677,7 @@ Goals:
 - import from GitHub/local folder
 - basic detail view
 - usage counts by agent
+- `skills.sh`-compatible import path
 
 ### Phase C: Connect skills to portability
 
@@ -377,7 +685,7 @@ Goals:
 
 - importing company packages creates company skills
 - exporting selected skills works cleanly
-- agent attachments round-trip through `.paperclip.yaml`
+- agent attachments round-trip primarily through `AGENTS.md` shortnames
 
 ### Phase D: External skill adoption flow
 
@@ -395,18 +703,19 @@ Goals:
 - drift resolution actions
 - multi-agent skill usage and sync reporting
 
-## 12. Design Risks
+## 15. 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.
+5. If agent skill associations are path-based instead of shortname-based, the format will feel too technical and too Paperclip-specific.
 
-## 13. Recommendation
+## 16. Recommendation
 
 The next product step should be:
 
-1. keep the current agent-level skill sync panel as the short-term attachment UI
+1. move skills out of agent configuration and into a dedicated `Skills` tab
 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:
@@ -414,5 +723,6 @@ The next product step should be:
    - actual
    - external
    - unmanaged
+5. keep agent-to-skill associations shortname-based in `AGENTS.md`
 
 That gives Paperclip one coherent skill story instead of forcing package management, adapter sync, and agent configuration into the same screen.