@easbot/skills 0.3.11 → 0.3.12

package/README.en.md

@@ -2,19 +2,34 @@
 
 # @easbot/skills
 
-Skill package management subsystem for the EAS Agent ecosystem. Discovers, installs, removes, searches, updates, syncs and one-shot uses skills (SKILL.md) from GitHub, Well-Known hosts, or local paths.
+Skill management subsystem for the EASBot ecosystem. Handles discovery, installation, removal, search, update, one-shot use (use), and store/cache/index operations for skills (SKILL.md). Also acts as the **Plugin Source Registry** (decision 0044), abstracting well-known, marketplace, and local plugin sources into `PluginSource` for `@easbot/agent` to inject into `PluginDefinition.skills`.
 
-Usable both as a standalone CLI (`easbot skills ...`) and as a library that the `@easbot/agent` host CLI delegates to via Commander.js, so `easbot agent skills ...` and `easbot skills ...` are equivalent.
+Usable both as a standalone CLI (`easbot-skills`) and as a library delegated to by the `@easbot/agent` main CLI via Commander.js, making `easbot skills ...` and `easbot-skills ...` equivalent.
+
+## Version
+
+v0.3.11
+
+## Target Files
+
+The package only operates on **SKILL.md** (and optional local `plugin.json`):
+- Skill name comes from the `name` field in the `SKILL.md` frontmatter
+- Plugin manifest comes from `plugin.json` (if present; otherwise defaulting to `*.md`)
 
 ## Features
 
-- **Type Safety**: full TypeScript types + Zod frontmatter validation
-- **Multi-Source**: GitHub shorthand / HTTPS / SSH / Well-Known / local path
-- **Multi-Agent**: Claude Code, Cursor, AiderDesk, Amp, Antigravity, Zed, Codex, Hermes, Vibe, AutoHand, Eve, ...
-- **Dependency Injection**: `setGlobalAdapter / setInstanceAdapter / setAgentAdapter` lets the host (agent / gateway) inject `IGlobal.Path`, `IInstance.directory`, and SubAgentRunner / LocalAgentRunner — all data lives under one tree
-- **Incremental Sync**: lockfile-based add / remove / update / sync with local SHA-256 hashing
-- **i18n**: built-in zh-CN / en-US translations; user-facing strings go through `t()`, with fallback to the English literal when a key is missing
-- **Telemetry + Audit**: built-in `skills.sh` partner-audit reporting and OpenClaw risk gating
+- **Type Safety**: Full TypeScript types + Zod frontmatter validation + Zod remote-skill payload validation
+- **Multi-Source**: GitHub shorthand (`owner/repo`) / HTTPS / SSH / Well-Known index / local path / GitHub API blob fallback
+- **Multi-Agent**: 72+ agent types (`easbot`, `claude-code`, `cursor`, `codex`, `amp`, `eve`, `gemini-cli`, `github-copilot`, `opencode`, `qwen-code`, `trae`, `trae-cn`, `windsurf`, `zed`, `roo`, `cline`, `iflow-cli`, `kimi-code-cli`, `augment`, `devin`, `goose`, `depto` etc.)
+  - **Universal shared path**: `eve` / `amp` / `gemini-cli` / `github-copilot` / `qwen-code` / `roo` / `windsurf` / `zed` / `claude-code` and 16 universal agents share `.agents/skills` directory
+  - **Non-universal agents**: each maintains independent skill directories
+- **Install Matrix / Post-Install Reconcile**: `AgentInstallMatrix` (agent × skill 2D table, `probeCell` cell-by-cell), post-install cell reconcile (missing → link, excess → remove)
+- **Dependency Injection** (voting 0043): `setGlobalAdapter` / `setInstanceAdapter` / `setAgentAdapter` inject `IGlobal.Path` / `IInstance.directory` so skills uses the host's unified XDG data tree
+- **Incremental Sync**: Lockfile-based `add` / `remove` / `update` / `store` with local SHA-256 hashing (`skill-lock.ts` / `local-lock.ts`)
+- **Store-Centric Ops** (voting 36A): `skills store list / clean / update / remove` manage store dirs + index + cache without touching agent distributions
+- **Local Source Hard Protection**: `store clean --force` / `store remove` refuse to delete cache / user directory for local sources
+- **i18n**: Built-in zh-CN / en-US translations; all user-facing strings go through `t()`, with fallback to English literal when key is missing
+- **Telemetry + Audit**: Built-in `skills.sh` partner-audit reporting, OpenClaw risk scoping, telemetry flush (`flushTelemetry`)
 
 ## Installation
 
@@ -32,41 +47,101 @@ Or as a monorepo workspace dependency:
 }
 ```
 
+## Directory Layout
+
+```
+src/
+├── types.ts                # AgentType, Skill, AgentConfig, ParsedSource, RemoteSkill
+├── agents.ts               # Agent config matrix (72+) + classification functions
+├── skills.ts               # Skill discovery: parseSkillMd, discoverSkills, filterSkills
+├── installer/
+│   ├── installer.ts          # Physical install: installSkillForAgent, installRemoteSkillForAgent, installBlobSkillForAgent
+│   ├── post-install.ts       # Post-install reconcile matrix: planActions, buildMatrix, probeCell
+│   ├── store.ts              # Three-layer store (source→cache→install): ensureCachedSource, acquireSourceClone, cleanCache
+│   └── types.ts              # InstallMode, InstalledSkill etc.
+├── add.ts                  # Skill add pipeline
+├── find.ts                 # Search (skills.sh / fuzzy filter / local store query)
+├── list.ts                 # List installed (project/global/agent filtered)
+├── remove.ts             # Remove skills
+├── update.ts              # Incremental update (by filter, update one or more)
+├── use.ts                  # One-shot use: materializeUseSkill, buildUsePrompt, launchAgentInteractively
+├── doctor.ts              # Health check + dangling symlink cleanup
+├── store-cmd.ts            # Store ops subcommands (list / clean / update / remove)
+├── init-template.ts        # Create a new skill from locale template
+├── sanitize.ts             # Control char sanitization: sanitizeMetadata, stripTerminalEscapes
+├── telemetry.ts            # Telemetry: track, flushTelemetry, fetchAuditData, setVersion
+├── detect-agent.ts        # Detect running AI agent: detectAgent, isRunningInAgent
+├── skill-lock.ts           # Global lockfile (skill-lock.json)
+├── local-lock.ts           # Project lockfile (skills-lock.json) + folder SHA-256
+├── git.ts                  # Repo clone / cleanupTempDir / parseGitHubRepoUrl
+├── blob.ts                 # GitHub API fallback: fetchRepoTree, tryBlobInstall, toSkillSlug
+├── source-parser.ts        # Source normalization: parseSource, parseOwnerRepo, sanitizeSubpath, shRepoPrivate
+├── interfaces.ts          # Dependency injection: setGlobalAdapter / setInstanceAdapter / getGlobal / getXdgData
+├── constants.ts            # AGENTS_DIR / SKILLS_SUBDIR / UNIVERSAL_SKILLS_DIR
+├── frontmatter.ts        # YAML frontmatter parser
+├── format.ts             # ANSI color helpers
+├── providers/
+│   ├── wellknown.ts          # WellKnownProvider: fetch index + scan + load
+│   └── registry.ts          # Provider registry + HostProvider interface
+├── sources/
+│   ├── index.ts              # PluginSource entry: createWellKnownSource / createLocalPluginSource factories
+│   ├── registry.ts             # Registry: registerSource / listSources / findSource / listAllEntries
+│   ├── wellknown.ts          # Wellknown source adapter
+│   ├── local.ts             # Local plugin dir (plugin.json) adapter
+│   └── types.ts              # PluginSource / PluginSourceCategory / PluginSourceEntry interfaces
+├── i18n/                  # Full i18n (zh-CN / en-US)
+├── prompts/               # Search multi-select prompt
+├── utils/                 # Helpers (ansi / format)
+├── cli.ts                  # Standalone CLI entry (easbot-skills)
+├── cli-handler.ts          # CLI handler (for agent reuse)
+└── src/sources/             # PluginSource registry (voting 0044)
+```
+
 ## CLI Usage
 
 ### Standalone CLI
 
 ```bash
 # Add a skill
-easbot skills add houjallen/agent-skills
-easbot skills add https://github.com/houjallen/agent-skills -g
+easbot-skills add houjallen/agent-skills
+easbot-skills add https://github.com/houjallen/agent-skills -g
 
-# Search
-easbot skills find typescript --owner houjallen
+# Search (interactive fzf picker)
+easbot-skills find typescript --owner houjallen
 
-# List installed
-easbot skills list --json
+# List installed (project/global)
+easbot-skills list --json
+easbot-skills ls -g -a claude-code
 
 # Remove
-easbot skills remove my-skill -y
+easbot-skills remove my-skill -y
+easbot-skills rm --agent claude-code my-skill
 
 # Update
-easbot skills update -g
+easbot-skills update -g
+easbot-skills update my-skill --all
 
 # One-shot use (no lockfile mutation)
-easbot skills use houjallen/agent-skills@houjallen
-
-# Sync from node_modules / restore from lockfile
-easbot skills experimental_sync
-easbot skills experimental_install
-
-# Initialize a new skill
-easbot skills init my-skill
+easbot-skills use houjallen/agent-skills@houjallen
+easbot-skills use --skill my-skill --agent claude
+
+# Store-centric ops (store + cache + index)
+easbot-skills store list [keyword]                 # List store skills (name filter)
+easbot-skills store list --json                    # Full index as JSON
+easbot-skills store clean                          # Reset store (delete store dirs + clear index)
+easbot-skills store clean --force                  # Same + clear cache (local source protected)
+easbot-skills store remove <sourceKey>             # Remove source
+easbot-skills store remove <sourceKey> --force     # Extra clear cache
+
+# Health check (check + cleanup dangling symlinks)
+easbot-skills doctor
+easbot-skills doctor -a easbot -t                  # check one agent + auto-cleanup
+easbot-skills dr -g                                # global only
 ```
 
 ### Delegated from a host CLI
 
-`@easbot/agent` reuses every sub-command through `handleSkillsCli(args, deps)`:
+`@easbot/agent`'s `easbot skills ...` reuses all sub-commands via `handleSkillsCli(args, deps)`:
 
 ```typescript
 import { handleSkillsCli, setGlobalAdapter, setInstanceAdapter } from '@easbot/skills';
@@ -74,43 +149,66 @@ import { handleSkillsCli, setGlobalAdapter, setInstanceAdapter } from '@easbot/s
 setGlobalAdapter({ Path: Global.Path });
 setInstanceAdapter({ directory: ctx.config.directory, worktree: Instance.worktree });
 
-await handleSkillsCli(['add', 'houjallen/agent-skills', '-y'], {
+const result = await handleSkillsCli(['add', 'houjallen/agent-skills', '-y'], {
   version: ctx.programVersion,
+  cwd: ctx.config.directory,
 });
+// process.exit(result.code) if result.code !== 0
 ```
 
+`easbot skills` is registered in `packages/agent/src/cli/commands/skills.ts` via `registerSkillsCommand()`. Commander.js `skills.<subcommand>` converts flags to argv and dispatches to `handleSkillsCli`. The `skills store` sub-family is also registered in the same module via `registerSkillsCommand()`.
+
 ## API
 
 | Module | Exports | Notes |
 |---|---|---|
-| `add` | `runAdd / parseAddOptions / initTelemetry` | Skill add pipeline |
-| `remove` | `removeCommand / parseRemoveOptions` | Skill removal |
-| `list` | `runList / parseListOptions` | List installed skills |
-| `find` | `runFind / parseFindOptions / searchSkillsAPI` | skills.sh search |
-| `update` | `runUpdate / parseUpdateOptions` | Incremental update |
-| `install` | `runInstallFromLock` | Restore from skills-lock.json |
-| `sync` | `runSync / parseSyncOptions` | Sync from node_modules |
-| `use` | `runUse / parseUseOptions / buildUsePrompt` | One-shot use |
-| `cli-handler` | `handleSkillsCli / renderBanner / renderHelp / SkillsCliDeps / SkillsCliResult` | CLI bridge |
-| `interfaces` | `setGlobalAdapter / setInstanceAdapter / setAgentAdapter / getGlobal / getInstance / ...` | Dependency injection |
-| `agents` | `agents / detectInstalledAgents / getUniversalAgents / ...` | Agent metadata |
-| `installer` | `installSkillForAgent / listInstalledSkills / getCanonicalSkillsDir` | Physical install |
-| `skill-lock` | `readSkillLock / writeSkillLock / addSkillToLock / removeSkillFromLock` | Global lockfile |
-| `local-lock` | `readLocalLock / writeLocalLock / computeSkillFolderHash` | Project lockfile |
-| `telemetry` | `track / flushTelemetry / setVersion / fetchAuditData` | Usage stats + security audit |
-| `i18n` | `t / initI18n / registerI18nResources / changeI18nLanguage` | Internationalization |
+| `types` | `AgentType`, `Skill`, `AgentConfig`, `ParsedSource`, `RemoteSkill` | Core type definitions (70+ AgentType union) |
+| `agents` | `agents`, `detectInstalledAgents`, `getAgentConfig`, `getAgentSkillDirs`, `getUniversalAgents`, `getAgentGlobalSkillDirs`, `isUniversalAgent`, `matchesUniversalScope` etc. | Agent config matrix + classifiers |
+| `skills` | `parseSkillMd`, `discoverSkills`, `filterSkills`, `getSkillDisplayName`, `isSubpathSafe`, `shouldInstallInternalSkills` | SKILL.md discovery/parse |
+| `installer` | `installSkillForAgent`, `installRemoteSkillForAgent`, `installBlobSkillForAgent`, `installWellKnownSkillForAgent`, `listInstalledSkills`, `isSkillInstalled`, `getCanonicalSkillsDir`, `getInstallPath`, `sanitizeName` | Physical install APIs |
+| `installer/post-install` | `buildMatrix`, `planActions`, `applyActions`, `probeCell`, `runPostInstallReconcile` | Install matrix + diff application |
+| `installer/store` | `acquireSourceClone`, `ensureCachedSource`, `installFromCache`, `cleanCache`, `getCacheRepoDir`, `getSourceDir` | Three-layer source/cache/install architecture |
+| `add` | `runAdd`, `parseAddOptions`, `initTelemetry`, `AddOptions` | Add flow |
+| `find` | `runFind`, `parseFindOptions`, `searchSkillsAPI`, `FindOptions`, `SearchSkill` | Search (skills.sh + local store) |
+| `list` | `runList`, `parseListOptions` | List |
+| `remove` | `removeCommand`, `parseRemoveOptions`, `RemoveOptions` | Remove |
+| `update` | `runUpdate`, `parseUpdateOptions`, `hasProjectSkills`, `matchesSkillFilter`, `resolveUpdateScope`, `UpdateScope` | Incremental update |
+| `store-cmd` | `runStore`, `parseStoreOptions`, `runStoreList`, `runStoreClean`, `runStoreUpdate`, `runStoreRemove`, `StoreOptions` | Ops: store/cache/index management |
+| `use` | `runUse`, `parseUseOptions`, `buildUsePrompt`, `materializeUseSkill`, `launchAgentInteractively`, `UseOptions`, `MaterializedUseSkill` | one-shot use |
+| `doctor` | `runDoctor` | Health check + link cleanup |
+| `cli-handler` | `handleSkillsCli`, `renderBanner`, `renderHelp`, `SkillsCliDeps`, `SkillsCliResult` | CLI bridge for agent reuse |
+| `interfaces` | `setGlobalAdapter`, `setInstanceAdapter`, `setAgentAdapter`, `getGlobal`, `getInstance`, `getHomeDir`, `getXdgData`, `getXdgConfig`, `getXdgState`, `getXdgCache`, `getProjectDirectory`, `resetGlobalAdapter`, `resetInstanceAdapter`, `hasAgentAdapter` | Path/Agent DI |
+| `skill-lock` | `readSkillLock`, `writeSkillLock`, `addSkillToLock`, `removeSkillFromLock`, `getSkillFromLock`, `getGitHubToken`, `getAllLockedSkills`, `dismissPrompt`, `isPromptDismissed`, `resetGhAuthWarning` | Global lockfile |
+| `local-lock` | `readLocalLock`, `writeLocalLock`, `addSkillToLocalLock`, `removeSkillFromLocalLock`, `computeSkillFolderHash`, `getLocalLockPath` | Project lockfile |
+| `git` | `cloneRepo`, `cleanupTempDir`, `parseGitHubRepoUrl`, `isGitHubHttpsCloneUrl`, `isGitHubSsoAuthError`, `GitCloneError` | Git subprocess cloning with fallbacks |
+| `blob` | `fetchRepoTree`, `findSkillMdPaths`, `getSkillFolderHashFromTree`, `tryBlobInstall`, `toSkillSlug`, `resetRepoTreeAuthState` | GitHub API blob fallback |
+| `telemetry` | `track`, `flushTelemetry`, `setVersion`, `fetchAuditData`, `setDetectedAgent` | Usage stats + security |
+| `sanitize` | `sanitizeMetadata`, `stripTerminalEscapes` | Output sanitization |
+| `detect-agent` | `detectAgent`, `getAgentName`, `getAgentType`, `isRunningInAgent` | Agent environment detection |
+| `providers/wellknown` | `wellKnownProvider`, `WellKnownProvider` | WellKnown host: parse index + pull SKILL.md |
+| `providers/registry` | `findProvider`, `registerProvider`, `getProviders`, `registry` | Provider registry + HostProvider interface |
+| `sources` | `registerSource`, `listSources`, `findSource`, `findSourcesByCategory`, `listAllEntries`, `createWellKnownSource`, `createLocalPluginSource` | PluginSource registry (voting 0044) |
 | `frontmatter` | `parseFrontmatter` | YAML frontmatter parser |
-| `providers` | `wellKnownProvider / registry / findProvider` | Well-Known & custom host providers |
+| `constants` | `AGENTS_DIR`, `SKILLS_SUBDIR`, `UNIVERSAL_SKILLS_DIR` | Convention directory constants |
+| `utils/ansi` | `BOLD`, `DIM`, `RESET`, `TEXT`, `CYAN` etc. | ANSI terminal helpers |
+
+## Supported Agent List (Complete)
+
+The `AgentType` union in `types.ts` contains 70+ agent types, including:
 
-## Global Path Injection
+`easbot`, `claude-code`, `cursor`, `codex`, `eve`, `opencode`, `aider-desk`, `amp`, `antigravity`, `astrbot`, `augment`, `autohand-code`, `bob`, `openClaw`, `cline`, `codearts-agent`, `codebuddy`, `codemaker`, `codestudio`, `command-code`, `continue`, `cortex`, `crush`, `deepagents`, `devin`, `depto`, `droid`, `firebender`, `forgecode`, `gemini-cli`, `github-copilot`, `goose`, `hermes-agent`, `inference-sh`, `iflow-cli`, `jazz`, `junie`, `kilo`, `kimi-code-cli`, `kiro-cli`, `kode`, `lingma`, `loaf`, `mcpjam`, `mistral-vibe`, `moxby`, `mux`, `neovate`, `openhands`, `om`, `pi`, `qoder`, `qoder-cn`, `qwen-code`, `replit`, `reasonix`, `roo`, `roodev`, `tabnine-cli`, `terramind`, `tinycloud`, `trae`, `trae-cn`, `warp`, `windsurf`, `zed`, `zencoder`, `zenflow`, `pochi`, `promptscript`, `adal`, `antigravity-cli`, `mistral`, plus the virtual type `universal`.
 
-To avoid fighting with the host (agent / gateway) over XDG / home, `@easbot/skills` resolves paths through dependency injection by default:
+All agent configurations (displayName, skillsDir, globalSkillsDir, universal flag, install detection functions) are defined in `src/agents.ts`.
+
+## Global Path Dependency Injection
+
+To avoid conflicting with the host (agent/gateway) over XDG / home, `@easbot/skills` resolves paths through dependency injection by default:
 
 ```typescript
 import {
   setGlobalAdapter,    // inject IGlobal.Path
   setInstanceAdapter,  // inject IInstance.directory / worktree
-  setAgentAdapter,     // inject SubAgentRunner / LocalAgentRunner / triggerEvent
+  setAgentAdapter,     // inject SkillsAgentAdapter (subAgentRunner / localAgentRunner / triggerEvent)
   getHomeDir,
   getXdgConfig,
   getXdgData,
@@ -121,8 +219,8 @@ setGlobalAdapter({
   Path: {
     home: '/Users/me',
     data: '/Users/me/.local/share/easbot',
-    config: '/Users/me/.config/easbot',
-    state: '/Users/me/.local/state/easbot',
+    config: '...',
+    state: '...',
     cache: '/Users/me/.cache/easbot',
     log: '/Users/me/.local/state/easbot/log',
     bin: '/Users/me/.local/bin',
@@ -135,20 +233,29 @@ setInstanceAdapter({
 });
 ```
 
-When no adapter is set, `@easbot/skills` falls back to `xdg-basedir` + `homedir()`, keeping full backward compatibility with the v1 standalone CLI.
+When no adapter is set, `@easbot/schools` falls back to `xdg-basedir` + `homedir()`, keeping full backward compatibility with the v1 standalone CLI.
 
 ## Data Layout
 
 | Path | Purpose |
 |---|---|
-| `${Global.Path.data}/skills/` | Skill directory loaded by the agent at runtime |
-| `${Global.Path.data}/state/skills/.skill-lock.json` | Global install lockfile |
-| `<cwd>/.agents/skills/` / `<cwd>/skills/` | Project-level skill directories |
+| `${Global.Path.data}/skills/` | Skills dir loaded by the agent at runtime |
+| `${Global.Path.data}/skills/.skill-lock.json` | Global install lockfile (same root as store) |
+| `${Global.Path.data}/skills/store/<sourceKey>/` | **Store physical dir** (sourceKey-hashed normalized source; written once by `add`, reused by `update`) |
+| `${Global.Path.data}/skills/store/index.json` | **Store defs index** (key = skillName; records registryKey / type / url / skillPath / computedHash) |
+| `${Global.Path.cache}/skills/cache/<owner>/<repo>/` | **Cache physical** (remote source download/materialize cache; local source = same as user directory) |
+| `<cwd>/.agents/skills/` or `<cwd>/skills/` | Project-level skill directories |
 | `<cwd>/skills-lock.json` | Project-level lockfile |
 | `<home>/.config/easbot/skills/` | XDG config fallback |
 
 > When delegated from `@easbot/agent`, everything lands under `${Global.Path.data}` — sibling to Gateway / MCP / Session / Contact modules.
 
+## External Audit Hooks (skills.sh)
+
+`telemetry.ts` sends telemetry/audit data back to skills.sh (configurable via `SKILLS_API_URL`) for:
+- Skill audit (`fetchAuditData` returns per-skill `PartnerAudit` information)
+- Security gate check (skipped with `--dangerously-accept-openclaw-risks` flag)
+
 ## Development
 
 ```bash
@@ -161,7 +268,7 @@ pnpm build
 # Watch build
 pnpm dev
 
-# Tests (vitest; single file: npx vitest run src/__tests__/xxx.test.ts)
+# Tests (vitest)
 pnpm test
 pnpm test:run
 
@@ -180,11 +287,11 @@ pnpm clean
 ## Publishing
 
 ```bash
-# Linux / macOS
-pnpm publish:npm           # = bash scripts/publish.sh
+# Linux /macOS
+bash scripts/publish.sh
 
 # Windows PowerShell
-pnpm publish:npm:win       # = powershell -ExecutionPolicy Bypass -File scripts/publish.ps1
+powershell -ExecutionPolicy Bypass -File scripts/publish.ps1
 
 # Equivalent manual flow
 pnpm build
@@ -193,8 +300,8 @@ pnpm publish --access public --git-checks false --registry https://registry.npmj
 
 ## Runtime Notes
 
-- Uses Node built-ins (`fs/promises`, `node:os`, `node:path`, `node:child_process`); **not** browser-compatible.
-- Pulls in `simple-git`, `@vercel/detect-agent`, `@clack/prompts`, `picocolors`, `xdg-basedir`, `zod`, `yaml` for GitHub access, agent detection, interactive prompts, terminal styling, XDG resolution, and frontmatter validation.
+- Uses Node built-ins (`fs/promises`, `NODE:OS`, `node:path`, `node:child_process`); **not** browser-compatible.
+- Dependencies: `simple-git`, `@vercel/detect-agent`, `@clack/prompts`, `picocolors`, `xd-basedir`, `zod`, `yaml`.
 - `engines.node >= 22.22.3` — Node 22 LTS recommended.
 
 ## License