aweskill 0.1.7 → 0.2.1

package/README.md

@@ -3,7 +3,7 @@
   <h1>aweskill: One Skill Store for All Your Coding Agents</h1>
   <p><strong>Local skill orchestration CLI for AI coding agents.</strong></p>
   <p>
-    <a href="https://github.com/mugpeng/aweskill/releases"><img src="https://img.shields.io/badge/version-0.1.7-7C3AED?style=flat-square" alt="Version"></a>
+    <a href="https://github.com/mugpeng/aweskill/releases"><img src="https://img.shields.io/badge/version-0.2.0-7C3AED?style=flat-square" alt="Version"></a>
     <a href="https://github.com/mugpeng/aweskill"><img src="https://img.shields.io/badge/node-%E2%89%A520-0EA5E9?style=flat-square" alt="Node"></a>
     <a href="https://github.com/mugpeng/aweskill/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MPL--2.0-22C55E?style=flat-square" alt="License"></a>
     <a href="./README.zh-CN.md"><img src="https://img.shields.io/badge/README-%E4%B8%AD%E6%96%87-64748B?style=flat-square" alt="Chinese README"></a>
@@ -12,10 +12,14 @@
     <img src="https://img.shields.io/badge/status-beta-c96a3d?style=flat-square" alt="Status">
     <img src="https://img.shields.io/badge/agents-47_supported-0ea5a4?style=flat-square" alt="Supported agents">
     <img src="https://img.shields.io/badge/projection-symlink-1f2328?style=flat-square" alt="Projection mode">
+		<img src="https://img.shields.io/badge/OS-windows%20%26%20macOS-0078D4?style=flat-square" alt="Windows and macOS">
+    <img src="https://img.shields.io/npm/dt/aweskill?style=flat-square" alt="npm downloads">
+    <img src="https://img.shields.io/github/stars/mugpeng/aweskill?style=flat-square" alt="GitHub stars">
     <img src="https://img.shields.io/badge/platform-local%20CLI-334155?style=flat-square" alt="Local CLI">
   </p>
 </div>
 
+
 `aweskill` is a local CLI for managing, bundling, and projecting skills across AI coding agents.
 
 Instead of copying the same skill folders into every tool by hand, `aweskill` keeps a single source of truth in `~/.aweskill/skills/` and projects those skills into agent-specific directories with `symlink` or `copy`, depending on the target agent.
@@ -26,7 +30,7 @@ Instead of copying the same skill folders into every tool by hand, `aweskill` ke
 - **Bundle-based organization** for reusable skill sets
 - **Multi-agent projection** across Codex, Claude Code, Cursor, Gemini CLI, and more
 - **Managed enable/disable model** without a separate global activation file
-- **Backup, restore, dedupe, and recovery** built into the CLI
+- **Backup, restore, dedup, and recovery** built into the CLI
 
 ## Install
 
@@ -42,7 +46,7 @@ aweskill --help
 To pin a specific release:
 
 ```bash
-npm install -g aweskill@0.1.7
+npm install -g aweskill@0.2.0
 ```
 
 Package page: [npmjs.com/package/aweskill](https://www.npmjs.com/package/aweskill)
@@ -68,7 +72,7 @@ aweskill --help
 ```bash
 npm install
 npm pack
-npm install -g ./aweskill-0.1.7.tgz
+npm install -g ./aweskill-0.2.0.tgz
 ```
 
 ## Quick Start
@@ -77,37 +81,52 @@ npm install -g ./aweskill-0.1.7.tgz
 # 1. Initialize the aweskill home
 aweskill store init
 
-# 2. Scan existing agent skill directories
-aweskill skill scan
+# 2. Show where the aweskill store lives
+aweskill store where --verbose
+
+# 3. Scan existing agent skill directories
+aweskill store scan
 
-# 3. Import a skills root or a single skill
-aweskill skill import ~/.agents/skills
-# aweskill skill import /path/to/my-skill --mode cp
+# 4. Import scanned agent skills into the central store
+aweskill store import --scan
 
-# 4. Create a bundle
+# 5. Import a skills root or a single skill
+aweskill store import ~/.agents/skills
+# aweskill store import /path/to/my-skill --link-source
+
+# 6. Create a bundle
 aweskill bundle create frontend
 aweskill bundle add frontend my-skill
 
-# 5. Enable the bundle for one agent
+# 7. Enable the bundle for one agent
 aweskill agent add bundle frontend --global --agent claude-code
 
-# 6. Inspect current projected skills
+# 8. Inspect current projected skills
 aweskill agent list
 ```
 
-## Core Model
+## Windows
+
+`aweskill` now supports Windows as a native platform.
+
+- Requires Node.js 20 or later
+- PowerShell is recommended for the examples below
+- On Windows, agent projections prefer directory junctions and fall back to managed copies when links are unavailable
+- `store backup` and `store restore` no longer require a system `tar` binary
+
+Example:
 
-`aweskill` follows a simple projection model:
+```powershell
+aweskill store init
+aweskill store scan
+aweskill agent add bundle frontend --global --agent codex
+```
 
-1. Skills live in one central repository: `~/.aweskill/skills/<skill-name>/`
-2. Bundles are plain YAML files in `~/.aweskill/bundles/<bundle>.yaml`
-3. `agent add` projects selected skills into each agent's skills directory
+If you run into Windows-specific path or projection issues, please open an issue with your shell, Node version, and target agent.
 
-That projection is the activation model.
+## Core Model
 
-- If a managed symlink exists, the skill is enabled
-- If it does not exist, the skill is disabled
-- There is no separate global activation registry to reconcile
+`aweskill` keeps one central skill store in `~/.aweskill/skills/`, groups reusable skills through bundles, and projects selected skills into each agent's own skill directory. That projected filesystem state is the activation model.
 
 ## What It Supports
 
@@ -121,57 +140,109 @@ Key directories:
 - Duplicate holding area: `~/.aweskill/dup_skills/`
 - Backup archive: `~/.aweskill/backup/`
 - Bundles: `~/.aweskill/bundles/*.yaml`
-- Repo resources: `resources/bundle_templates/` and `resources/skill_archives/`
+- Built-in skills: `skills/aweskill/`, `skills/aweskill-advanced/`, `skills/aweskill-doctor/`
 
 ## Common Workflows
 
 ### Import skills into the central store
 
 ```bash
-aweskill skill import ~/.agents/skills
-aweskill skill import ~/Downloads/pr-review --mode cp
-aweskill skill import --scan
+# Import skills from an existing agent-managed skills directory
+aweskill store import ~/.agents/skills
+
+# Import a standalone skill folder and keep the original directory unchanged
+aweskill store import ~/Downloads/pr-review
+
+# Import a standalone skill folder and replace the source with an aweskill-managed projection
+aweskill store import ~/Downloads/pr-review --link-source
+
+# Import scanned agent skills and relink their source paths by default
+aweskill store import --scan
+
+# Import scanned agent skills but keep the original agent directories unchanged
+aweskill store import --scan --keep-source
 ```
 
 ### Build reusable bundles
 
 ```bash
+# Create a reusable bundle
 aweskill bundle create backend
+
+# Add multiple skills into the bundle
 aweskill bundle add backend api-design,db-schema
+
+# Inspect what the bundle contains
 aweskill bundle show backend
 ```
 
 ### Project skills into agents
 
 ```bash
+# Project one skill into detected global agent directories
 aweskill agent add skill biopython
+
+# Project multiple skills into one specific global agent directory
 aweskill agent add skill biopython,scanpy --global --agent codex
+
+# Project a whole bundle into every detected global agent directory
 aweskill agent add bundle backend --global --agent all
+
+# Turn managed symlinks back into full directories
+aweskill agent recover --global --agent codex
 ```
 
 ### Keep the store clean
 
 ```bash
-aweskill store backup --both
-aweskill agent sync
-aweskill agent recover --global --agent codex
-aweskill doctor dedupe --fix
+# Inspect the central store layout and entry counts
+aweskill store where --verbose
+
+# Create a backup archive of the current store
+aweskill store backup
+
+# Restore a backup archive into the current store
+aweskill store restore ~/Downloads/aweskill-backup.tar.gz
+
+# Inspect agent entries and categories
+aweskill agent list
+
+# Remove suspicious entries from the central store
+aweskill doctor clean
+
+# Move duplicate central-store skills into dup_skills
+aweskill doctor dedup --apply
+
+# Inspect repair actions for one agent
+aweskill doctor sync --global --agent codex
+
+# Repair broken / duplicate / matched agent entries for one agent
+aweskill doctor sync --global --agent codex --apply
+
+# Remove suspicious agent entries only when explicitly requested
+aweskill doctor sync --global --agent codex --apply --remove-suspicious
 ```
 
-By default, `store backup` and `store restore` only operate on `skills/`. Add `--both` to include `bundles/`, and pass an optional archive path to `store backup` if you want to export to a specific location.
+All `doctor` commands default to dry-run. Add `--apply` to make real changes.
 
 ## Command Surface
 
+Core commands: `store init`, `store where`, `store import`, `bundle create`, `agent add`, `doctor clean`
+
+<details>
+<summary>All commands</summary>
+
 | Command | Description |
 | --- | --- |
 | `aweskill store init [--scan] [--verbose]` | Create the `~/.aweskill` layout |
-| `aweskill store backup [archive] [--both]` | Archive the central skill store, optionally to a specific path |
-| `aweskill store restore <archive> [--override] [--both]` | Restore a previous backup |
-| `aweskill skill scan [--verbose]` | Scan supported agent skill directories |
-| `aweskill skill import <path> [--mode cp\|mv] [--override]` | Import a skill or an entire skills root |
-| `aweskill skill import --scan [--mode cp\|mv] [--override]` | Import the current scan results |
-| `aweskill skill list [--verbose]` | List skills in the central store |
-| `aweskill skill remove <skill> [--force]` | Remove one skill from the central store |
+| `aweskill store where [--verbose]` | Show the `~/.aweskill` location and summarize core store directories |
+| `aweskill store backup [archive] [--skills-only]` | Archive the central store; by default includes both skills and bundles |
+| `aweskill store restore <archive-or-dir> [--override] [--skills-only]` | Restore from a backup archive or unpacked backup directory |
+| `aweskill store scan [--global\|--project [dir]] [--agent <agent>] [--verbose]` | Scan supported agent skill directories for a chosen scope and agent set |
+| `aweskill store import <path> [--keep-source\|--link-source] [--override]` | Import a skill or an entire skills root; external paths keep their source by default |
+| `aweskill store import --scan [--global\|--project [dir]] [--agent <agent>] [--keep-source\|--link-source] [--override]` | Import the current scan results for a chosen scope and agent set; scanned agent paths link back to aweskill by default |
+| `aweskill store list [--verbose]` | List skills in the central store |
+| `aweskill store remove <skill> [--force]` | Remove one skill from the central store |
 | `aweskill bundle list [--verbose]` | List central bundles |
 | `aweskill bundle create <name>` | Create a bundle |
 | `aweskill bundle add <bundle> <skill>` | Add one or more skills to a bundle |
@@ -179,84 +250,48 @@ By default, `store backup` and `store restore` only operate on `skills/`. Add `-
 | `aweskill bundle show <name>` | Inspect bundle contents |
 | `aweskill bundle template list [--verbose]` | List built-in bundle templates |
 | `aweskill bundle template import <name>` | Copy a built-in template bundle into the store |
-| `aweskill agent supported` | List supported agent ids and display names |
+| `aweskill agent supported` | List all supported agent ids, mark global install status with `✓` / `x`, and show detected global skills paths |
 | `aweskill agent add bundle\|skill ...` | Project managed skills into agent directories |
 | `aweskill agent remove bundle\|skill ... [--force]` | Remove managed projections |
-| `aweskill agent list [...]` | Inspect linked, duplicate, and new entries |
-| `aweskill agent sync` | Remove stale managed projections |
+| `aweskill agent list [--global\|--project [dir]] [--agent <agent>] [--verbose]` | Read-only dry-run view of `doctor sync`: inspect `linked`, `broken`, `duplicate`, `matched`, `new`, and `suspicious` entries; when `--agent` is omitted, print the detected agent set for that scope before the grouped results |
+| `aweskill doctor sync [--apply] [--remove-suspicious] [--global\|--project [dir]] [--agent <agent>] [--verbose]` | Dry-run by default; add `--apply` to repair broken entries and relink duplicate / matched ones, and `--apply --remove-suspicious` to also remove suspicious ones; when `--agent` is omitted, print the detected agent set for that scope first |
 | `aweskill agent recover` | Convert managed symlinks into full directories |
-| `aweskill doctor dedupe [--fix] [--delete]` | Find and optionally clean duplicate skills |
-
-## Design Choices
+| `aweskill doctor clean [--apply] [--skills-only] [--bundles-only] [--verbose]` | Find suspicious non-store entries, grouped by `skills` and `bundles`, and optionally remove them |
+| `aweskill doctor dedup [--apply] [--delete]` | Find duplicate skills and optionally move or delete them |
 
-### No global activation file
-
-`aweskill` treats the projected filesystem state as the truth. This keeps the model simple and avoids a second layer of activation metadata drifting out of sync.
-
-### Bundles are expansion sets
-
-`agent add bundle <name>` expands the bundle into skill names and projects those skills. There is no separate long-lived "bundle activation" object after projection.
-
-### Managed-only removal
-
-`aweskill` removes only entries it can identify as its own managed symlinks. It does not blindly delete arbitrary skill directories.
+</details>
 
-## Bundle File Format
+## Built-in Skills
 
-Bundles are plain YAML under `~/.aweskill/bundles/<name>.yaml`:
+`aweskill` ships with three meta-skills that teach AI coding agents how to operate the CLI directly. Import them into your central store so agents like Codex, Claude Code, or Cursor can run aweskill commands without manual steps.
 
-```yaml
-name: frontend
-skills:
-  - pr-review
-  - frontend-design
+```bash
+aweskill store import skills/aweskill
+aweskill store import skills/aweskill-advanced
+aweskill store import skills/aweskill-doctor
 ```
 
-## Projection Model
-
-1. **Central source of truth for skill content**: `~/.aweskill/skills/<skill-name>/`.
-2. **`agent add`** creates, for each selected agent and supported scope, a **symlink** to that directory.
-3. **`agent remove`** removes only entries that are **managed by aweskill**.
-4. **`agent sync`** removes managed projections whose central skill path is missing.
-
-There is **no** reconcile pass driven by a global YAML activation list.
-
-Import behavior:
-
-- Default `skill import --scan` and batch `skill import` merge only missing files when the central skill already exists; `--override` overwrites.
-- When the source is a symlink, aweskill copies from the resolved real path and may print a warning.
-- Broken symlinks during batch import are reported; other items continue.
-- `restore` automatically creates a fresh backup of the current `skills/` tree before applying the archive.
-
-Display behavior:
-
-- `skill list` shows totals and a short preview unless `--verbose`.
-- `skill scan` shows per-agent totals by default; `--verbose` lists concrete scanned skills.
-- `agent list` categorizes `linked`, `duplicate`, and `new`; `--update` imports and relinks where needed.
-- `doctor dedupe` treats `name`, `name-2`, and `name-1.2.3` as one duplicate family and only modifies files when `--fix` is passed.
-
-Projection examples:
-
-```bash
-# Global projection for one agent
-aweskill agent add skill biopython --global --agent codex
+| Skill | Scope | When to use |
+| --- | --- | --- |
+| `aweskill` | Operations | Day-to-day: init, scan, import, list, remove, bundle CRUD, basic agent projection |
+| `aweskill-advanced` | Maintenance | Low-frequency: cross-agent projection strategy, bundle templates, recover flows, multi-scope planning |
+| `aweskill-doctor` | Diagnostics | Repair: `doctor clean`, `doctor dedup`, `doctor sync`, interpreting broken/duplicate/suspicious entries |
 
-# Project-scoped projection for one agent
-aweskill agent add skill pr-review --project /path/to/repo --agent cursor
+See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for the skill directory structure and design principles.
 
-# Bundle expansion writes individual managed projections
-aweskill agent add bundle backend --global --agent codex
-aweskill agent remove bundle backend --global --agent codex
+## Contributing
 
-# Convert symlink projections into copied directories
-aweskill agent recover --global --agent codex
-```
+If you want to contribute, see [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md).
 
-## Templates And Archives
+That file now covers:
 
-Reference bundle templates now live in [resources/bundle_templates/K-Dense-AI-scientific-skills.yaml](/Users/peng/Desktop/Project/aweskills/resources/bundle_templates/K-Dense-AI-scientific-skills.yaml). Runtime bundles still live under `~/.aweskill/bundles/`.
+- design tradeoffs
+- bundle file format
+- projection model
+- built-in skill structure and design principles
+- development workflow and testing expectations
 
-`resources/skill_archives/` is reserved for repository-level `tar.gz` backups that you want to keep in-tree and share with other users. `aweskill` does not generate or restore these archives automatically.
+Documentation, tests, and small focused improvements are all welcome.
 
 For a shareable archive collection maintained outside this repository, see [oh-my-skills](https://github.com/mugpeng/oh-my-skills), a separate backup repository for skill bundles and full-snapshot archives.
 
@@ -337,7 +372,7 @@ If you are exploring the broader skills ecosystem, these projects are worth usin
 - open skill ecosystem conventions
 - cross-agent local developer workflow tooling
 
-## Development
+## Development Commands
 
 ```bash
 npm install