@easbot/skills 0.3.12 → 0.3.14

package/README.en.md

@@ -2,34 +2,36 @@
 
 # @easbot/skills
 
-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`.
+Skill management subsystem for the EASBot ecosystem. Handles discovery, installation, removal, search, update, one-shot use (`use`), template initialization (`init`), 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 delegated to by the `@easbot/agent` main CLI via Commander.js, making `easbot skills ...` and `easbot-skills ...` equivalent.
+Usable both as a standalone CLI (`easbot-skills`) and as a library delegated to by the `@easbot/agent` main CLI via Commander.js — `easbot skills ...` and `easbot-skills ...` are equivalent.
 
 ## Version
 
-v0.3.11
+v0.3.13
 
 ## 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 + Zod remote-skill payload validation
+- **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
+- **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`, `dexto` etc.)
+  - **Universal shared path**: 16 agents (`eve` / `amp` / `gemini-cli` / `github-copilot` / `qwen-code` / `roo` / `windsurf` / `zed` / `claude-code` etc.) share `.agents/skills` via the `universal` scope
   - **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
+- **Install Matrix / Post-Install Reconcile**: `AgentInstallMatrix` (agent × skill 2D table, `probeCell` cell-by-cell); post-install cell reconcile (missing → link, excess → remove)
+- **Dependency Injection** (decision 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** (decision 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`)
+- **i18n**: built-in zh-CN / en-US translations; all user-facing strings go through `t()`, with fallback to English literal when the key is missing
+- **Telemetry + Audit**: built-in `skills.sh` partner-audit reporting, OpenClaw risk scoping, telemetry flush (`flushTelemetry`)
+- **Unified Prompt namespace** (Session 4): every interactive flow goes through [`@easbot/terminal.Prompt`](../terminal/README.en.md) — cancellation contract centralized (`Prompt.cancel` returns `never` and calls `process.exit(0)` internally), icons centralized through `Symbol` (writing `✓✗◆` literals is **forbidden**), colors centralized through `theme.colorize()`
 
 ## Installation
 
@@ -54,47 +56,49 @@ src/
 ├── types.ts                # AgentType, Skill, AgentConfig, ParsedSource, RemoteSkill
 ├── agents.ts               # Agent config matrix (72+) + classification functions
 ├── skills.ts               # Skill discovery: parseSkillMd, discoverSkills, filterSkills
+├── constants.ts            # AGENTS_DIR / SKILLS_SUBDIR / UNIVERSAL_SKILLS_DIR
+├── frontmatter.ts          # YAML frontmatter parser
+├── hash.ts                 # Hashing helpers: computeFromDir / computeSnapshotHash
+├── source-parser.ts        # Source normalization: parseSource, parseOwnerRepo, sanitizeSubpath, isRepoPrivate
+├── interfaces.ts           # Dependency injection: setGlobalAdapter / setInstanceAdapter / setAgentAdapter
+├── detect-agent.ts         # Detect running AI agent: detectAgent / isRunningInAgent
+├── sanitize.ts             # Control-char sanitization: sanitizeMetadata / stripTerminalEscapes
+├── telemetry.ts            # Telemetry: track, flushTelemetry, fetchAuditData, setVersion
+├── git.ts                  # Repo clone / cleanupTempDir / parseGitHubRepoUrl
+├── blob.ts                 # GitHub API fallback: fetchRepoTree, tryBlobInstall, toSkillSlug
+├── skill-lock.ts           # Global lockfile (skill-lock.json)
+├── local-lock.ts           # Project lockfile (skills-lock.json) + folder SHA-256
 ├── 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.
+│   ├── installer.ts          # Physical install: installSkillForAgent / installRemoteSkillForAgent / installBlobSkillForAgent / installWellKnownSkillForAgent / linkSkillDir / copySkillDir / listInstalledSkills / getInstallPath / getCanonicalPath / sanitizeName
+│   ├── post-install.ts       # Post-install reconcile matrix: planActions / buildMatrix / probeCell / runPostInstallReconcile
+│   ├── store.ts              # Three-layer source/cache/install convergence: acquireSourceClone / ensureCachedSource / cleanCache / getCacheRepoDir / getStoreDir
+│   └── store-types.ts        # Shared types: StoreSourceType / SkillEntry / PluginDefinition / MarketDefinition / SkillLocation / STORE_INDEX_VERSION / parsePluginId / storePathForSkillLock
 ├── 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
+├── list.ts                 # List installed skills (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/
+├── sources/                # Plugin Source registry (decision 0044)
 │   ├── 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)
+├── utils/                 # Helpers
+│   ├── ansi.ts               # Hardcoded SGR constants (RESET / BOLD / DIM / TEXT / CYAN / YELLOW / MAGENTA)
+│   ├── format.ts             # Label helpers: pBgLabel / pErrorBadge (agent badge + ERROR badge)
+│   ├── color.ts              # picocolors-shape bridge (dim/red/green/yellow/cyan/bold/... → @easbot/terminal.colorize + theme)
+│   └── output.ts             # Human-output helpers: printHuman / wrapJson / emitJson / formatListTruncated
 ├── cli.ts                  # Standalone CLI entry (easbot-skills)
-├── cli-handler.ts          # CLI handler (for agent reuse)
-└── src/sources/             # PluginSource registry (voting 0044)
+└── cli-handler.ts          # CLI handler (for agent reuse)
 ```
 
 ## CLI Usage
@@ -106,7 +110,7 @@ src/
 easbot-skills add houjallen/agent-skills
 easbot-skills add https://github.com/houjallen/agent-skills -g
 
-# Search (interactive fzf picker)
+# Search (interactive search-multi-select)
 easbot-skills find typescript --owner houjallen
 
 # List installed (project/global)
@@ -135,19 +139,71 @@ 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
+easbot-skills doctor -a easbot -y                  # Check one agent + auto-cleanup
+easbot-skills dr -g                                # Global only
+
+# Template initialization (create SKILL.md from locale template)
+easbot-skills init my-skill
+easbot-skills init                                  # Creates SKILL.md under cwd/<basename>/skills
+```
+
+### Subcommand list (standalone CLI)
+
+```
+easbot-skills add <source>          # Add a skill (aliases: a / install / i)
+easbot-skills find [query]          # Search (aliases: search / f / s)
+easbot-skills list                  # List installed (aliases: ls)
+easbot-skills remove [skills...]    # Remove (aliases: rm / r)
+easbot-skills update [skills...]    # Incremental update (aliases: upgrade / check)
+easbot-skills use <source[@skill]>  # One-shot use
+easbot-skills init [name]           # Template initialization
+easbot-skills doctor                # Health check (aliases: dr)
+easbot-skills store <subcommand>    # Store-centric ops (list / clean / update / remove)
 ```
 
+### `store` subcommands (Decision 0049-yyy)
+
+```
+# List all sources inside the store (human-readable mode shows full 64-hex sourceKey for downstream update / remove)
+easbot-skills store list
+easbot-skills store list [keyword]            # Filter by skill name
+
+# Reset the store (default: wipe store dirs + index.json; --force additionally clears cache)
+easbot-skills store clean
+easbot-skills store clean --force
+
+# Refresh store from source (does NOT touch agent distribution)
+# No source-key → full store refresh
+# With source-key (64-hex, copy from `store list`) → refresh only that source (entire source mirror)
+easbot-skills store update
+easbot-skills store update <full-source-key>   # Decision 0049-yyy: [keyword] → [source-key]
+
+# Remove a single store source (--force additionally clears cache; local source cache = user dir, NEVER deleted)
+easbot-skills store remove <source-key>
+easbot-skills store remove <source-key> --force
+```
+
+**Core semantics**:
+- `store` operates on the **whole-source mirror** (not on individual skills) — the store is a
+  cp of the source; either refresh the entire source or do nothing; there is no "update
+  only one skill inside the store" semantic.
+- To "trigger store refresh + agent distribution by skill name", use `skills update <name>`
+  — that path already does full-source pull + per-skill hash compare → agent distribution.
+- `store list` prints the **full** sourceKey (Decision 0049-yyy: previously 8-char truncated → users
+  couldn't reuse it directly).
+
 ### Delegated from a host CLI
 
-`@easbot/agent`'s `easbot skills ...` reuses all sub-commands via `handleSkillsCli(args, deps)`:
+`@easbot/agent`'s `easbot skills ...` reuses every subcommand via `handleSkillsCli(args, deps)`:
 
 ```typescript
-import { handleSkillsCli, setGlobalAdapter, setInstanceAdapter } from '@easbot/skills';
+import { handleSkillsCli, setAgentAdapter } from '@easbot/skills';
 
-setGlobalAdapter({ Path: Global.Path });
-setInstanceAdapter({ directory: ctx.config.directory, worktree: Instance.worktree });
+setAgentAdapter({
+  global: Global,        // IGlobal
+  instance: Instance,    // IInstance
+  // subAgentRunner / localAgentRunner / triggerEvent are optional
+});
 
 const result = await handleSkillsCli(['add', 'houjallen/agent-skills', '-y'], {
   version: ctx.programVersion,
@@ -156,105 +212,354 @@ const result = await handleSkillsCli(['add', 'houjallen/agent-skills', '-y'], {
 // 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()`.
+`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 registered in the same module.
 
-## API
+## API (by module)
 
-| Module | Exports | Notes |
-|---|---|---|
-| `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 |
-| `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:
-
-`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`.
-
-All agent configurations (displayName, skillsDir, globalSkillsDir, universal flag, install detection functions) are defined in `src/agents.ts`.
+> All exports flow from the top-level entry [`src/index.ts`](src/index.ts) and are grouped by theme below.
+
+### 1. Core types
+
+```typescript
+import type { AgentType, Skill, AgentConfig, ParsedSource, RemoteSkill } from '@easbot/skills';
+```
+
+| Type | Description |
+|---|---|
+| `AgentType` | 70+ Agent union (includes the `universal` virtual type) |
+| `Skill` | Skill model (name / path / frontmatter / pluginName / subpath etc.) |
+| `AgentConfig` | Agent configuration (name / displayName / skillsDir / globalSkillsDir / detectInstalled) |
+| `ParsedSource` | Source descriptor (type / url / ref / subpath) |
+| `RemoteSkill` | Remote-skill model |
+
+### 2. Agent system
+
+```typescript
+import {
+  agents,                          // Record<AgentType, AgentConfig>
+  EVE_SUBAGENTS_DIR,               // 'agent/subagents'
+  PROJECT_SKILLS_DIR_PATTERN,      // /^\.[^/]+\/skills$/
+  detectInstalledAgents,
+  getAgentConfig,
+  getAgentGlobalSkillDirs,         // List of project-level agent global skill dirs
+  getAgentProjectSkillDirs,
+  getAgentProjectSkillContainerPrefixes,
+  getAgentSkillDirs,
+  getEveSubagents,
+  getNonUniversalAgents,           // Non-universal agents
+  getOpenClawGlobalSkillsDir,
+  getUniversalAgents,
+  isUniversalAgent,
+  matchesUniversalScope,
+} from '@easbot/skills';
+import type { AgentSkillDirsResult, UniversalScope } from '@easbot/skills';
+```
+
+### 3. Skill discovery / install
+
+```typescript
+import {
+  discoverSkills, filterSkills, getSkillDisplayName,
+  isSubpathSafe, parseSkillMd, shouldInstallInternalSkills,
+  installSkillForAgent, installRemoteSkillForAgent, installBlobSkillForAgent,
+  installWellKnownSkillForAgent,
+  linkSkillDir, copySkillDir,
+  getAgentBaseDir, getCanonicalPath, getCanonicalSkillsDir,
+  getEveSubagentSkillsDir, getInstallPath,
+  isSkillInstalled, listInstalledSkills, sanitizeName,
+} from '@easbot/skills';
+import type { DiscoverSkillsOptions, InstallMode, InstalledSkill } from '@easbot/skills';
+
+// Post-install matrix
+import { applyActions, buildMatrix, planActions, probeCell, runPostInstallReconcile } from '@easbot/skills';
+import type { AgentInstallMatrix, CellAction, CellScope, InstallCell, InstallState,
+  PostInstallInput, PostInstallResult } from '@easbot/skills';
+```
+
+### 4. Source parsing
+
+```typescript
+import { parseSource, parseOwnerRepo, getOwnerRepo, isRepoPrivate, sanitizeSubpath } from '@easbot/skills';
+```
+
+### 5. Command entry points (`run*` + `parse*`)
+
+```typescript
+import { runAdd, parseAddOptions, initTelemetry } from '@easbot/skills';
+import type { AddOptions } from '@easbot/skills';
+
+import { runFind, parseFindOptions, searchSkillsAPI } from '@easbot/skills';
+import type { FindOptions, ParseFindOptionsResult, SearchSkill } from '@easbot/skills';
+
+import { runList, parseListOptions } from '@easbot/skills';
+import { removeCommand, parseRemoveOptions } from '@easbot/skills';
+import type { RemoveOptions } from '@easbot/skills';
+
+import { runUpdate, parseUpdateOptions, hasProjectSkills, matchesSkillFilter, resolveUpdateScope } from '@easbot/skills';
+import type { UpdateCheckOptions, UpdateScope } from '@easbot/skills';
+
+import { runUse, parseUseOptions, buildUsePrompt, materializeUseSkill, launchAgentInteractively } from '@easbot/skills';
+import type { AgentProcess, AgentSpawn, MaterializedUseSkill, ParseUseOptionsResult, UseOptions, UseSkill } from '@easbot/skills';
+
+import { runDoctor } from '@easbot/skills';
+
+import { runStore, parseStoreOptions, runStoreList, runStoreClean, runStoreUpdate, runStoreRemove } from '@easbot/skills';
+import type { StoreOptions } from '@easbot/skills';
+```
+
+### 6. Lockfile / hashing
+
+```typescript
+import {
+  readSkillLock, writeSkillLock, addSkillToLock, removeSkillFromLock, getSkillFromLock,
+  getGitHubToken, getAllLockedSkills, getSkillsBySource,
+  getSkillLockPath, computeContentHash, storePathFromLockEntry,
+  dismissPrompt, isPromptDismissed, resetGhAuthWarning,
+} from '@easbot/skills';
+import type { DismissedPrompts, SkillLockEntry, SkillLockFile } from '@easbot/skills';
+
+import {
+  readLocalLock, writeLocalLock, addSkillToLocalLock, removeSkillFromLocalLock,
+  getLocalLockPath, storePathFromLocalLockEntry,
+} from '@easbot/skills';
+import type { LocalSkillLockEntry, LocalSkillLockFile } from '@easbot/skills';
+
+import { computeFromDir, computeSnapshotHash } from '@easbot/skills';
+```
+
+### 7. Git / Blob integration
+
+```typescript
+import {
+  DEFAULT_CLONE_TIMEOUT, GitCloneError,
+  cloneRepo, cleanupTempDir, parseGitHubRepoUrl,
+  isGitHubHttpsCloneUrl, isGitHubSsoAuthError,
+} from '@easbot/skills';
+
+import {
+  BLOB_ALLOWED_REPOS,                 // Record<string, { downloadUrl }>
+  toSkillSlug,
+  fetchRepoTree, findSkillMdPaths, getSkillFolderHashFromTree,
+  resetRepoTreeAuthState, tryBlobInstall,
+} from '@easbot/skills';
+import type { BlobInstallResult, BlobSkill, RepoTree, SkillDownloadResponse, SkillSnapshotFile, TreeEntry } from '@easbot/skills';
+```
+
+### 8. Installer support layer (three-layer source / cache / install)
+
+```typescript
+import {
+  acquireSourceClone, ensureCachedSource, installFromCache, cleanCache, cleanCachedRepo,
+  getCacheRepoDir, getCacheRoot, getSourceDir,
+} from '@easbot/skills';
+import type { InstallScope } from '@easbot/skills';
+
+// store-types shared types
+export type {
+  StoreSourceType, SkillScope,
+  SkillEntry, PluginDefinition, MarketDefinition, SkillLocation,
+  DefaultPluginConfig, StoreIndex,
+  STORE_INDEX_VERSION,
+  parsePluginId, pluginDirFromPluginId, storePathForSkillLock,
+} from '@easbot/skills';
+```
+
+### 9. Security / telemetry / Agent detection
+
+```typescript
+import {
+  track, flushTelemetry, fetchAuditData, setVersion, setDetectedAgent,
+} from '@easbot/skills';
+import type { AuditResponse, PartnerAudit, SkillAuditData } from '@easbot/skills';
+
+import { sanitizeMetadata, stripTerminalEscapes } from '@easbot/skills';
+
+import { detectAgent, getAgentName, getAgentType, isRunningInAgent } from '@easbot/skills';
+```
+
+### 10. Provider abstraction
+
+```typescript
+import { wellKnownProvider, WellKnownProvider } from '@easbot/skills';
+import type {
+  WellKnownIndex, WellKnownIndexV1, WellKnownIndexV2,
+  WellKnownSkill, WellKnownSkillEntry, WellKnownSkillEntryV1, WellKnownSkillEntryV2,
+  WellKnownFileContent,
+} from '@easbot/skills';
+
+import { findProvider, getProviders, registerProvider, registry } from '@easbot/skills';
+import type { HostProvider, ProviderMatch, ProviderRegistry, RemoteSkill as ProviderRemoteSkill } from '@easbot/skills';
+```
+
+### 11. Constants & helpers
+
+```typescript
+import { AGENTS_DIR, SKILLS_SUBDIR, UNIVERSAL_SKILLS_DIR, parseFrontmatter } from '@easbot/skills';
+```
+
+### 12. CLI bridge (reused by `@easbot/agent`)
+
+```typescript
+import { handleSkillsCli, renderBanner, renderHelp } from '@easbot/skills';
+import type { SkillsCliDeps, SkillsCliResult } from '@easbot/skills';
+```
+
+### 13. Interface injection (host → skills)
+
+```typescript
+import {
+  setGlobalAdapter, setInstanceAdapter, setAgentAdapter,
+  resetGlobalAdapter, resetInstanceAdapter,
+  getGlobal, getInstance, getAgentAdapter, getHomeDir,
+  getXdgConfig, getXdgData, getXdgState, getXdgCache,
+  getProjectDirectory,
+  hasAgentAdapter, requireAgentAdapter,
+} from '@easbot/skills';
+import type { SkillsAgentAdapter } from '@easbot/skills';
+import type { IGlobal, IInstance, ISubAgentRunner } from '@easbot/skills';
+```
+
+### 14. Plugin Source registry (decision 0044)
+
+```typescript
+import { registerSource, unregisterSource, listSources, findSource, findSourcesByCategory, listAllEntries,
+  createWellKnownSource, createLocalPluginSource } from '@easbot/skills';
+import type {
+  PluginSource, PluginSourceCategory, PluginSourceEntry, PluginSourceLoadResult,
+  WellKnownSourceOptions, LocalPluginSourceOptions,
+} from '@easbot/skills';
+```
+
+```typescript
+import { registerSource, createWellKnownSource, createLocalPluginSource } from '@easbot/skills';
+
+// 1) Register a well-known endpoint as a plugin source
+registerSource(createWellKnownSource({
+  url: 'https://mintlify.com/docs',
+}));
+
+// 2) Register a local plugin.json as a plugin source
+registerSource(createLocalPluginSource({
+  basePath: process.cwd(),
+}));
+
+// 3) At @easbot/agent bootstrap, pull every source
+import { listSources } from '@easbot/skills';
+for (const source of listSources()) {
+  const entries = await source.fetch();
+  for (const entry of entries) {
+    const { skills } = await source.load(entry);
+    // → inject into PluginDefinition.skills
+  }
+}
+```
+
+## Supported Agent List (complete)
+
+The `AgentType` union in `agents.ts` covers **72 agents** (plus the `universal` virtual type):
+
+`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`, `dexto`, `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`, `zanbura`, `mistral-vibe`, `moxby`, `mux`, `neovate`, `openhands`, `om`, `pi`, `qoder`, `qoder-cn`, `qwen-code`, `replit`, `reasonix`, `roo`, `rovodev`, `tabnine-cli`, `terramind`, `tinycloud`, `trae`, `trae-cn`, `warp`, `windsurf`, `zed`, `zencoder`, `zenflow`, `pochi`, `promptscript`, `adal`, `antigravity-cli`, `mistral`, plus the virtual type `universal`.
+
+**Universal shared `.agents/skills` directory** (16 agents): `eve` / `amp` / `gemini-cli` / `github-copilot` / `qwen-code` / `roo` / `windsurf` / `zed` / `claude-code` etc.
+
+All agent configuration (displayName / skillsDir / globalSkillsDir / universal flag / install detection / `detectInstalled`) lives 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:
+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 SkillsAgentAdapter (subAgentRunner / localAgentRunner / triggerEvent)
+  setAgentAdapter,     // Recommended: one-shot injection (global + instance + optional subAgentRunner etc.)
+  setGlobalAdapter,    // Inject IGlobal.Path
+  setInstanceAdapter,  // Inject IInstance.directory / worktree
   getHomeDir,
   getXdgConfig,
   getXdgData,
   getProjectDirectory,
 } from '@easbot/skills';
 
-setGlobalAdapter({
-  Path: {
-    home: '/Users/me',
-    data: '/Users/me/.local/share/easbot',
-    config: '...',
-    state: '...',
-    cache: '/Users/me/.cache/easbot',
-    log: '/Users/me/.local/state/easbot/log',
-    bin: '/Users/me/.local/bin',
+setAgentAdapter({
+  global: {
+    Path: {
+      home: '/Users/me',
+      data: '/Users/me/.local/share/easbot',
+      config: '/Users/me/.config/easbot',
+      state: '/Users/me/.local/state/easbot',
+      cache: '/Users/me/.cache/easbot',
+      log: '/Users/me/.local/state/easbot/log',
+      bin: '/Users/me/.local/bin',
+    },
   },
-});
-
-setInstanceAdapter({
-  directory: '/repo',
-  worktree: '/repo',
+  instance: {
+    directory: '/repo',
+    worktree: '/repo',
+  },
+  // Optional
+  subAgentRunner: ...,
+  triggerEvent: async (event, input, ctx) => ({ success: true, output: undefined, modified: false }),
 });
 ```
 
-When no adapter is set, `@easbot/schools` falls back to `xdg-basedir` + `homedir()`, keeping full backward compatibility with the v1 standalone CLI.
+When no adapter is set, the skills package falls back to `xdg-basedir` + `homedir()`, keeping full backward compatibility with the v1 standalone CLI.
+
+**`getHomeDir()` priority** (for test isolation):
+1. `process.env.EASBOT_TEST_HOME` (**test-only**, highest priority)
+2. Injected `Global.Path.home`
+3. `os.homedir()` fallback
 
 ## Data Layout
 
-| Path | Purpose |
-|---|---|
-| `${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 injected, every `getXdgData / getXdgCache / ...` resolves through `Global.Path.*`; the default path uses `xdg-basedir + easbot` segments.
 
-> When delegated from `@easbot/agent`, everything lands under `${Global.Path.data}` — sibling to Gateway / MCP / Session / Contact modules.
+| Path | Purpose | Implementation |
+|---|---|---|
+| `${getXdgData()}/skills/` | Skills directory loaded by the agent at runtime | `installer/store.ts` |
+| `${getXdgData()}/skills/.skill-lock.json` | Global install lockfile (same root as store) | `skill-lock.ts` |
+| `${getXdgData()}/skills/store/<sourceKey>/` | **Store physical dir** (sourceKey-hashed normalized source; written once by `add`, reused by `update`) | `installer/store.ts::getStoreDir` |
+| `${getXdgData()}/skills/store/index.json` | **Store defs index** (per-skill registryKey / type / url / skillPath / computedHash) | `installer/store.ts::getStoreDefinitionsFile` |
+| `${getXdgCache()}/skills/cache/<type>/<owner/repo>/` | **Cache physical** (remote source download/materialize cache; local source = same as user directory) | `installer/store.ts::getCacheRepoDir` |
+| `<cwd>/.easbot/skills/<skill>/` | EASBot project-level (not hit by universal agents) | `agents.ts` |
+| `<cwd>/.agents/skills/<skill>/` | Universal agents (claude-code / cursor / gemini-cli etc.) project-level | `agents.ts` |
+| `<cwd>/<agent-glob>/skills/<skill>/` | Each agent's custom project-level (e.g. `~/.trae/skills/`) | `agents.ts` |
+| `<cwd>/skills-lock.json` | Project-level lockfile | `local-lock.ts` |
+| `${getXdgConfig()}/easbot/skills/` | EASBot global skill dir (injected scenario) | `agents.ts::easbot.globalSkillsDir` |
+| `~/.config/easbot/skills/` | EASBot global skill dir (default fallback) | same |
+
+> 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:
+`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)
+- Security gate check (skipped with the `--dangerously-accept-openclaw-risks` flag)
+
+## Interaction Conventions (Session 4 refactor)
+
+Every interactive flow (select / confirm / multiselect / spinner / intro / outro / cancel / Log) goes through [`@easbot/terminal.Prompt`](../terminal/README.en.md):
+
+```typescript
+import { Prompt, Symbol as Glyph } from '@easbot/terminal';
+
+// Cancellation contract: Prompt.cancel returns `never` and exits internally
+const v = await Prompt.select({ message: 'Choose scope', options: [...] });
+if (Prompt.isCancel(v)) await cleanup();
+Prompt.cancel('User cancelled');
+
+// Icons centralized (writing ✓✗◆ literals is FORBIDDEN)
+console.log(`${Glyph.statusIcon('success')} Operation succeeded`); // ✓ green
+console.log(`${Glyph.colorize(Glyph.bar.bullet, 'error')} bullet`);
+
+// Status logging (colors unified with terminal theme)
+Prompt.Log.info('Installing...');
+Prompt.Log.warn('Warning');
+Prompt.Log.error('Failure');
+Prompt.Log.step('Step');
+Prompt.Log.message('Plain message');
+```
+
+Business code **must not** call `pc.green('✓')` directly, **nor** `console.log(p.theme.error(...))`. Everything routes through `utils/color.ts` (the picocolors-shape **bridge**, kept as a transitional layer) and `Glyph.*` / `Prompt.Log.*`.
 
 ## Development
 
@@ -273,11 +578,12 @@ pnpm test
 pnpm test:run
 
 # Code quality
-pnpm biome-lint      # biome check .
-pnpm biome-fix       # biome check --write .
-pnpm biome-format    # biome format .
+pnpm lint            # biome check .
+pnpm lint:fix        # biome check --write .
+pnpm format          # biome format .
+pnpm format:fix      # biome format --write .
 
-# Type check
+# Type-check
 pnpm type-check
 
 # Clean
@@ -287,7 +593,7 @@ pnpm clean
 ## Publishing
 
 ```bash
-# Linux /macOS
+# Linux / macOS
 bash scripts/publish.sh
 
 # Windows PowerShell
@@ -300,10 +606,11 @@ 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.
-- Dependencies: `simple-git`, `@vercel/detect-agent`, `@clack/prompts`, `picocolors`, `xd-basedir`, `zod`, `yaml`.
+- Uses Node built-ins (`fs/promises`, `node:os`, `node:path`, `node:child_process`); **not** browser-compatible.
+- Dependencies: `simple-git`, `@easbot/terminal` (unified Prompt + theme + icons), `xdg-basedir`, `zod`, `yaml`.
+  - **No longer** depends on `@clack/prompts` or `picocolors` — everything converges to `@easbot/terminal` (see Session 4 decisions).
 - `engines.node >= 22.22.3` — Node 22 LTS recommended.
 
 ## License
 
-MIT
+MIT