Dotta
86bc3db693
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Native agents use tools to read reusable company skills. > - The existing native skill tools read only skills assigned to the agent. > - An agent can stop when a task needs another skill that is already in the company library. > - This pull request adds tools to search and read accessible company skills on demand. > - Agents can use the saved instructions without a persistent assignment change. ## Linked Issues or Issue Description **Problem or motivation** An agent cannot use an unassigned company skill through the standard native skill tools. A generic API workaround needs extra discovery and can return the full library. **Proposed solution** Add `search_skills` and `load_skill` to the native tool catalog. Search returns small pages of stored metadata. Load returns text from a saved version and lists its files. Both tools use the current run identity and existing company and project access checks. **Alternatives considered** Assign each skill before a read, or use generic API discovery. Both add work to a read that the company already permits. **Roadmap alignment** This extends the existing skills discovery path. It does not add a store, permission model or installation flow. Related: #15409 adds an assigned-skill loader to a different adapter. ## What Changed - Add bounded company skill search. Search does not synchronize sources or fetch repositories. - Add versioned text reads for SKILL.md and supporting files. Page text and file lists. Reject unsafe paths and binary files. - Recheck access after storage reads. Keep the existing closed Muse, skill-test and completion-review tool scopes. - Add integration tests with isolated PostgreSQL and real local package storage. Update the native tool count assertion and skill documentation. - Limit text files to 16 MiB before body reads. Accept saved file paths up to 4,096 characters plus the repository prefix. Return the response digest only on the first page. - Add optional byte limits to the package readers. Select only the requested legacy file in PostgreSQL. Cast the size comparison to `bigint` so existing callers can omit the limit. - Cache decoded text and its digest for one run. Limit the cache to 64 MiB and 64 files. Check access on each page and clear the cache when the run closes. - Read repository source files and wrapper inputs through verified warm reads or isolated recovery. These reads do not hold the company startup lock. ## Verification - Local verification tested tree `7ba5828387ca0a9c2ee99655818a28de1235a854`, published as commit `c9d04cba601541cca506f5b72aa6f7272a25379f`. The published tree matches that tested checkout. Current head `33fa3d3d4c7988288685ce7c6499d064e0cb9079` (tree `8daaa2f3264d1cd65a9b6d85dbb9d3729ac4a29d`) removes six comment lines from three source files; its executable code is unchanged from the locally tested revision. - Four native skill and authority Vitest suites: 72 passed and 7 existing sandbox checks skipped. All 20 skill-library integration tests passed. - Skill-library and package-store suites: 65 passed. This includes the 45 package-store cases and the same 20 integration cases. Ran with umask `022` for executable-file tests. - Server source and test typecheck layers passed in low-memory mode. The affected source cycle also passed a final separate check. - `git diff --check` and `node scripts/check-module-boundaries.mjs` passed. - Red/green evidence: the new default inline-read case reproduced PostgreSQL error `22003`. Two max-size paging cases reproduced extra body reads. Warm and cold repository reads timed out while another connection held the company startup lock. All five cases pass after the fixes. - Both 16 MiB paging cases check that the second page performs no additional body read. They also check that source-access revocation blocks a cached page. Warm and cold lock cases load both the generated wrapper and a supporting file while the startup lock remains held. - The first cold-read test attempt had an incorrect helper import. Corrected the test import, reproduced the lock timeout, then verified the fix. - [CI on the previous revision](https://github.com/paperclipai/paperclip/actions/runs/42319652795) passed typecheck, build and policy. Serialized shard 2 failed in the unchanged test `schedules bounded retries for failed accepted interaction continuation wakes`. The same case passed locally: 1 passed; 416 cases were excluded by the filter. The cause of the earlier CI failure remains unknown. [CI forc9d04cba](https://github.com/paperclipai/paperclip/actions/runs/42323260426) passed: 52 successful jobs and one skipped selector, including typecheck, build, all serialized server shards, native server tests, Runner/Rust, and e2e. This establishes a later pass; the earlier heartbeat failure's cause remains unknown. [CI for current head33fa3d3d](https://github.com/paperclipai/paperclip/actions/runs/42325148224) passed: all 52 applicable workflow jobs succeeded, with one skipped selector. The head has 58 successful check runs and three skipped checks; Snyk also passed. - Earlier failures remain recorded. Preflight cannot build Rust because Cargo is absent. The first catalog assertion expected 51 tools instead of 53. Test startup needed the plugin SDK build. An earlier typecheck hit the 8 GiB memory limit; low-memory checks passed. The previous package test failed under umask `077`; it passed under `022`, and this run's complete package suite passes with `022`. - Greptile reviewed current head `33fa3d3d` at 2026-11-07 01:40 UTC: 5/5 with no outstanding findings. The three older Ponytail threads are resolved after checking the size/cache, long-path, and bigint fixes and regression tests. Ponytail's supplemental refreshed assessment stopped before completing and posted no new findings. Its earlier findings are fixed and all seven review threads are resolved. The completed Greptile assessment covers current head. - No hosted deployment or live provider run was performed. ## Risks - Package reads can recover stored packages through the existing storage layer. Search reads only stored database metadata. - Load is a read. It does not install files into the provider workspace or change runtime bundles. It does not grant tool access or authorize actions in the skill text. - Callers must retain the returned version ID for later pages. A missing version returns an error. - Files above 16 MiB return a size-limit error. The run cache retains at most 64 MiB of decoded text and 64 entries. A cache miss or eviction requires a full verified file read. Each page still checks current access. The SHA-256 response field is null after the first text or file-list page. - No database migration or UI change is required. ## Model Used - OpenAI Codex, GPT-6 family, with reasoning, repository tools and code execution. The exact model ID and context window are not exposed to this agent. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge
6.9 KiB
Skills created by the Runner
Search and load company skills
Native agents can use search_skills and load_skill to read accessible company
library skills even when those skills are not assigned to them. These read-only
tools are available in Auto, Ask and Plan modes without generic API access or a
mounted workspace. The closed Muse, completion-review and skill-test profiles
keep their existing tool scopes.
Call search_skills with a query to match a name, key, slug or description.
An empty query browses the library. Results include IDs, version IDs, source type,
trust level and compatibility. limit is at most 20. Follow nextCursor with the
same query until it is null. Search reads stored metadata; it does not synchronize
sources, install catalog entries or fetch repositories.
Call load_skill with the returned skill ID and versionId. An exact key also
works; a slug must be unique. The default file is SKILL.md. To read a referenced
text file, pass its relative path and the same version ID. The response includes
a SHA-256 digest on the first text page (null on continuation pages), byte size,
and up to 6,000 UTF-16 characters. Retain the first page's digest. Follow nextOffset
in offset; a version ID is required for subsequent pages. The file list contains
up to 50 entries; use nextFileOffset as fileOffset to read more entries. Do not
switch to the latest version partway through a read. Missing or retired versions
return an error instead of silently substituting different content.
Loads use the existing saved package reader, including repository skill wrappers and supporting files. Text files above 16 MiB are rejected before body reads; accepted text is cached for the run with a 64 MiB budget and at most 64 files. Later pages reuse cached text and still check current access. Evicted files are read again. Repository reads use verified warm files or isolated recovery without holding the company startup lock. Supporting paths use the saved package limit of 4,096 characters plus the generated repository prefix. Binary files and unsafe paths are rejected. Access is checked against the current run and the existing company and project source boundaries, including after file I/O. Loaded content does not change persistent assignments, pinned runtime bundles, permissions, connections, or approval gates. Skill mutation policy continues to govern authoring and installation through the existing APIs. Reading instructions does not authorize actions described in them.
Create and update skills
The native Runner exposes create_skill in Auto and skill-test work. An agent
can save a reusable, single-file skill directly in the company's skill library.
The tool is unavailable in Ask and pre-acceptance Plan modes.
The native Runner also exposes update_skill in the same modes. Read the
existing skill and its currentVersionId through the company skill API before
editing. Supply the complete primary file, not a fragment:
{
"skillId": "<existing skill UUID>",
"expectedVersionId": "<current version UUID>",
"markdown": "---\nname: release-review\ndescription: Review release notes.\n---\n\n# Review\nCheck each release note and its tests.\n",
"idempotencyKey": "review-update-1"
}
The tool uses the existing Skill Studio file endpoint and company skills.edit
policy. It returns a skill ID, path, resulting version ID, and Skill Studio
path. Retry a lost response with exactly the same key and inputs; that
returns the original receipt without another version or activity record.
Reusing the key with different inputs, or updating after the version changes,
returns a conflict. After a version conflict, reread the skill and choose a
new key for the revised edit. Policy is checked again even on exact retries.
{
"name": "release-review",
"description": "Review release notes.",
"markdown": "---\nname: release-review\ndescription: Review release notes.\n---\n\n# Review\nCheck each release note against its change.\n",
"idempotencyKey": "release-review-1"
}
The name is lowercase with hyphens. The complete SKILL.md must have matching
name and description frontmatter and a nonempty instruction body. An optional
slug must equal the name. Company, task, agent and run identity come from the
authenticated run; they are not tool inputs.
The tool uses the same company skill policy and storage as Skill Studio. Skills are open by default unless company policy restricts creation. Creating a skill does not assign it to an agent or introduce a new approval step. Once the skill is saved, the task can finish normally if no other work remains.
The result contains the skill ID, name, slug, description, version ID and Studio path. Reuse the same idempotency key and inputs after a lost response. A retry returns the existing skill without another creation event. A key reused with different inputs, or a name that belongs to another skill, returns a conflict. Published files are never replaced as part of a competing creation request. Deleting a managed skill releases its name for a later creation. Deletion uses the same name lock as creation and retains its source files until the database deletion commits. Imported local and project source folders are not removed.
User interface
Successful creation adds a Skill created card to the originating task's feed. The card opens a named skill tab in the task sidebar. Repeated clicks focus that tab. The tab reads the company skill directly, so it is not a second editable copy of the instructions.
Open in Skill Studio opens that same skill for editing. After saving and returning to the task, the sidebar shows the latest saved version. Reloading the task restores the tab. The historical card remains a creation receipt even if the skill is later edited or removed. The sidebar reports missing skills, denied access and retryable load errors explicitly.
Verification
Server regressions cover authenticated creation, company isolation, policy denials and revocation, mode restrictions, initial version/file persistence, idempotency, conflicting retries and concurrent creation. UI tests cover the creation card, saved tabs, frontmatter-free preview and error states.
The companion Runner Eval case create-skill tests provider tool use against
the seeded mock control plane, not production storage or company policy.
The standalone mock uses a generated production frontmatter parser and schema
validator. Regenerate it with
node packages/shared/scripts/generate-runner-skill-frontmatter.ts after changing
the shared frontmatter contract. A shared-package test checks synchronization.
Invalid inputs are covered by deterministic tests: a live model should not be
penalized for declining to send a schema-invalid request. Product E2E's
create-skill-studio case checks real creation, task completion, the feed card,
sidebar, Studio editing and the updated skill after returning to the task.
See the eval guide for the difference between these suites.