mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-20 09:50:48 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - A responsibility shows the skills of the agents doing its work. People cannot say which skills a responsibility needs. > - The maintainer chose to file skills under responsibilities like projects, tasks and routines. > - Agents also need to set a skill's catalog details without rewriting its SKILL.md. > - This pull request lets people and agents file, move and remove company skills under a responsibility, and adds `update_skill_details`. > - The benefit is that a responsibility lists the skills it needs, beside the skills its agents already hold. ## Linked Issues or Issue Description Refs #22253, #22261 and #22274; this pull request is stacked on them. **Subsystem affected** Database (`responsibility_links`), shared types and validators, server responsibility service and routes, Dashboard versions, native runner tools, and the responsibility page UI. **Problem or motivation** Skills under a responsibility are only computed from the agents doing its work. A person cannot record that "Hiring needs interviewing", and an agent cannot file a skill when it maps work for a person. **Proposed solution** Add a nullable `skill_id` to `responsibility_links` and allow it as the one target of a link. Show filed and computed skills together. Let the file, unfile, lookup and link routes and tools take skills. Keep filed skills in Dashboard versions so undo covers them. Add a small live tool for a skill's tagline and categories. **Alternatives considered** Keeping skills computed only, and giving the skill to the agent that runs the responsibility, was the other option. It was not chosen. Extending `update_skill` would change its scenario contract, whose mock needs `markdown`, so the details tool is separate. ## What Changed - Review fixes: the default responsibility view's Skills "+" adds an existing skill, removes a filed one, or opens an agent's skills page. A newest Dashboard version without a skill list is upgraded in place, so the first skill filed after it is undone. Undo files again, or removes, only skills the restoring person can see. A read scope without a skill condition sees no filed skill. `update_skill_details` with only `skillId` is a no-op, as its schema allows. - Migration `0499`: add `responsibility_links.skill_id` (FK to `company_skills`, on delete cascade). Widen the single-target check to four targets. Add a unique `(responsibility_id, skill_id)` index and a `skill_id` index. The migration is idempotent and online-compatible (NOT VALID then VALIDATE, and the indexes are built CONCURRENTLY). It is listed in `MIGRATIONS_WITH_TOP_LEVEL_STATEMENTS`. - Shared: `ResponsibilityLink.skillId`; `ResponsibilitySkillSummary.linkId` and `computed`; `skillId` in the link and lookup schemas; `skill` in `RESPONSIBILITY_FILE_ITEM_KINDS`; optional `skillIds` in Dashboard snapshot links. - Server: filing checks the reader's skill visibility (`skillAccessService`). The detail merges filed and computed skills into one card each. Lookup accepts `skillId`. Dashboard capture, restore and summary include filed skills. A version without `skillIds` leaves filed skills as they are when it is restored. - Tools: `file_under_responsibility`, `remove_from_responsibility` and `find_responsibilities_for` accept `kind: "skill"`. `get_responsibility` returns `linkId` and `computed` for each skill. Add `update_skill_details` (tagline and categories). - UI: the responsibility page has "Add existing skill". A filed skill shows "Filed here" and a remove button. Computed skills keep their holders. ## Verification - Server: the `responsibilit*` tests (new: file, find, move and unfile a skill; one card for a skill that is both filed and computed; undo of a filed skill from the Dashboard history), `skill-tools.test.ts` (new `update_skill_details` cases), `responsibility-tools`, `routine-tools`, `routines-routes`, `paperclip-runner-tool-authority`, `runner-api` and `openapi-routes`: 24 files, 2723 tests passed. - UI: responsibility page and component tests (16 files, 158 tests, including a new filed-skill test) pass. `pnpm --filter @paperclipai/ui typecheck` passed. - `@paperclipai/db` `check:migrations` passes and reports the override. The snapshot drift test passes. `tsc` passes for `db`, `shared` and the server layers. - Runner: catalog and semantic-tool tests (317) pass. All generator checks pass. ## Risks - The migration changes a check constraint on `responsibility_links`. The replacement accepts every row that the old check accepted. It is swapped as NOT VALID and then validated. The previous release never sets `skill_id`. - Deleting a company skill removes its links (cascade). - Filed skills follow the reader's skill visibility. A skill the reader may not see is not listed. ## Model Used Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use and code execution. ## 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 - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: Paperclip <noreply@paperclip.ing>
96 lines
5.6 KiB
TypeScript
96 lines
5.6 KiB
TypeScript
import { parseFrontmatterMarkdown, skillFrontmatterSchema } from "@paperclipai/shared";
|
|
import { z } from "zod";
|
|
|
|
/** A complete single-file skill. Identity and permissions come from the run. */
|
|
export const createSkillToolInput = z.object({
|
|
name: z.string().min(1).max(120).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
|
|
slug: z.string().min(1).max(120).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/).optional(),
|
|
description: z.string().trim().min(1).max(2000),
|
|
markdown: z.string().min(1).max(200000),
|
|
idempotencyKey: z.string().min(1).max(240),
|
|
}).strict().superRefine((input, context) => {
|
|
const document = parseFrontmatterMarkdown(input.markdown);
|
|
const metadata = skillFrontmatterSchema.safeParse(document.frontmatter);
|
|
if (!document.hasFrontmatter || !metadata.success || !document.body.trim()
|
|
|| metadata.data.name !== input.name || metadata.data.description !== input.description
|
|
|| (input.slug !== undefined && input.slug !== input.name)) {
|
|
context.addIssue({ code: "custom", path: ["markdown"], message: "Provide a complete SKILL.md with name and description matching the tool inputs, a nonempty body, and slug equal to name when supplied." });
|
|
}
|
|
});
|
|
|
|
/** Replace the complete primary file of an existing skill, never a partial patch. */
|
|
export const updateSkillToolInput = z.object({
|
|
skillId: z.string().guid(),
|
|
markdown: z.string().min(1).max(200000),
|
|
expectedVersionId: z.string().guid(),
|
|
idempotencyKey: z.string().min(1).max(240),
|
|
}).strict().superRefine((input, context) => {
|
|
const document = parseFrontmatterMarkdown(input.markdown);
|
|
const metadata = skillFrontmatterSchema.safeParse(document.frontmatter);
|
|
if (!document.hasFrontmatter || !metadata.success || !document.body.trim()) {
|
|
context.addIssue({ code: "custom", path: ["markdown"], message: "Provide a complete SKILL.md with valid name and description frontmatter and a nonempty body." });
|
|
}
|
|
});
|
|
|
|
export async function callUpdateSkillTool(input: {
|
|
arguments: Record<string, unknown>; apiUrl: string; token: string; companyId: string;
|
|
}, fetcher: typeof fetch = fetch) {
|
|
const { skillId, markdown, expectedVersionId, idempotencyKey } = updateSkillToolInput.parse(input.arguments);
|
|
const response = await fetcher(`${input.apiUrl.replace(/\/+$/, "").replace(/\/api$/, "")}/api/companies/${encodeURIComponent(input.companyId)}/skills/${encodeURIComponent(skillId)}/files`, {
|
|
method: "PATCH",
|
|
headers: { Authorization: `Bearer ${input.token}`, "Content-Type": "application/json" },
|
|
body: JSON.stringify({ path: "SKILL.md", content: markdown, expectedVersionId, idempotencyKey }),
|
|
signal: AbortSignal.timeout(60_000),
|
|
});
|
|
const result = await response.json();
|
|
if (!response.ok) throw new Error(typeof result.error === "string" ? result.error : `Skill update failed (${response.status})`);
|
|
return { skillId: result.skillId, versionId: result.versionId, path: result.path, studioPath: result.studioPath };
|
|
}
|
|
|
|
/** Use the same API and company skill policy as Skill Studio. */
|
|
export async function callCreateSkillTool(input: {
|
|
arguments: Record<string, unknown>; apiUrl: string; token: string; companyId: string;
|
|
}, fetcher: typeof fetch = fetch) {
|
|
const body = createSkillToolInput.parse(input.arguments);
|
|
const response = await fetcher(`${input.apiUrl.replace(/\/+$/, "").replace(/\/api$/, "")}/api/companies/${encodeURIComponent(input.companyId)}/skills`, {
|
|
method: "POST",
|
|
headers: { Authorization: `Bearer ${input.token}`, "Content-Type": "application/json" },
|
|
body: JSON.stringify(body), signal: AbortSignal.timeout(60_000),
|
|
});
|
|
const result = await response.json();
|
|
if (!response.ok) throw new Error(typeof result.error === "string" ? result.error : `Skill creation failed (${response.status})`);
|
|
return { id: result.id, name: result.name, slug: result.slug, description: result.description,
|
|
versionId: result.currentVersionId, studioPath: `/skills/studio/${encodeURIComponent(result.id)}` };
|
|
}
|
|
|
|
/**
|
|
* A company skill's catalog details that live outside SKILL.md. Its name and
|
|
* description are SKILL.md frontmatter, so they change through update_skill.
|
|
* Like the advertised schema, only skillId is required; without a detail the
|
|
* call changes nothing.
|
|
*/
|
|
export const updateSkillDetailsToolInput = z.object({
|
|
skillId: z.string().guid(),
|
|
tagline: z.string().trim().max(120).nullable().optional(),
|
|
categories: z.array(z.string().trim().min(1).max(60)).max(20).optional(),
|
|
}).strict();
|
|
|
|
/** Same API and company skill edit policy as the skill page. */
|
|
export async function callUpdateSkillDetailsTool(input: {
|
|
arguments: Record<string, unknown>; apiUrl: string; token: string; companyId: string;
|
|
}, fetcher: typeof fetch = fetch) {
|
|
const { skillId, ...details } = updateSkillDetailsToolInput.parse(input.arguments);
|
|
if (details.tagline === undefined && details.categories === undefined) {
|
|
return { id: skillId, changed: false, note: "Nothing changed: send tagline, categories or both." };
|
|
}
|
|
const response = await fetcher(`${input.apiUrl.replace(/\/+$/, "").replace(/\/api$/, "")}/api/companies/${encodeURIComponent(input.companyId)}/skills/${encodeURIComponent(skillId)}`, {
|
|
method: "PATCH",
|
|
headers: { Authorization: `Bearer ${input.token}`, "Content-Type": "application/json" },
|
|
body: JSON.stringify(details), signal: AbortSignal.timeout(60_000),
|
|
});
|
|
const result = await response.json();
|
|
if (!response.ok) throw new Error(typeof result.error === "string" ? result.error : `Skill update failed (${response.status})`);
|
|
return { id: result.id, name: result.name, slug: result.slug, tagline: result.tagline ?? null, categories: result.categories ?? [],
|
|
studioPath: `/skills/studio/${encodeURIComponent(result.id)}` };
|
|
}
|