> ## Documentation Index
> Fetch the complete documentation index at: https://docs.decimal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Update, pin or fork a skill

> What happens when a skill's author publishes a new version, the four ways to pin one, and who can see a skill.

You can hold a registry skill in three ways, and each reacts differently when its author publishes a new version. To add one, see [Browse the registry](https://docs.decimal.ai/guides/registry.md#add-a-skill).

| | **Linked** | **Forked** | **Files** |
| - | - | - | - |
| What you have | A pointer to the author's skill | Your own editable copy on DecimalAI | A folder in your project |
| **The author publishes a new version** | Agents following the latest get it on their next run, and record an [automatic version](https://docs.decimal.ai/guides/agent-setup-versions.md#versions). Pinned agents stay. | Nothing changes. A daily check flags it, and you choose whether to merge. | Nothing changes until you run `decimalai skills update`. |
| The author unpublishes | Existing links keep the last public version. New links are refused. | Your copy keeps working. Merging is refused. | Your files stay. |
| Your edits | Not possible | Yours to make | Block updates until you pass `--force`, which backs them up |
| To undo | **Uninstall** on the skill's page | Delete it like any skill you own | `decimalai skills remove <name>` |

"The latest" on a link means the newest version that passed its safety scan. When a project connects to DecimalAI, its file list is copied onto the agent once, pins included, and those skills then behave as linked.

## Take an update

**Linked:** nothing to do.

**Files:** `decimalai skills status --remote` lists what's outdated. `decimalai skills update` moves every `latest` entry and leaves exact pins alone. Restart the agent process afterwards. [Skills on disk](https://docs.decimal.ai/guides/skills-on-disk.md#versions-latest-or-exact) has the details.

**Forked:** the skill's page shows **Upstream update available**, with **Preview Changes** and **Merge Update**. In the SDK:

```python theme={null}
from decimalai import SkillRouter

router = SkillRouter()  # key from decimalai.init() or DECIMAL_API_KEY

router.merge_upstream("pdf", mode="preview")  # both bodies, side by side; writes nothing
router.merge_upstream("pdf", mode="replace")  # a new version on your copy
```

`replace` overwrites your copy's `SKILL.md` body with the author's. Earlier versions stay in its history. Bundled files don't come along: your copy keeps its own.

`merge_upstream` changes your copy on DecimalAI, and `skills update` changes your project's files. If your files come from your copy, merge first, then update.

## Fork a skill

Forking copies a skill and its bundled files into your organization. It takes the [Editor role](https://docs.decimal.ai/guides/teams.md#roles) or an API key with write permission. Forking the same skill twice returns `409`.

* **Keep the original's name:** agents following its latest version move to your copy (`moved_agents`), and agents pinned to a version stay (`pinned_agents_kept`). Deleting the copy moves them back.
* **Give it a new name:** it's a separate skill, and nothing moves (`unmoved_agents`).

Otherwise, a copy reaches only [the agents you add it to](https://docs.decimal.ai/guides/agent-setup-versions.md#which-agents-get-a-new-skill). It [earns its own SkillScore](https://docs.decimal.ai/guides/skillscore.md).

**Fork** on one of your organization's own skills makes a renamed copy in your current team.

## Pin a version

There are four ways.

| Way | How |
| - | - |
| **The dashboard** | On an agent's **Prompt & skills** page, click the skill, choose **Pin v3**, then **Review & apply**. Or set **Version** on the skill page's **Install linked** form. |
| **The SDK** | `router.assign_skill("support-agent", skill_id, pin_version_id=version_id)` for one agent, or `router.use("pdf", mode="pinned", version=version_id)` for a link. |
| **`decimalai skills add pdf@3`** | Not connected, it writes `"pdf" = "3"` to `.decimal/skills.toml`. Connected or with `--to-agent`, it pins on the agent. |
| **`.decimal/skills.lock`** | Records the exact bytes of every installed skill, pinned or not. `decimalai skills install` never moves a version, and with `--frozen` it writes those bytes or fails. |

A `version_id` comes from `router.list_versions(name)` for your own skill, or the `versions` list of `GET /api/v1/registry/skills/{slug}` for a public one.

An agent's own link overrides the workspace link. A pin doesn't overrule safety: DecimalAI stops serving a public skill's pinned version if it fails its scan.

## Who can see a skill

| Level | API value | Who can see it |
| - | - | - |
| **Only me** | `personal` | Its creator, and anyone it's shared with |
| **Team** | `workspace` | Its team's members, and anyone it's shared with |
| **Organization** | `org` | Everyone in your organization |
| **Public** | `public` | Anyone, through the registry |

Org admins can see and edit every skill. A skill's creator and anyone with edit access can edit it too, and so can its team's editors unless it's **Only me**. Skills made in the dashboard start as **Only me**, and skills made through the API or SDK start as **Organization**.

Change the level on the skill's **Settings** tab, or with `PUT /api/v1/skills/{id}` and `visibility`. That takes the creator, the team's admins or an org admin, though team admins can't change an **Only me** skill. Agents it's assigned to keep it either way. **Public** is reached only by [publishing](https://docs.decimal.ai/guides/publish-a-skill.md), and unpublishing makes a skill **Organization**.

To share a Team or Only me skill without changing its level, open **Sharing & access** on its **Settings** tab, choose **+ Share with team or person**, and give **View** or **Edit** access.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.