skillnet 0.6.0

Manage canonical AI skill stores, derived views, and calibration data for multi-phase-plan.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102

# Option B Migration

`skillnet 0.5.0` removed reconcile source arbitration. `skillnet 0.5.1`
finishes the migration by making `doctor` validate the new canonical/view
layout and by adding a fresh-host clone helper.

## Schema

Removed legacy fields:

- `[global].sources`
- `[global].sync_paths`
- `[global].stale_codex_skill_paths`
- `project_source_rules`
- `extra_sources`

Replacement global schema:

```toml
[global]
views = [
  { label = "claude", path = "/home/alice/.claude/skills", scope = "global" },
  { label = "agents", path = "/home/alice/.agents/skills", scope = "global" },
]
```

Replacement project schema:

```toml
[[projects]]
name = "demo"
path = "/home/alice/Projects/demo"
origin = "git@codeberg.org:alice/demo.git"
canonical_rel = ".skills"
views = [
  { rel = ".claude/skills", label = "claude" },
  { rel = ".agents/skills", label = "agents" },
]
```

`origin` is optional and is used only by `skillnet project clone --all`.
`canonical_rel` defaults to `.skills`; project views default to
`.claude/skills` and `.agents/skills`.

## Layout

- Global canonical store: `<mirror_root>/global/`
- Global views: configured `[global].views[*].path`
- Project canonical store: `<project>/<canonical_rel>/`
- Project committed views: `<project>/<view.rel>/`
- Project mirror aggregator: `<mirror_root>/projects/<project-name>` symlink
  to `<project>/<canonical_rel>/`

Global views use absolute symlinks to canonical skills. Project views use
relative symlinks so they can be committed to project repositories.

## Fresh Host Bootstrap

On a new host:

```sh
git clone git@codeberg.org:caniko/ai-skills.git /path/to/ai-skills
skillnet project clone --all --dry-run
skillnet project clone --all
home-manager switch
skillnet doctor
```

`project clone --all` skips existing project paths, warns for projects without
`origin`, clones missing projects with configured origins, then runs
`skillnet project sync --all` to materialise in-repo views and mirror
aggregator symlinks.

By default, HTTPS origins are refused. Use `--ssh-strict=false` only when an
HTTPS clone is intentional.

## Doctor

`skillnet doctor` now reports:

- missing canonical stores;
- view entries that are not symlinks;
- view symlinks that are broken or point outside the canonical store;
- canonical skills missing from a configured view;
- orphan view entries not matching any canonical skill name;
- missing, non-symlink, broken, or unexpected project aggregator symlinks.

Missing project repository paths are warnings, not errors, because a host may
be partially bootstrapped before all project repositories are cloned.

## Reconcile-Pull And Centralised Config (`0.6.0`)

`0.6.0` partially reverses `0.5.0`'s "no reconcile" stance, but only in a
narrow promotion path. `skillnet sync` can promote a user-visible non-symlink
view entry back into canonical when the view content is newer, but the default
run only reports would-promote work and exits `2`. Mutation requires
`--apply-promote`; `--no-promote` keeps `0.5.x` behaviour; Home Manager
activation never promotes by default.

For the XDG migration, `skillnet config migrate`, and the Home Manager
declarative pattern, see
[Centralised config (0.6.0)](centralised-config.md).