cnife-skill-manager 0.1.0__tar.gz

cnife_skill_manager-0.1.0/.agents/skills/e2e-happy-path/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: e2e-happy-path
+description: End-to-end happy-path test for skill-manager — declares the public fixture, syncs, and asserts the correct path. Run before PR.
+disable-model-invocation: true
+---
+
+# E2E happy-path test for skill-manager
+
+Verify skill-manager's **correct path** end to end: a declared skill is cloned from a real public GitHub repo, linked into `.agents/skills/`, and its `SKILL.md` stays readable. The test object is skill-manager itself.
+
+The split is fixed: a bash **script** runs the deterministic flow (isolate, declare, sync) and emits a **manifest**; you, the agent, do the orchestration, assertions, and human-readable verdict.
+
+## Preconditions
+
+- Run from the **skill-manager repo root** (cwd = repo root). The script path below is relative to it.
+- `skill-manager` is installed and on PATH.
+- GitHub is reachable for anonymous HTTPS clone (the fixture repo is public).
+
+## Steps
+
+### 1. Run setup + sync
+
+Execute the script and capture the full stdout and exit code. It builds an isolated tree, redirects XDG, writes the fixture declaration, and runs `skill-manager sync`. It prints `skill-manager sync` output followed by exactly one `E2E_MANIFEST {...}` line on exit.
+
+```bash
+.agents/skills/e2e-happy-path/scripts/e2e-setup-sync.sh
+```
+
+**Completion criterion**: you hold the script's exit code and full stdout, and the `E2E_MANIFEST {...}` line is present in it.
+
+### 2. Route on exit code
+
+- **Non-zero exit**: an **infra failure** — setup or sync broke. Grep the `E2E_MANIFEST` line for `root` (preserve that tmpdir for triage), read stderr, and go straight to the verdict.
+- **Zero exit**: sync succeeded; continue to assertion.
+
+**Completion criterion**: you have routed to exactly one path — infra failure (verdict) or sync success (assertion).
+
+### 3. Parse the manifest
+
+From the `E2E_MANIFEST {...}` line, parse the JSON and take four paths: `root`, `project_dir`, `xdg_config_home`, `xdg_cache_home`.
+
+```bash
+grep '^E2E_MANIFEST ' <<<"$STDOUT" | sed 's/^E2E_MANIFEST //'
+```
+
+**Completion criterion**: all four paths are non-empty.
+
+### 4. Run the thorough gate
+
+Assert all five points below. Each records pass/fail with evidence. **Run every point to the end even if an earlier one fails** - the gate is exhaustive so nothing is under-reported; one fail makes the whole run fail, but the rest still execute.
+
+Let `REPO=CNife/skill-manager-e2e-fixture` and `CACHE=$xdg_cache_home/skill-manager/repos/$REPO`.
+
+1. **Symlink valid**: `$project_dir/.agents/skills/e2e-fixture` is a symlink whose resolved target equals `$CACHE`.
+2. **SKILL.md readable**: reading `SKILL.md` through that symlink, its first line is `---`.
+3. **Ledger HEAD consistent**: in `$xdg_config_home/skill-manager/config.json`, `sources["CNife/skill-manager-e2e-fixture"].commit` equals `git -C "$CACHE" rev-parse HEAD` (compare the two live values).
+4. **Clone happened**: `$CACHE/.git` exists.
+5. **sync output**: the script stdout excluding the `E2E_MANIFEST` line contains both `ensured CNife/skill-manager-e2e-fixture` and `created e2e-fixture`.
+
+**Completion criterion**: every one of the five points has been asserted and carries a pass/fail plus evidence.
+
+### 5. Verdict
+
+- **All five pass**: verdict is **PASS**; you may delete `$root`.
+- **Any fail**: verdict is **FAIL**; list each failing point with its evidence, and **preserve `$root`** for triage, stating the path in the verdict.
+- **Infra failure** (step 2): verdict is **FAIL (infra)**; summarize stderr and state `$root`, preserving it.
+
+**Completion criterion**: a single unambiguous PASS or FAIL verdict has been emitted, and on any FAIL the `$root` path is stated and the tmpdir preserved.

cnife_skill_manager-0.1.0/.agents/skills/e2e-happy-path/scripts/e2e-setup-sync.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# E2E happy-path setup + sync for skill-manager.
+#
+# Deterministic flow ONLY: build an isolated tree, redirect XDG, write the
+# fixture declaration, and run `skill-manager sync`. NO assertions, NO pass/fail
+# judgement — that is the driving agent's job.
+#
+# Contract with the driving agent (skill-manager issue #8):
+#   - stdout: `skill-manager sync` output flows straight through, followed by
+#     exactly one `E2E_MANIFEST {...}` line emitted on EXIT (success or failure).
+#   - stderr: sync failure diagnostics (`Error: ...`).
+#   - exit code: the process exit code (0 = setup+sync ok, non-zero = infra fail).
+#
+# The manifest carries the isolated paths the agent needs to assert against, plus
+# `root` (the tmpdir) so a failed run can preserve the whole tree for triage.
+set -euo pipefail
+
+E2E_ROOT=""
+PROJECT_DIR=""
+XDG_CONFIG_HOME_VAL=""
+XDG_CACHE_HOME_VAL=""
+_E2E_EMITTED=0
+
+emit_manifest() {
+  if [ "$_E2E_EMITTED" -eq 1 ]; then return; fi
+  _E2E_EMITTED=1
+  printf 'E2E_MANIFEST {"root":"%s","project_dir":"%s","xdg_config_home":"%s","xdg_cache_home":"%s"}\n' \
+    "$E2E_ROOT" "$PROJECT_DIR" "$XDG_CONFIG_HOME_VAL" "$XDG_CACHE_HOME_VAL"
+}
+trap emit_manifest EXIT
+
+# 1. Build the isolated tree: <root>/{project,config,cache}.
+E2E_ROOT="$(mktemp -d -t e2e-happy-path.XXXXXX)"
+PROJECT_DIR="$E2E_ROOT/project"
+XDG_CONFIG_HOME_VAL="$E2E_ROOT/config"
+XDG_CACHE_HOME_VAL="$E2E_ROOT/cache"
+mkdir -p "$PROJECT_DIR" "$XDG_CONFIG_HOME_VAL" "$XDG_CACHE_HOME_VAL"
+
+# 2. Declare the fixture skill. Full project-config shape is required by
+#    config.load_project_config ({"skills":[...]}), not the bare SkillRef shown
+#    in the fixture README.
+cat > "$PROJECT_DIR/.skill-manager.json" <<'EOF'
+{"skills":[{"name":"e2e-fixture","repo":"CNife/skill-manager-e2e-fixture","path":"."}]}
+EOF
+
+# 3. Redirect XDG so sync writes the ledger + clone cache under <root>, never
+#    the real ~/.config/skill-manager or ~/.cache/skill-manager.
+export XDG_CONFIG_HOME="$XDG_CONFIG_HOME_VAL"
+export XDG_CACHE_HOME="$XDG_CACHE_HOME_VAL"
+
+# 4. Run sync with cwd = project dir: sync resolves .skill-manager.json and
+#    .agents/skills/ relative to cwd. stdout passes through for the agent;
+#    a sync failure exits non-zero (set -e) and the trap still emits the manifest.
+cd "$PROJECT_DIR"
+skill-manager sync
+
+# trap EXIT emits the manifest on the success path too.

cnife_skill_manager-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Sync dependencies
+        run: uv sync --locked --group dev
+
+      - name: Ruff check
+        run: uv run ruff check .
+
+      - name: Ruff format
+        run: uv run ruff format --check .
+
+      - name: Pytest
+        run: uv run pytest

cnife_skill_manager-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,83 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Sync dependencies
+        run: uv sync --locked --group dev
+
+      - name: Ruff check
+        run: uv run ruff check .
+
+      - name: Ruff format
+        run: uv run ruff format --check .
+
+      - name: Pytest
+        run: uv run pytest
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Ensure tag commit is on main
+        run: |
+          git fetch origin main
+          TAG_COMMIT="$(git rev-parse "${GITHUB_REF_NAME}^{commit}")"
+          if ! git merge-base --is-ancestor "$TAG_COMMIT" origin/main; then
+            echo "Tag ${GITHUB_REF_NAME} (${TAG_COMMIT}) is not an ancestor of origin/main; refusing to publish."
+            exit 1
+          fi
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.13"
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TAG="${GITHUB_REF_NAME}"
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            echo "Release $TAG already exists; skipping creation."
+            exit 0
+          fi
+          NOTES=$(git tag -l --format='%(contents)' "$TAG")
+          if [ -n "$(printf '%s' "$NOTES" | tr -d '[:space:]')" ]; then
+            gh release create "$TAG" --title "$TAG" --notes "$NOTES"
+          else
+            gh release create "$TAG" --title "$TAG" --generate-notes
+          fi

cnife_skill_manager-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+.pi/
+.agents/skills/*
+!.agents/skills/e2e-happy-path/
+
+# Python / uv
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# hatch-vcs generated
+src/skill_manager/_version.py

cnife_skill_manager-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+        args: ["--fix=lf"]
+      - id: check-json
+      - id: check-toml
+      - id: check-yaml
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: "0.9.22"
+    hooks:
+      - id: uv-lock
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.10
+    hooks:
+      - id: ruff-format
+      - id: ruff-check
+        args: ["--fix"]

cnife_skill_manager-0.1.0/AGENTS.md

@@ -0,0 +1,13 @@
+## Agent skills
+
+### Issue tracker
+
+Issues live as GitHub issues in this repo, via the `gh` CLI. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Five default triage labels: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`. See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context: one `CONTEXT.md` + `docs/adr/` at the repo root. See `docs/agents/domain.md`.

cnife_skill_manager-0.1.0/CONTEXT.md

@@ -0,0 +1,45 @@
+# Skill Manager
+
+按项目声明式启用 coding agent 技能：Skill 只在 Source 中保留一份，项目通过符号链接引用，全局技能保持精简。
+
+## Language
+
+**Skill / 技能**:
+含 `SKILL.md` 的目录，可被遵守 `./.agents/skills/`（及可选 `~/.agents/skills/`）约定的 coding agent 启用。
+_Avoid_: package, installable, 包
+
+**Source / 源仓库**:
+以 `owner/repo` 标识的 GitHub 仓库，克隆进缓存后可提供一个或多个 Skill。
+_Avoid_: registry, remote, 远端, 注册表
+
+**Skill declaration / 技能声明**:
+项目配置中的一条启用记录，由 `name`、`repo`、`path` 组成。
+_Avoid_: skill ref, entry, 安装项
+
+**Project config / 项目配置**:
+`./.skill-manager.json`，声明本项目启用哪些 Skill。
+_Avoid_: manifest, lockfile, 清单
+
+**Global config / 全局配置**:
+XDG 配置文件（默认 `~/.config/skill-manager/config.json`），记录各 Source 及其 HEAD commit。
+_Avoid_: ledger, database, 台账
+
+**Source cache / 源缓存**:
+XDG 缓存目录（默认 `~/.cache/skill-manager/repos/`），存放已克隆的 Source。
+_Avoid_: library, global library, 全局技能库
+
+**Link / 链接**:
+`./.agents/skills/<name>` 下的符号链接，指向源缓存内某个 Skill 目录。
+_Avoid_: install, copy, 安装
+
+**sync / 同步**:
+幂等操作：确保 Source 已克隆、记录 HEAD、为已声明 Skill 创建 Link。
+_Avoid_: restore, apply, 恢复, 应用
+
+**enable / 启用**:
+交互式向项目配置追加一条 Skill declaration，并执行 sync。
+_Avoid_: add, install, 添加, 安装
+
+**disable / 禁用**:
+交互式从项目配置移除一条 Skill declaration，并清理对应 Link。
+_Avoid_: remove, uninstall, 删除, 卸载

cnife_skill_manager-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CNife
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cnife_skill_manager-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: cnife-skill-manager
+Version: 0.1.0
+Summary: Project-scoped declarative skill manager for agent skills
+Project-URL: Homepage, https://github.com/CNife/skill-manager
+Project-URL: Repository, https://github.com/CNife/skill-manager
+Project-URL: Issues, https://github.com/CNife/skill-manager/issues
+Author-email: CNife <CNife@vip.qq.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,cli,skills,xdg
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# Skill Manager
+
+Project-scoped declarative skill manager for coding agents that load skills from `./.agents/skills/` (and optionally `~/.agents/skills/`).
+
+**One source, many projects, slim globals.** Each skill lives once in a cached Source. Projects get symlinks (Links), not copies. Keep agent-global skills minimal; declare per project what you actually need.
+
+Compatible with any agent that discovers skill directories containing `SKILL.md` under those paths ([pi](https://github.com/earendil-works/pi-coding-agent) is one example).
+
+Today skill-manager only writes project Links under `./.agents/skills/`. Managing `~/.agents/skills/` is on the [roadmap](#roadmap).
+
+## Features
+
+- **Declare and sync project skills** — write `.skill-manager.json`, run `skill-manager sync`
+- **Inspect source and link status** — `skill-manager list` (`linked` / `external` / `broken` / `unlinked`)
+- **Enable / disable interactively** — `skill-manager enable` / `disable`
+- **Manage source cache** — `skill-manager source list|add|remove|update`
+
+## Install
+
+```bash
+uv tool install cnife-skill-manager
+# or: pipx install cnife-skill-manager
+
+# from source (dev):
+uv tool install .
+# or run in-place:
+uv run skill-manager
+```
+
+## Configure
+
+Create `./.skill-manager.json` in your project:
+
+```json
+{
+  "skills": [
+    {"name": "read", "repo": "tw93/Waza", "path": "skills/read"},
+    {"name": "kami", "repo": "tw93/Kami", "path": "."}
+  ]
+}
+```
+
+- `name`: symlink name under `./.agents/skills/` (single path component; duplicates error)
+- `repo`: GitHub `owner/repo` (both parts must be safe slug components)
+- `path`: skill directory inside the repo (`.` for repo-root skills; must contain `SKILL.md`; path traversal is rejected)
+
+## Usage
+
+```bash
+skill-manager sync      # clone/fetch sources, link declared skills
+skill-manager list      # show sources and skill status
+skill-manager enable    # interactively add a skill from the cache, then sync
+skill-manager disable   # interactively remove a skill and its link
+```
+
+### Source repository management
+
+```bash
+skill-manager source list              # list cached repos and HEAD status
+skill-manager source add <owner/repo>  # add and clone a new source
+skill-manager source remove <repo>     # remove source (cache + config)
+skill-manager source update [repo]     # update one or all sources
+```
+
+`sync` is idempotent and never overwrites an existing non-tool symlink (it skips with a notice). Sources are derived from the declared skills' `repo` fields.
+
+## Paths (XDG)
+
+| What | Path |
+|------|------|
+| Global config | `$XDG_CONFIG_HOME/skill-manager/config.json` (default `~/.config/skill-manager/config.json`) |
+| Source cache | `$XDG_CACHE_HOME/skill-manager/repos/` (default `~/.cache/skill-manager/repos/`) |
+| Project skills | `./.agents/skills/` |
+
+## Roadmap
+
+- [ ] **Global skills** — manage Links under `~/.agents/skills/` (same model as project Links)
+- [ ] **Non-interactive enable/disable** — CLI flags for scripts and CI
+- [ ] **Broader sources** — arbitrary Git URLs; local git repos or folders as Sources
+- [ ] **Source inspect** — list skill paths in a Source before enabling
+- [ ] **Hidden-dir scan policy** — skip skills under hidden directories by default; `--all` to include them
+- [ ] **Pinned versions** — pin a Source to a commit or tag in the project declaration

cnife_skill_manager-0.1.0/README.md

@@ -0,0 +1,82 @@
+# Skill Manager
+
+Project-scoped declarative skill manager for coding agents that load skills from `./.agents/skills/` (and optionally `~/.agents/skills/`).
+
+**One source, many projects, slim globals.** Each skill lives once in a cached Source. Projects get symlinks (Links), not copies. Keep agent-global skills minimal; declare per project what you actually need.
+
+Compatible with any agent that discovers skill directories containing `SKILL.md` under those paths ([pi](https://github.com/earendil-works/pi-coding-agent) is one example).
+
+Today skill-manager only writes project Links under `./.agents/skills/`. Managing `~/.agents/skills/` is on the [roadmap](#roadmap).
+
+## Features
+
+- **Declare and sync project skills** — write `.skill-manager.json`, run `skill-manager sync`
+- **Inspect source and link status** — `skill-manager list` (`linked` / `external` / `broken` / `unlinked`)
+- **Enable / disable interactively** — `skill-manager enable` / `disable`
+- **Manage source cache** — `skill-manager source list|add|remove|update`
+
+## Install
+
+```bash
+uv tool install cnife-skill-manager
+# or: pipx install cnife-skill-manager
+
+# from source (dev):
+uv tool install .
+# or run in-place:
+uv run skill-manager
+```
+
+## Configure
+
+Create `./.skill-manager.json` in your project:
+
+```json
+{
+  "skills": [
+    {"name": "read", "repo": "tw93/Waza", "path": "skills/read"},
+    {"name": "kami", "repo": "tw93/Kami", "path": "."}
+  ]
+}
+```
+
+- `name`: symlink name under `./.agents/skills/` (single path component; duplicates error)
+- `repo`: GitHub `owner/repo` (both parts must be safe slug components)
+- `path`: skill directory inside the repo (`.` for repo-root skills; must contain `SKILL.md`; path traversal is rejected)
+
+## Usage
+
+```bash
+skill-manager sync      # clone/fetch sources, link declared skills
+skill-manager list      # show sources and skill status
+skill-manager enable    # interactively add a skill from the cache, then sync
+skill-manager disable   # interactively remove a skill and its link
+```
+
+### Source repository management
+
+```bash
+skill-manager source list              # list cached repos and HEAD status
+skill-manager source add <owner/repo>  # add and clone a new source
+skill-manager source remove <repo>     # remove source (cache + config)
+skill-manager source update [repo]     # update one or all sources
+```
+
+`sync` is idempotent and never overwrites an existing non-tool symlink (it skips with a notice). Sources are derived from the declared skills' `repo` fields.
+
+## Paths (XDG)
+
+| What | Path |
+|------|------|
+| Global config | `$XDG_CONFIG_HOME/skill-manager/config.json` (default `~/.config/skill-manager/config.json`) |
+| Source cache | `$XDG_CACHE_HOME/skill-manager/repos/` (default `~/.cache/skill-manager/repos/`) |
+| Project skills | `./.agents/skills/` |
+
+## Roadmap
+
+- [ ] **Global skills** — manage Links under `~/.agents/skills/` (same model as project Links)
+- [ ] **Non-interactive enable/disable** — CLI flags for scripts and CI
+- [ ] **Broader sources** — arbitrary Git URLs; local git repos or folders as Sources
+- [ ] **Source inspect** — list skill paths in a Source before enabling
+- [ ] **Hidden-dir scan policy** — skip skills under hidden directories by default; `--all` to include them
+- [ ] **Pinned versions** — pin a Source to a commit or tag in the project declaration

cnife_skill_manager-0.1.0/docs/adr/0001-symlink-not-copy.md

@@ -0,0 +1,3 @@
+# 用符号链接暴露 Skill，不拷贝
+
+pi 从项目的 `./.agents/skills/` 发现技能。skill-manager 在该目录创建指向源缓存内 Skill 目录的符号链接，而不是把文件拷贝进项目。这样 Skill 内容始终以 Source 的 HEAD 为准，项目侧无分叉副本；换用拷贝会在每次更新后留下过期副本，且与「全局做小、按项目启用」的意图相悖。

cnife_skill_manager-0.1.0/docs/adr/0002-sources-derived-from-declarations.md

@@ -0,0 +1,3 @@
+# Source 从技能声明派生
+
+项目配置只声明 Skill（`name` + `repo` + `path`），不维护显式的 sources 列表。`sync` 从声明的 `repo` 字段去重派生需要的 Source。保持 DRY，避免「仓库已声明但无技能」与「技能已声明但仓库未注册」两套状态。独立的 `source add/remove/update` 管理全局缓存层，与项目声明正交：预克隆可以，但项目侧仍以声明为准派生。

cnife_skill_manager-0.1.0/docs/adr/0003-explicit-skill-name.md

@@ -0,0 +1,3 @@
+# Skill 用显式 name 字段命名链接
+
+曾考虑从 `path` 末段（或仓库名）派生链接名，但对仓库根目录技能（`path: "."`）会歧义，且同名技能跨仓库时无法消解。因此每条技能声明带显式 `name`，作为 `./.agents/skills/<name>` 的链接名；`name` 必须是单个路径分量，配置内重名直接报错。身份仍是 `name + repo + path`，`name` 只负责磁盘句柄，不替代 `repo + path` 的定位。

cnife_skill_manager-0.1.0/docs/adr/0004-sync-add-only.md

@@ -0,0 +1,3 @@
+# sync 只增不删
+
+`sync` 确保声明的 Source 与 Link 存在，但不删除未再声明的链接，也不覆盖已存在的外部符号链接或非链接条目（跳过并提示）。多数同步工具会双向对账；这里选择保守安全：避免误删用户手建链接，也不在未标记「本工具创建」的前提下做回收。移除技能靠 `disable` 或用户手动清理。

cnife_skill_manager-0.1.0/docs/adr/0005-version-from-git-tags.md

@@ -0,0 +1,3 @@
+# 版本以 git tag + hatch-vcs 为唯一来源
+
+包版本不手写在 `pyproject.toml` 或 `__init__.py`。发布时打 `v*` tag（如 `v0.1.0`），由 hatch-vcs 解析为 PEP 440 版本并写入 `_version.py`。这样 tag、PyPI 版本与运行时 `__version__` / `--version` 同一来源，避免多处漂移；相对静态写版本或 attr 读源码，更适合「打 tag 即发布」的 CI 流程。

cnife_skill_manager-0.1.0/docs/adr/0006-pypi-trusted-publishing.md

@@ -0,0 +1,3 @@
+# 经 GitHub OIDC Trusted Publishing 发 PyPI
+
+发布不使用长期 PyPI API token，而在 push `v*` tag 时由 `.github/workflows/publish.yml` 通过 OIDC 向 PyPI 换短时凭证上传。publisher 绑定 PyPI 项目 `cnife-skill-manager`、仓库 `CNife/skill-manager`、workflow `publish.yml`、Environment `pypi`。相对本地 `uv publish` + token，可审计、无密钥落盘，且与 tag 驱动版本一致；首次需在 PyPI 控制台登记 pending publisher。

cnife_skill_manager-0.1.0/docs/adr/0007-pypi-name-cnife-skill-manager.md

@@ -0,0 +1,3 @@
+# PyPI 分发名用 cnife-skill-manager，与 CLI 名分离
+
+理想包名 `skill-manager` 因与已有 `skill-mgr` / `agent-skill-manager` 等过于相似，被 PyPI 拒绝登记。分发名改为 `cnife-skill-manager`；CLI 入口与 import 仍为 `skill-manager` / `skill_manager`，避免用户命令与代码路径被品牌前缀绑架。安装：`uv tool install cnife-skill-manager`，使用：`skill-manager`。

cnife_skill_manager-0.1.0/docs/agents/domain.md

@@ -0,0 +1,37 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root
+- **`docs/adr/`** — ADRs that touch the area you're about to work in
+
+If any of these are missing, **proceed silently**. `/domain-modeling` (via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions resolve.
+
+## File structure
+
+Single-context:
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-symlink-not-copy.md
+│   ├── 0002-sources-derived-from-declarations.md
+│   ├── 0003-explicit-skill-name.md
+│   └── 0004-sync-add-only.md
+└── src/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (issue title, refactor proposal, hypothesis, test name), use the term as defined in `CONTEXT.md`. Synonyms under `_Avoid_` are out of bounds.
+
+If the concept isn't in the glossary yet — either inventing language the project doesn't use (reconsider), or a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it rather than silently overriding:
+
+> _Contradicts ADR-0004 (sync add-only) — but worth reopening because…_