Files
skillshare/website/docs/reference/commands/status.md
T
Willie b0d87fba28 feat(sync): make prefixed target naming misconfigurations visible (#503)
* feat(sync): make prefixed target naming misconfigurations visible

Prefixed naming (#497) works, but several of its failure modes only showed up
at sync time or gave advice that cannot be followed:

- A collision that only prefixing creates told the user to "rename one in
  SKILL.md", which a tracked skill cannot do, and never said the prefix caused
  it. The hint now names the prefixing and points at renaming the other skill or
  re-tracking the repo with --name.
- `target add` silently wrote mode: copy when the inherited naming is prefixed.
  The CLI now says so.
- A target that resolves to prefixed outside copy mode was reported only by
  sync. status, doctor and target list (plain and JSON) now flag it, and the
  sync/validation and `--skills=true` errors say how to fix it.
- The dim "duplicate skill names (isolated by ...)" line printed on every sync
  even when nothing was wrong, and before a failing sync. Isolated duplicates
  are not a problem, so it is dropped; the website docs still showed an
  outdated form of this output and are corrected in all locales.

* fix(status): flag prefixed-outside-copy in the TUI list and status --json

Codex review of #503 found two surfaces the new check missed:

- The interactive `target list` (the default on a terminal) never read the
  item's naming error, so a prefixed + merge target looked healthy there. The
  list row now marks the mode with "!" and the detail panel shows the fix.
- `status --json` (global and project) builds its target entries directly, so
  scripts got no signal. Each target now carries a `warning` string, matching
  `target list --json`.

* docs(troubleshooting): sync no longer prints a message for isolated duplicates

The collision troubleshooting tip still said sync shows an info message when
filters isolate duplicate skill names. That line was dropped, so the tip now
says sync prints nothing about them. Codex review of #503 flagged the stale
English page and its four translations.

* fix(config): point managed-project naming errors at the project settings

The "set mode: copy on the target" hint is wrong for a target a global
`projects:` entry expands into: it cannot be edited with `target` or under
`targets:`, and the mode lives in the project's skills settings. The hint now
depends on whether the target belongs to a managed project (Codex review of
#503).

The naming/mode check becomes a TargetConfig method so status, doctor and
target list share it, which also lets the hint see the project root. Along the
way: doctor reuses it, the TUI list renders the mode once, and
reportTargetAdded takes a flag instead of comparing a mode string.

* fix(config): hint the project settings for managed-project naming errors

ProjectNamingError (the config-load check for a global `projects:` entry) still
returned the bare naming error, so a project that inherits prefixed with a
non-copy mode got no fix. It now names the project's skills settings, like the
expanded targets do. The built-in skill's sync reference also mentions that
status, doctor and target list flag the misconfiguration before sync.

Found by the second /code-review pass on #503.

* fix(sync): detect prefix collisions from the colliding paths

reportCollisions decided a collision came from prefixing when its name was not
also a duplicate in the source. A tracked skill that joined two ordinary
skills already sharing the name was therefore sent to the "rename one in
SKILL.md" hint, which a tracked skill cannot follow (Codex review of #503).

A collision on a prefixed target that includes a tracked path now gets the
tracked-skill hint, whatever else shares the name. The wording no longer claims
prefixing renamed the skill, since a name that already starts with the repo
name is unchanged.

* fix(sync): use discovered repo metadata for the tracked-skill hint

The collision hint treated any path segment starting with "_" as a tracked
repo, so an ordinary skill under a folder such as org/_drafts (no .git) was
told it could not be renamed and to re-track a repo that does not exist. It now
uses DiscoveredSkill.IsInRepo, the same signal prefixed naming uses.

The prefixed docs also gain the fix for a target a global `projects:` entry
expands into (projects.<root>.skills.mode: copy), since `target` cannot edit
those. Both from Codex review of #503.

* fix(sync): keep both collision hints when targets disagree

The same name can clash on a prefixed target with a tracked skill and on
another target between ordinary skills only. The prefixed flag was OR-ed across
targets, so the second case lost its rename/filter hint. Track both kinds
separately while grouping, and print each hint that applies (Codex review of
#503).

* fix(sync): keep the rename hint inside a mixed collision group

When a tracked skill and two ordinary skills share a prefixed name, re-tracking
the repo fixes only the tracked one; the ordinary pair still clashes and is
excluded. The group now also shows the rename/filter hint when at least two of
its participants are not tracked (Codex review of #503).

* fix(sync): offer filters in the tracked-skill collision hint

Two tracked skills of the same repo with the same name collide after
prefixing, and neither renaming a tracked skill nor re-tracking the repo
separates them. The hint now also names include/exclude filters, so every
collision on a prefixed target has an actionable remedy (Codex review of #503).

* docs(sync-modes): limit the target list claim to targets under targets

target list builds from the config without project expansion, so it cannot
flag a target a `projects:` entry expands into; status and doctor can. The
prefixed paragraph and the built-in skill reference said all three flag it
(Codex review of #503).
2026-10-10 00:00:23 +08:00

216 lines
7.7 KiB
Markdown

---
sidebar_position: 7
---
# status
Show the current state of skillshare: source, tracked repositories, targets, and versions.
```bash
skillshare status
```
With `follow_source_links: true`, unavailable first-level source links produce a warning naming the link while healthy skills remain listed. With `--json`, these warnings go to stderr and stdout remains valid JSON.
## When to Use
- Check if all targets are in sync after making changes
- See which targets need a `sync` run
- Verify tracked repos are up to date
- Verify the active audit policy (profile, threshold, dedupe mode)
- Check for CLI or skill updates
## Example Output
```
Source
skills ~/.config/skillshare/skills 43 skills
agents ~/.config/skillshare/agents 2 agents
Tracked repositories
✓ _superpowers 15 skills
Targets skills agents
claude ~/.claude/skills ✓ 43 linked ✓ 2
cursor ~/.cursor/skills ✓ 43 linked · 1 local ✓ 2
gemini ~/.gemini/skills ✓ 43 linked —
universal ~/.agents/skills ✓ 43 linked —
all use merge
Extras
rules ~/.claude/rules 2 files · merge
rules ~/.cursor/rules 2 files · merge
commands ~/.claude/commands 1 file · merge
team ~/.codex 1 file · symlink
team ~/.claude 1 file · import
Audit default · blocks critical
Version CLI 0.24.0 · skill 0.21.12
! Skill 0.21.13 is available — run skillshare upgrade --skill && skillshare sync
```
## Sections
### Source
Shows the skills folder and how many skills it holds. When an agents folder exists, it is shown on a second line with its agent count. An active `.skillignore` adds a line with its pattern and ignored-skill counts.
### Tracked Repositories
Lists git repositories installed with `--track`, each with its skill count. `✓` means the repository is clean; `!` adds `uncommitted changes`, or the git error when its status cannot be read.
### Targets
Each target is one row: its name, its skills folder, and how its skills and agents stand. A line under the table names the sync modes in use.
```
Targets skills agents
claude ~/.claude/skills ✓ 8 linked · 2 local ✓ 8
cursor ~/.cursor/skills ! 6/8 copied ! 7/8
copy: cursor · merge: claude
! 2 skills not synced — run skillshare sync
```
**skills column:**
| Shows | Meaning |
|-------|---------|
| `✓ 8 linked` / `✓ 8 copied` | Every expected skill is in place. Merge and copy targets count the skills left after `include`/`exclude` |
| `· 2 local` | Skills of your own in that folder, which sync leaves alone |
| `! 6/8 linked` | Some skills are not synced yet; status ends with how many and the `sync` command. Skills that `sync` skips on purpose (an invalid name under `standard` or `prefixed` naming, or a name collision) are not counted, because running `sync` again cannot add them; `sync` names them |
| `✓ symlinked` | Symlink mode: the whole folder links to the source |
| `! needs sync` | The mode changed; run `sync` to apply it |
| `! has files` / `! not synced yet` | The target has never been synced |
| `✗ links to …` / `✗ broken link` | The folder is a link to somewhere else, or to nothing |
| `skills off` | Skills are turned off for this target |
**agents column:** `✓ 8` is the number of linked agents (up-to-date copies count as linked). `! 7/8` means some are missing; run `skillshare sync agents`. Only the agents this target syncs count: those left after `.agentignore`, the target's agents include/exclude and each agent's `targets` frontmatter. In copy fallback, identical local files that skillshare does not own are kept and counted as `· 1 local`. `—` means the target has no agents folder. The column is left out when there is no agents source.
### Extras
When extras are configured, each extra target gets a row:
```
Extras
rules .cursor/rules 4 files · merge
commands .claude/commands 3 files · merge
```
Each row shows the extra, its target folder, the file count, and the mode files are synced with: on Windows without Developer Mode, a target that links files shows `copy`.
### Audit
One line with the active audit policy (from CLI flags, project config, or global config): the profile (`default`, `strict` or `permissive`) and the lowest severity that blocks an install (`critical` by default). The dedupe mode and the analyzers are named only when they differ from the defaults (`global` and all analyzers).
### Version
Shows the CLI and skill versions. When a newer skill is released, a line says how to update it. (Global mode only.)
## Options
| Flag | Description |
|------|-------------|
| `--json` | Output as JSON (for scripting/CI) |
| `--project, -p` | Use project mode |
| `--global, -g` | Use global mode |
| `--help, -h` | Show help |
## JSON Output
```bash
skillshare status --json
```
```json
{
"source": {
"path": "~/.config/skillshare/skills",
"exists": true,
"skillignore": {
"active": true,
"files": [".skillignore", "_team-skills/.skillignore"],
"patterns": ["test-*", "vendor/"],
"ignored_count": 2,
"ignored_skills": ["test-draft", "vendor/lib"]
}
},
"skill_count": 12,
"tracked_repos": [
{"name": "_team-skills", "skill_count": 5, "dirty": false},
{"name": "_personal-repo", "skill_count": 3, "dirty": true}
],
"targets": [
{
"name": "claude",
"path": "~/.claude/skills",
"mode": "merge",
"status": "merged",
"synced_count": 8,
"include": [],
"exclude": []
}
],
"agents": {
"source": "~/.config/skillshare/agents",
"exists": true,
"count": 8,
"targets": [
{"name": "claude", "path": "~/.claude/agents", "expected": 8, "linked": 8, "drift": false}
]
},
"audit": {
"profile": "DEFAULT",
"threshold": "CRITICAL",
"dedupe": "GLOBAL",
"analyzers": []
},
"version": "0.17.0"
}
```
A target gets a `warning` string only when sync would reject it, for example `prefixed` naming outside copy mode; the text says how to fix it.
A tracked repo whose git status cannot be read has `"status": "unknown"` and `message` holding the error; `dirty` is then false and not meaningful.
The `source.skillignore` field is present only when at least one `.skillignore` or `.skillignore.local` file exists. When absent: `"skillignore": { "active": false }`. The `files` array includes `.skillignore.local` paths when present. In text mode, the `.skillignore` line shows `(.local active)` when any `.skillignore.local` is in effect.
JSON output is supported in both global and project mode.
## Project Mode
In a project directory, status shows the project's source, targets and extras, with paths relative to the project root:
```bash
skillshare status # Auto-detected if .skillshare/ exists
skillshare status -p # Explicit project mode
```
### Example Output
```
Source
skills .skillshare/skills 3 skills
agents .skillshare/agents 4 agents
.skillignore: 3 patterns, 0 skills ignored
Targets skills agents
claude .claude/skills ✓ 3 linked ✓ 4
cursor .cursor/skills ✓ 3 linked ✓ 4
all use merge
Extras
rules .cursor/rules 4 files · merge
commands .claude/commands 3 files · merge
Audit default · blocks critical
```
Project status does not show Tracked Repositories or Version sections (these are global-only features).
## See Also
- [sync](/docs/reference/commands/sync) — Sync skills to targets
- [diff](/docs/reference/commands/diff) — Show detailed differences
- [doctor](/docs/reference/commands/doctor) — Diagnose issues
- [Project Skills](/docs/understand/project-skills) — Project mode concepts