Bring your existing skills

What is scanned

The desktop app scans when you open Skills, or when you go back to the app while Skills is open, if the last scan is more than one minute old. While one Skill is open, the app does not scan. It scans when you go back to the list. The CLI scans when you run artifactbridge skills scan. Skills that ArtifactBridge does not manage show under Skills → Installed → Only on this computer. It reads these user skill folders:

• ~/.claude/skills (Claude Code)
• ~/.agents/skills and ~/.codex/skills (Codex)
• ~/.grok/skills (Grok)
• ~/.config/opencode/skills and ~/.config/opencode/skill (OpenCode)
• ~/.hermes/skills (Hermes), including category folders up to three levels deep
• ~/.openclaw/skills (OpenClaw)

A scan has fixed limits. It stops after 3 seconds. In each folder in the list above, it reads at most 2,000 entries and 500 skill folders. In total, it reads at most 2,000 skill folders. When a scan reaches a limit, the list shows a note for that folder in the list above. It shows the Skills that the scan read. It does not count the folders that the scan did not read.

What stays on this computer

• ArtifactBridge keeps the scan results, the folder names and paths, the file names and sizes, and your Keep decisions in a private local index. The index is in the ArtifactBridge state folder. ArtifactBridge never sends it.
• The prepared text is a private copy in the same state folder. Cancel or leaving the screen removes it.
• Skills on this computer that ArtifactBridge does not manage are never part of the install reports that ArtifactBridge sends for the Skills it installed.
• Inspection shows SKILL.md as inert text. Nothing in it runs. Values that look like secrets are masked.
• ArtifactBridge records no product event for a scan or Keep. After a send or a replacement that you confirmed, it records one anonymous product event that contains only the action and its result code. The event contains no name, path, hash, count, workspace or member.

Add to workspace

Add to workspace does what New skill does in the web app. It adds the text to the workspace as a document, then makes the document a Skill. There is no review step.

1. Open the Skill and choose Add to workspace….
2. Check its Title (lowercase letters, numbers and hyphens, 64 characters at most) and choose a Folder. Below a folder, ArtifactBridge says who can see a Skill filed there: Visible to everyone in this workspace for a workspace folder, or that only people with access to a private folder can see it. A folder whose visibility cannot be confirmed cannot be chosen.
3. When your server supports it, choose the same settings as for a new Skill: Can agents use this? and Can agents make direct changes?. When private documents are on in your workspace, also choose Access: everyone in the workspace, or Only me. The switches start at the folder’s defaults.
4. ArtifactBridge prepares the exact SKILL.md text for these values. If it changes the text, you can open the exact text before you add it.
5. Choose Add to workspace.

If a workspace Skill already has this name, nothing is added and you choose another name. A new name changes only the folder name and the name: or slug: line in what is added. When you choose Only me, the document and the Skill are private to you.

Only SKILL.md is added, at most 1 MiB. Other files in the folder stay on this computer. A value that looks like a secret blocks Add to workspace.

When the Skill is added, each folder of it becomes the installed copy of the new workspace Skill at once, as an install from the workspace makes it, and as in A Skill with the name of a workspace Skill. The desktop app goes back to the list and shows a notice that you can dismiss. The Skill shows in Skills → Installed, not in Only on this computer. When you chose a new name, the folder gets that name, and its name: line shows as a local change. Other people get the Skill only when they install it.

A Skill with the name of a workspace Skill

A local Skill with the same name as one workspace Skill that you can see, or with exactly its text, is always the installed copy of that workspace Skill. As soon as the desktop app compares the list with the workspace, it links the folder to that workspace Skill. No file in the folder changes. ArtifactBridge records the folder as the installed copy, as an install from the workspace does, also for a tool that is not installed on this computer yet. The folder then shows in Skills → Installed, and the list says so.

• If its text is the same as the workspace version, it gets workspace updates.
• If its text is different, it shows as Edited locally, as any installed Skill that you changed does. Review your change there. You can propose it or, when the Skill allows it, update the workspace Skill. You can also keep your copy, or discard your change to get the workspace version. Updates wait until you decide. See Keep local edits.

Files in the folder that the workspace version does not have stay in the folder. They are not counted as changes.

A folder that is not where ArtifactBridge installs the Skill is moved there first, whole and unchanged: a folder with another name gets the Skill’s name, and a category folder or a folder in ~/.codex/skills or ~/.config/opencode/skill moves to that tool’s skills folder. An earlier Keep on this computer does not stop the link. A folder stays in Only on this computer only when an install from the workspace is not possible either: the workspace Skill is deactivated or has no version to install, several workspace Skills have its name, or another folder is already where the Skill is installed. The Skill details say why.

In the CLI, artifactbridge skills link-to-workspace <local-id> --to <workspace-skill> links one folder.

Who can read what you send

When you choose Add to workspace, the document is immediately readable by the people who can see the folder that you chose, or only by you with Only me. When the document becomes a Skill, the same people can see the Skill. Adding a Skill does not install it on other people’s computers.

When you propose a change, the text is immediately readable by the people who have access to the review in your workspace. This happens before anybody accepts it. Proposing does not accept, publish or replace a Skill.

The folder path, the other files and the scan results are never sent.

After you add or propose

The app shows what happened.

Give a reason

The reason step says how many issues the check found. Choose Show more to see the Skill’s text with each finding on its line, as in the web app’s Findings view. Choose a finding to read its explanation and its fix. Show less closes the view. In Why is this OK?, type why the flagged text is acceptable, at most 1,000 characters. Then choose Create skill with reason. The reason is recorded with your name on that version. It is not saved on this computer. If the check still needs a reason, the step stays open and says so.

Choose Discard, press Escape or leave the step to stop. Nothing stays in the workspace, and your local Skill is as it was before.

In the CLI, a needs_reason result keeps the document in the workspace until you give a reason with artifactbridge skills add-to-workspace --document <uuid> --name <slug> --skill-check-reason -, or delete it with artifactbridge skills add-to-workspace --document <uuid> --discard. Discard deletes only a document that you created, that is still at version 1 and that is not a Skill.

A check that finds no issues does not prove that a Skill is safe. Read the text before you add it.

If your server cannot receive local Skills yet, the list says to update ArtifactBridge, and nothing is sent.

When the outcome is unknown

If the connection fails after you send, the outcome is unknown. Unknown does not mean that nothing was sent. ArtifactBridge keeps the original request key. Check status only reads the saved request. Retry same request sends the same reviewed bytes with the same key. The server then answers with the first request and does not make a second one. A request with an unknown outcome stays available under Requests to check even if the local folder is removed. When you are not signed in or cannot reach ArtifactBridge, Check status and Retry same request are not shown; the request and its key are kept, and the actions return when you are connected again.

Use the workspace version instead (CLI)

In the desktop app, discard your change to a linked Skill to get the workspace version. See A Skill with the name of a workspace Skill.

In the CLI, artifactbridge skills use-workspace-version <local-id> --to <workspace-skill> replaces a local folder with the workspace Skill of the same name. It works only for a folder where ArtifactBridge installs that workspace Skill for a detected tool. First it shows what will happen and a digest. Nothing changes yet. Then --confirm <digest> moves the whole folder, unchanged, to the moved-aside folder in the ArtifactBridge state folder, and installs the workspace version. If the folder, the workspace version, the account or the workspace changed after the summary, nothing moves. Moved folders are never deleted automatically. --status only reads the current state. --recover finishes or undoes an interrupted replacement and keeps your files.

A person must act

An agent can scan, list, inspect and prepare a dry run. Linking a folder, proposing a change, replacing with the workspace version and Recover need a person. When an agent tries, the command stops with requires_person and nothing changes.

Add to workspace uses your own sign-in, as New skill in the web app does. ArtifactBridge refuses agent credentials for it. It cannot tell whether a program that uses your own sign-in is you.

Restore a moved folder

Each replacement keeps your folder under skills/moved-aside/ in the ArtifactBridge state folder, for example ~/.artifactbridge/skills/moved-aside/. Each entry has its own folder with your folder and a manifest.json that names where it came from. To use your folder again:

1. Remove the workspace version from that tool in Skills → Installed.
2. Move your folder from its moved-aside entry back to the place that the manifest names.
3. Run artifactbridge skills scan, or open Skills in the desktop app.

Uninstall and purge

artifactbridge uninstall without --purge keeps the state folder, including the local index and the moved-aside folders. artifactbridge uninstall --purge first lists everything it will do. It deletes the local skills index and the private preview copies. Before it removes the state folder, it moves each moved-aside folder to ~/ArtifactBridge skill backups/. Your skill folders are not changed by deleting the index.