* fix(update): keep an agent's source when updating it After the first `update agents`, an agent's recorded source became `/agents/<name>.md` with type `unknown-subdir` and no repo URL, so `check agents` stopped looking upstream and later changes never arrived (#777). The batch path rebuilt the repository source from the clone URL, subdir and branch only, leaving Raw and Type empty, and the metadata written back was built from that empty Raw. The fallback reinstall and the dashboard update kept the agent's full source as Raw while clearing the subdir, so the written source repeated the agent path. AgentRepoSource now rebuilds the repository source once, by cutting the agent path off the recorded source, and all three paths use it, so the source written back is the one install recorded. Agents whose metadata was already rewritten have no repository left in it and need to be installed again. * fix(check): compare each agent at its own branch and report unchecked agents Agent update checks gave wrong answers in several cases next to #777: - Agents from one repository were compared with the first agent's version, so an older agent sharing a repo with a current one never showed its update. - The installed branch was never sent to the remote, so an agent pinned to a non-default branch was compared with the default branch head. - A tracked agent repo records its full commit while the remote hash is abbreviated, so a fresh clone always read as update_available; its checked-out branch was also ignored. - `update agents` printed "All agents are up to date" and exited 0 when agents could not be checked at all: an unreachable remote, unreadable metadata, or a source erased by the #777 bug. Each agent is now compared with its own version at its own branch, and an agent whose source the old bug erased reports an error asking for a reinstall, since its metadata no longer names a repository. Update lists the agents it could not check and exits non-zero, counting them apart from agents that failed to update. The docs describe the error status and the reinstall fix. * fix(update): repair dashboard-doubled agent sources and share the update flow Review of the previous commits found gaps in recovering agents that earlier updates broke, and in how the two update handlers report them: - A dashboard update before the #777 fix appended the agent path to its source a second time. Those agents keep their repo URL, so check offers an update, but discovery then failed on the doubled path. Every copy of the path is now cut, and the update writes the source back correctly. - On the dashboard, an agent whose source the CLI bug erased failed with "invalid source: source cannot be empty". AgentRepoSource now returns the same reinstall error check shows, and both use one detector. - When every tracked agent was such an erased agent, no remote was asked, so the "Checking agents" spinner was never stopped and drew over the error rows. It is now stopped once the check returns. - The global and project handlers repeated the check-and-update flow, and the project copy had already drifted (no dry-run log entry, spinner in --json). Both now run one shared flow. Tests cover the erased agent next to an updatable one in global, --json, --dry-run and project mode, and the doubled and erased sources in AgentRepoSource.
9.6 KiB
sidebar_position
| sidebar_position |
|---|
| 3 |
check
Check for available updates to tracked repositories and installed skills without applying changes.
skillshare check # Check all repos and skills
skillshare check my-skill # Check a single skill
skillshare check a b c # Check multiple skills
skillshare check --group frontend # Check all skills in frontend/
skillshare check x -G backend # Mix names and groups
skillshare check --json # Machine-readable output
skillshare check my-skill --diff # Show what you changed in a skill since install
When to Use
Before Updating
Preview what would change before running update:
skillshare check # See what has updates
skillshare update --all # Apply updates
skillshare sync # Distribute changes
CI/CD Pipeline
Check for stale skills in CI:
result=$(skillshare check --json)
# Parse JSON to detect outdated skills
Exit Status
check exits with code 1 if any checked item has status error (for example, an unreachable remote or a missing local source). Available updates, stale items, and local modifications alone do not cause failure. With --json, stdout still contains the complete results; inspect each item's status and message for details.
What It Does
check inspects your source directory and reports update status for:
- Tracked repositories — Fetches from origin, shows how many commits you're behind
- Installed skills (with metadata) — Compares installed version against the remote HEAD
- Stale skills — Detects skills whose subdirectory was deleted from the upstream repository
- Locally modified skills — Compares the files of a skill installed from a repository with the files recorded at install time, and reports
"status": "modified"when you edited, added, or deleted any of them - Local-path installs — Compares the files at the path you installed from with the files recorded at install time (see Local-Path Installs)
- Local skills — Marks skills without install metadata as "local source" (nothing to compare)
- Skill-level
targetsvalidation — Warns about unknown target names in SKILL.mdtargetsfrontmatter fields
Unlike update, check never modifies any files.
Local-Path Installs
A skill installed from a directory on disk (skillshare install /path/to/skill) records that path and the hash of every file it copied. check re-hashes the files at that path and reports:
- up to date — the files match what was installed
- update available — a file was changed, added, or removed at the source path
- error — the source path no longer exists (
local source not found: <path>)
This is useful for skills that another application ships and updates, such as a skill inside an app bundle:
skillshare install /Applications/Surge.app/Contents/Resources/Skills/surge
# After the app updates:
skillshare check surge # → Update available
skillshare update surge # Re-copies from the path and runs the security audit
skillshare sync
Skills installed before file hashes were recorded keep the "local source" status until they are updated or reinstalled. In project mode, a relative path (such as ./vendor/my-skill) is resolved against the project root.
When the dashboard installs the root of a directory that also contains child skills, it copies only that root's SKILL.md. check then compares only SKILL.md, and update re-copies only SKILL.md.
Example Output
$ skillshare check
! _shared-rules 3 commits behind
! _design-system uncommitted changes
! commit update available · github.com/anthropics/skills
! old-helper stale — no longer in the upstream repository
! Updates available for 1 repo, 1 skill, 2 up to date, 1 local skipped, 1 stale · 3.4s
Next
skillshare update --all pull the updates
skillshare update --all --prune remove stale skills
Check Specific Skills
You can check one or more skills by name instead of scanning everything:
skillshare check my-skill # Single skill
skillshare check skill-a skill-b # Multiple skills
With follow_source_links: true, you can also check a followed Git checkout by its link name, for example skillshare check _dev-skills.
Use --group / -G to check all updatable skills in a group directory:
skillshare check --group frontend # All skills under frontend/
skillshare check -G frontend -G backend # Multiple groups
skillshare check my-skill -G frontend # Mix names and groups
If a positional name matches a group directory (not a repo or skill itself), it is automatically expanded:
skillshare check frontend # Auto-detected as group
Skills without metadata (local-only) are skipped when expanding groups.
Options
| Flag | Description |
|---|---|
--group, -G <name> |
Check all updatable skills in a group (repeatable) |
--project, -p |
Check project-level skills (.skillshare/) |
--global, -g |
Check global skills (~/.config/skillshare) |
--json |
Output as JSON (for scripting/CI) |
--diff |
For the named skills, show each file changed since install as a line diff against the installed version. Needs a name or --group; cannot be combined with --json |
--help, -h |
Show help |
:::tip Auto-detection
If neither --project nor --global is specified, skillshare auto-detects: if .skillshare/config.yaml exists in the current directory, it defaults to project mode; otherwise global mode.
:::
JSON Output
skillshare check --json
{
"tracked_repos": [
{"name": "_team-skills", "status": "up_to_date", "behind": 0, "branch": "main"},
{"name": "_shared-rules", "status": "behind", "behind": 3, "branch": "develop"}
],
"skills": [
{"name": "pdf", "source": "anthropics/skills", "version": "a1b2c3d",
"status": "up_to_date", "installed_at": "2024-06-01T10:00:00Z"},
{"name": "commit", "source": "anthropics/skills", "version": "x9y8z7w",
"status": "update_available", "installed_at": "2024-05-15T08:30:00Z"},
{"name": "old-helper", "source": "anthropics/skills", "version": "d4e5f6g",
"status": "stale", "installed_at": "2024-03-10T09:00:00Z"},
{"name": "my-review", "source": "anthropics/skills", "version": "a1b2c3d",
"status": "modified", "installed_at": "2024-06-01T10:00:00Z",
"message": "local changes since install"},
{"name": "local-skill", "source": "", "version": "",
"status": "local", "installed_at": "2024-04-20T12:00:00Z"}
]
}
Skills with "status": "error" include a message field when the reason is known, for example "message": "local source not found: /path/to/skill".
Status Indicators
| Icon | Meaning |
|---|---|
✓ |
Up to date |
⬇ |
Update available (tracked repo: commits behind; skill: newer version) |
⚠ |
Stale — subdirectory deleted or renamed upstream |
! |
Has uncommitted changes (tracked repo) or local changes since install (skill) |
• |
Local source (no install metadata to compare) |
:::info Stale skills
When a skill's subdirectory was renamed or deleted upstream, check reports it as stale. Use update --prune to clean up stale skills.
:::
:::info Locally modified skills
A skill you edited after installing it is reported as modified, even when upstream has a newer version; its message then ends with update available upstream. update leaves it alone until you run skillshare update <name> --force, which discards your changes and reinstalls it. OS metadata files (.DS_Store, Thumbs.db, desktop.ini) do not count as local changes.
To see the changes first, run skillshare check <name> --diff. It fetches the commit the skill was installed at, so the diff shows only your edits even when upstream has moved on:
! my-skill 2 files changed since install
modified SKILL.md
# My Skill
- Run the tests.
+ Run the tests with -race.
added NOTES.md
+ my notes
:::
:::tip Monorepo awareness
For skills installed from a subdirectory, check only reports "update available" when that specific directory changed — not when unrelated parts of the repo have new commits.
:::
Project Mode
skillshare check -p # Check all project skills
skillshare check -p my-skill # Check specific project skill
skillshare check -p --group frontend # Check project group
skillshare check -p --json # JSON output for project
Agent Support
skillshare check agents scopes the check to agents only, reporting drift and update status for .md files in the agents source directory:
skillshare check agents # Check all agents
skillshare check agents --json # JSON output for agents
skillshare check agents -p # Check project agents
Each agent is compared with the branch it was installed from. An agent whose recorded source was lost by an earlier update agents reports error and asks you to reinstall it; see Troubleshooting.
Without the agents argument, check operates on skills only (default behavior). See Agents for background.