Introducing a new way to review your PRs.

Read the announcement

paperclipai / paperclip

The open-source app everyone uses to manage agents at work

View on GitHub

30 documents · Updated Nov 20, 2026

docs / skills-and-knowledge-sources

Skills and knowledge sources

Skills are reusable knowledge packages that agents can discover, inspect, select, and use during work. Paperclip brings together catalog skills, organization-authored skills, project skills, and Git-backed sources while keeping source identity, file contents, versions, and access decisions visible.

Skill library

The organization skill library is the shared boundary between reusable knowledge and agent work. A skill has a stable key and name, a SKILL.md entry point, optional supporting files, source information, trust and compatibility status, sharing scope, and a current version. Agents select skills from this library instead of keeping unrelated copies.

The library also records lineage and use. A skill can point to an original skill when it is forked, show which agents use it, and retain versions for review or later selection. This makes a skill a managed work resource rather than only a Markdown prompt.

The library supports these broad source classes:

Source classPurpose
CatalogOffer Paperclip-provided bundled or optional skills with stable metadata and a pinned origin.
Local or projectBring a skill from a local folder or a project workspace into the organization view. Project imports remain linked to workspace files.
GitHub or skills.shImport a package from a Git repository. skills.sh references resolve to the related GitHub repository while retaining the external source label.
URLRecord knowledge obtained from a remote URL when it is not managed as a Git source.
Organization-authoredCreate or fork a skill in Paperclip and maintain its content in Skill Studio.

The organization work model provides the wider context for this library. See Organization work management, Work products and conversations, Projects, goals, and teams, and Budgets and cost controls for the surrounding work model. See Agent work management for how agents consume selected skills.

References: packages/…/company-skill.ts• L3-9 packages/…/company-skill.ts• L22-55 packages/…/company-skill.ts• L87-105 packages/…/company_skills.ts• L19-63 ui/…/CompanySkills.tsx• L568-750

Skill packages

A skill package is a set of files rooted at one SKILL.md entry point. The entry point gives the agent-facing instructions. Supporting Markdown, reference files, assets, and scripts travel with the package so the instructions can use a known local layout.

Paperclip keeps a file inventory for each package and classifies its contents. The inventory supports file browsing, version snapshots, source comparison, and runtime preparation. Trust is derived from the package shape: Markdown-only packages are the least risky; assets need more care; scripts or executable files need the highest trust.

Package contents are kept as immutable snapshots identified by a content hash. The package store keeps a verified manifest and archive for durable reads, then uses a local cache to serve repeated reads. Identical package content can be reused instead of being stored again.

Catalog packages are searchable before installation. The catalog describes each package, its category, tags, role hints, requirements, files, content hash, and source. The UI separates bundled and optional catalog knowledge from installed skills, then shows compatibility, trust, provenance, and update state before installation.

References: packages/…/company-skill.ts• L11-20 packages/…/company-skill.ts• L526-569 server/…/company-skills.ts• L736-780 server/…/company-skills.ts• L3710-3735 server/…/skill-package-store.ts• L449-533 ui/…/CompanySkills.tsx• L1629-1935

Imported and project knowledge

Paperclip can read a local skill folder or scan a project workspace for known skill locations and a root SKILL.md. An engineer chooses a project, reviews discovered candidates, resolves name conflicts, and imports selected packages. Remote-only workspaces do not qualify for this local scan because the server cannot safely inspect their files.

Project imports stay linked to the project workspace. Skill Studio can edit the source files in place, so those changes affect the workspace rather than creating a separate organization copy. The import path checks that the package remains inside the workspace and rejects symbolic links. It reports candidates as new, already imported, conflicting, or skipped.

An engineer can choose “Make a copy” when the package must become an independent organization-owned skill. The copy keeps source lineage as metadata but changes the editable source to Paperclip, so later edits do not change the project or remote package.

References: server/…/company-skills.ts• L1451-1570 server/…/company-skills.ts• L2394-2470 server/…/company-skills.ts• L4710-4833 server/…/company-skills.ts• L7363-7395 ui/…/SkillStudio.tsx• L1453-1565 ui/…/SkillStudio.test.tsx• L742-762

Git-backed sources

A Git-backed source represents one organization-managed repository and tracking reference. It keeps the repository identity, selected skill paths, excluded folders, connection, last successful commit, revision, and refresh state. A source can therefore update many selected organization skills as one controlled operation.

The source flow resolves a branch or other tracking reference to an immutable commit. It scans the repository, finds SKILL.md entry points, inspects candidate packages, and lets the user select what to install. Some sources represent separate skill packages; a project-bound source can instead keep the repository as one package so its shared files remain available together.

This diagram shows the source lifecycle from discovery to agent use.

flowchart LR
    A[Repository and tracking ref] --> B[Authorize caller]
    B --> C[Resolve immutable commit]
    C --> D[Scan package entry points]
    D --> E[Inspect files and references]
    E --> F[Select packages or repository]
    F --> G[Create or refresh organization skills]
    G --> H[Store source provenance and version]
    H --> I[Select skill for agent]
    I --> J[Materialize on agent run]

The source can be refreshed, re-selected, configured, or disconnected. A refresh checks the repository and creates a new skill version only when the selected package changed. If a refresh fails or a selected package disappears, the prior installed content remains available and the source records the state for review. Disconnecting stops future tracking; the user can either delete the linked skills or keep editable copies before removing the source.

References: server/…/skill-sources.ts• L37-119 server/…/skill-sources.ts• L121-228 server/…/skill-sources.ts• L263-355 server/…/skill-sources.ts• L362-460 server/…/skill-sources.ts• L463-507

Provenance and snapshots

Provenance explains where a skill came from and which source state produced the installed content. Paperclip stores a source type, locator, reference, package path, and source metadata. Git-backed skills also retain the commit and selected repository path that supplied the package. The UI uses this information to show source identity, sync state, and the link back to source management.

A snapshot is the fixed package state used for inspection, import, preview, or a version. Git scans read from the resolved commit rather than from a moving branch. Skill versions keep the package files and revision number, so an agent test or release can refer to the exact knowledge that was used instead of the current mutable source. The package store verifies the snapshot manifest and archive before it serves content, and it can rebuild a package from an authorized exact-commit recipe when durable bytes need recovery.

The package content hash gives refreshes a stable comparison point. A changed package advances the current version. An unchanged package remains unchanged even when the source refreshes. Forks preserve a visible relationship to the original, but they give the new skill its own organization identity and editing path.

Skill Studio runs also use snapshots. A saved input is captured when a run starts, and a re-run uses the viewed run’s skill version, input, and agent choices. This keeps later edits from changing the meaning of an earlier result.

References: server/…/company-skills.ts• L3750-3859 server/…/skill-sources.ts• L127-227 server/…/skill-package-store.ts• L204-347 server/…/skill-package-store.ts• L546-577 server/…/company-skills.ts• L7363-7395 ui/…/SkillStudio.tsx• L2304-2347 ui/…/SkillStudio.tsx• L3121-3137 ui/…/SkillStudio.tsx• L3185-3206

Inspection boundaries

Inspection gives an engineer enough information to decide whether a package is safe and complete before import. It lists files, sizes, encodings, executable flags, declared requirements, warnings, and links that are missing or leave the package. It does not claim to find every runtime dependency.

Inspection does not run package scripts or install dependencies. External packages with executable scripts are blocked from import. Local and Git scans reject unsafe links and enforce package boundaries, while previews read the requested fixed source state. These boundaries keep discovery focused on package content instead of turning a source scan into code execution.

The client can view text or package metadata before selection. Binary assets remain identified as binary content rather than being rendered as text.

References: server/…/company-skills.ts• L2486-2542 server/…/company-skills.ts• L2709-2728 server/…/company-skills.ts• L776-780 ui/…/SkillStudio.tsx• L1616-1639

Access boundaries

Skill access has two linked boundaries: organization membership and skill policy. Every organization skill operation first checks that the actor belongs to the organization. Mutation actions then evaluate organization policy against the actor and the skill source or skill identity. Policies can match agents, roles, skill keys, source types, and normalized source locators.

Git reads use the caller’s authorized GitHub connection or the credentials available to the active agent run. Seeing that a connection exists is not enough to use it. A refresh or preview must still authorize the caller, and an agent cannot use a saved connection from another run when its own run has no matching authority.

Policy administration is separate from ordinary skill use. Organization administrators can replace or reset the policy with revision checks. When an explicit rule or platform boundary denies a mutation, the UI shows an actionable denial rather than treating it as a temporary scan error. See Runtime and tool governance for the wider execution and tool trust model.

References: server/…/company-skills.ts• L168-250 server/…/company-skill-policy.ts• L45-87 server/…/company-skill-policy.ts• L155-186 server/…/skill-source-github-access.ts• L17-40 server/…/skill-source-github-access.ts• L53-87 server/…/company-skill-policy.ts• L43-59 ui/…/SkillPolicySurfaces.tsx• L1-9 ui/…/SkillStudio.tsx• L189-212

Skills UI flows

The Skills area separates installed knowledge, discovery, and authored knowledge. Installed skills are available to the organization. Discover skills combines catalog and other available sources. My Skills focuses on skills that the current actor can open, edit, and test in Skill Studio.

The main browse flows are:

  1. Installed knowledge: Search the organization library, filter by source, browse folders, refresh a selected project folder, and open a skill for inspection.
  2. Discovery: Search and sort skills from available sources. Catalog entries show whether they are bundled or optional. A detail view exposes files, trust, compatibility, requirements, content hash, and the install or update action.
  3. Catalog installation: Inspect a catalog package, review its provenance and file inventory, then install it in the organization. Installation and agent enablement are separate states. A fresh install can enable the skill for eligible agents in the same confirmation step.
  4. Project import: Scan project workspaces, browse candidates, resolve conflicts, and import references to selected workspace packages.
  5. Source management: Open Sources to connect a repository, watch scan progress, select packages, inspect files and warnings, and save or refresh the source selection.
  6. Skill management: Open a skill to inspect files, provenance, versions, users, comments, update state, and lineage. Edit an organization-owned skill or make a copy of a read-only source-backed skill before changing it independently.

The current streamlined UI uses Installed and Discover as the primary views. Older catalog, bundled, category, and folder URLs are redirected into Discover or the installed view so existing links remain useful. The UI also makes “installed” distinct from “enabled for agents,” which prevents a library copy from being mistaken for active agent use.

References: ui/…/CompanySkills.tsx• L568-750 ui/…/CompanySkills.tsx• L1029-1388 ui/…/CompanySkills.tsx• L3937-4161 ui/…/CompanySkills.tsx• L4325-4386 ui/…/CompanySkills.test.tsx• L383-730 ui/…/CompanySkills.production.tsx• L559-750

Skill Studio

Skill Studio is the authoring and verification workspace for reusable knowledge. It lets an engineer create or fork a skill, edit its package files, save versioned changes, prepare test inputs, run the skill with an agent, and inspect the resulting run.

The workspace supports these activities:

ActivityPurpose
Create or forkStart an organization-owned skill from a blank draft or from an existing skill. Creation can carry the folder where the engineer started, and a fork keeps visible lineage to its source.
File editingBrowse the package tree, preview Markdown, edit supported files, and add or remove package files. Read-only sources show “Make a copy” instead of an edit path.
Version historyCompare saved package states and restore an older state by creating a new head version. History is not rewritten, and concurrent changes produce a conflict that preserves the local draft.
Test inputsKeep named reusable inputs in folders or use an unsaved ad-hoc input for a single run. Saved inputs are snapshotted when a run starts.
Test runsChoose an eligible agent, provide input, optionally apply a run template, and inspect status, output, documents, attachments, and interactions. A run can be cancelled or re-run from its saved snapshots.

The Studio landing view helps an engineer return to work through recently visited and recently updated skills. It keeps human editor identity visible without presenting an agent as a human editor. On large screens, Studio presents the skill, input, and test-run areas together. On small screens, the same areas appear as tabs.

This diagram shows the authoring path from a reusable package to a checked agent run.

flowchart LR
    A[Create or fork skill] --> B[Edit package files]
    B --> C[Save version]
    C --> D[Choose saved or ad-hoc input]
    D --> E[Choose agent and run template]
    E --> F[Run from skill and input snapshots]
    F --> G[Inspect output and run state]

References: ui/…/SkillStudio.tsx• L277-394 ui/…/SkillStudio.tsx• L396-715 ui/…/SkillStudio.tsx• L769-918 ui/…/SkillStudio.tsx• L947-1132 ui/…/SkillStudio.tsx• L1284-1664 ui/…/SkillStudio.tsx• L1953-2347 ui/…/SkillStudio.tsx• L2359-2657 ui/…/SkillStudio.tsx• L3084-3338 ui/…/SkillStudio.tsx• L3484-3619 ui/…/SkillStudio.test.tsx• L324-410 ui/…/SkillStudio.test.tsx• L477-762

Agent knowledge use

An agent’s skill selection is a desired set of organization skill keys. The selection can include a version pin when the adapter supports it. Paperclip applies the desired set according to the adapter’s mode: some adapters keep materialized skills in a workspace, some apply them for the next run, and unsupported adapters only track the selection.

The company library and the agent runtime have different responsibilities. The library owns source, content, versions, and policy. Agent configuration chooses which reusable knowledge is relevant. Runtime preparation then builds a read-only package view from the selected skill content, while unmanaged skills detected by an adapter remain outside the company library’s edit controls.

For the full relationship between agent configuration and execution, see Agent work management. For work produced during agent execution, see Work products and conversations. For plugin-provided reusable skills, see Extensibility platform.

References: ui/…/CompanySkills.tsx• L2179-2229 ui/…/CompanySkills.tsx• L3153-3208 server/…/runtime-skill-selections.ts• L1-7 server/…/runtime-skill-cache.ts• L28-51 server/…/runtime-skill-cache.ts• L173-213 server/…/plugin-managed-skills.ts• L156-221

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep source type names, source badges, policy source categories, provenance labels, and Installed, Discover, and Studio wording aligned across shared validation, server policy evaluation, and the Skills UI.
  • When source selection, package mode, or revision rules change, update scan, refresh, disconnect, copy, and preview contracts together with stale-selection handling in the Sources UI.
  • When package inventory, file encoding, or snapshot hashing changes, check version creation, preview results, source comparison, catalog install, and runtime materialization as one contract.
  • When package storage, archive receipts, or recovery rules change, check durable verification, local cache recovery, exact-commit restoration, deduplication, and maintenance cleanup together.
  • When project scan paths or workspace rules change, update both server discovery and the project import flow’s folder guidance, source-link behavior, and conflict states.
  • When GitHub connection rules change, verify that repository listing, scan, preview, refresh, and agent-run reads all use the same caller-specific authorization boundary.
  • When skill policy actions or resource selectors change, update policy normalization, mutation routes, administration routes, and denial surfaces together.
  • When the library UI changes, preserve the distinction between installation, agent enablement, source ownership, editable copies, and read-only status.
  • When Studio version, conflict, or test-run snapshot rules change, update save, restore, re-run, and release-pin behavior together.

Important failure modes

TriggerConsequenceGuard
A GitHub branch, repository, or connection cannot be readDiscovery or refresh stops. Existing installed skills remain available when a refresh fails.Reauthorize each read, resolve a fixed commit, and retain the last successful source state.
A selected package has an invalid entry point, unsupported file, broken package boundary, or unsafe linkThe candidate is marked invalid or warned and cannot be safely imported as selected.Inspect package files and references before import. Do not follow unsafe links.
An external package contains scripts or executablesImport is rejected instead of placing executable content in the external organization skill library.Derive trust from the file inventory and block executable external packages.
A stored package manifest or archive is missing, corrupt, or belongs to another storage providerThe package cannot be served from durable storage. An eligible Git-backed package may enter recovery with a retry delay.Verify manifest and archive checksums, keep the content hash aligned, and use the authorized exact-commit restore recipe.
A source revision changes while a user saves a selectionThe selection is rejected as stale rather than silently overwriting a newer source state.Require the caller to reload the source before saving.
A source refresh omits installed repository files or exceeds supported package limitsThe refresh stops and keeps the installed repository skills and dependencies.Reduce the repository package or choose a compatible package mode before refreshing.
A source is disconnectedFuture sync stops. Linked skills are either deleted or converted to editable copies according to the user’s choice.Require an explicit disconnect action and preserve provenance on copies.
A caller lacks organization access, GitHub authority, or a skill policy grantThe operation is denied and no source or skill mutation occurs.Enforce organization boundaries, caller-specific Git access, and policy evaluation before mutation.
A user edits a read-only source or bundled skillThe save path is unavailable. The original source remains unchanged.Show read-only state early and offer “Make a copy” for independent edits.
A user runs Studio with no eligible agent, no input, no package files, or unsaved skill editsThe Run action stays disabled until the test has a usable skill and input state.Evaluate the run gate before starting a test and ask the user to save the skill first.
A skill or saved input changes while the user is editing itThe local draft is not silently replaced. The user must reconcile the draft with the latest saved content.Send the expected version and preserve unsaved text after a conflict.
An agent adapter cannot manage Paperclip skillsThe selection is tracked or shown as unavailable, but the adapter’s own skills are not changed.Mark unsupported or detected adapter skills as read-only and direct management to the adapter.

Key files

FileWhy to read it
server/…/company-skills.tsMain organization skill model, local and remote imports, source metadata, versions, trust classification, editable-copy behavior, and runtime-facing content.
server/…/skills-catalog.tsCatalog discovery, pinned catalog file reads, content hash checks, and catalog package metadata.
server/…/skill-sources.tsGit-backed source lifecycle, package selection, refresh, disconnect, editable copies, and source audit events.
server/…/skill-package-store.tsImmutable package snapshots, durable archive storage, verified reads, local cache use, deduplication, and exact-commit recovery.
server/…/github-skill-source.tsRepository scan behavior, package discovery, inspection, warnings, and immutable commit previews.
server/…/skill-source-git-snapshot.tsThe bounded commit snapshot used to read Git-backed package files safely.
server/…/skill-package-inspection.tsPackage file inventory and reference checks that shape inspection warnings.
server/…/company-skill-policy.tsOrganization policy evaluation for skill actions and source boundaries.
server/…/company-skills.tsHTTP surface for catalogs, organization skills, Git sources, imports, previews, versions, and policy-aware mutations.
packages/…/company-skill.tsShared vocabulary for skill sources, trust, compatibility, sharing, versions, catalog records, and project scan results.
packages/…/skill-source.tsShared contract for source discovery, inspection, selection, progress, and refresh results.
ui/…/CompanySkills.tsxInstalled and Discover views, catalog inspection, installation, folders, project scans, provenance, agent attachment, and skill detail.
ui/…/SkillStudio.tsxSkill creation and forking, package editing, recent-skill landing, version history, reusable inputs, test runs, and run inspection.
ui/…/SkillStudio.test.tsxBehavioral coverage for Studio creation, folder context, recent-skill browsing, version conflicts, and read-only copy actions.
ui/…/AgentSkillReleasePicker.tsxThe supported bundled-skill choice between the live default and a pinned release snapshot.
ui/…/SkillsContextualSidebar.tsxTop-level Skills navigation and the product split between installed, discovery, sources, and authored skills.
ui/…/SkillSourceTree.tsxPackage-level source selection and file-level inspection affordances.
ui/…/ImportSkillsFromProjectDialog.tsxProject workspace scan, browse, conflict resolution, and reference import flow.
ui/…/SkillSourceProvenance.tsxSource sync state and the link from a skill back to its managed Git source.
ui/…/AgentSkillsTab.tsxThe bridge from the organization library to per-agent selection, version pins, and adapter limits.