skill-tui-cli

stc scans a repository, explains which skills match its dependencies and files, and loads a deliberately small set into that project. Skills live in one central registry and can be reused through bookmarks instead of being copied into every global agent directory.

Quick start

npm install -g skill-tui-cli
stc scan

No global install:

npx --package skill-tui-cli stc scan

Requires Node.js 20 or later. Use the package name with npx; npx stc may resolve an unrelated package.

The first useful loop is intentionally short:

stc scan                       # inspect this project and choose skills
stc find react                 # search remote Skill catalogs when needed
stc bm add web -s testing,typescript
stc inject web --project .     # load the saved set into this project

Interactive controls: Esc returns from a nested prompt (or cancels at the root); Ctrl+C interrupts the whole command with exit code 130.

Why stc?

• Project-aware — reads dependency, language, configuration, workspace, and repository signals across single projects, monorepos, or adjacent Git repositories.
• Explainable — ranks local recommendations, keeps remote results in a separate section, and lets you inspect a SKILL.md before installation.
• Focused — injects only the selected skills by link, copy, or an AGENTS.md prompt block.
• Reusable — saves named skill sets as bookmarks and keeps source provenance in a central registry.
• Automation-ready — supports declarative stc.yaml, lock files, dry-run planning, frozen checks, diffs, and transactional apply.
• Agent-assisted, user-approved — recommend --llm creates a guarded prompt locally; the generated workflow stops for approval before any install.

How it works

1. Scan — stc scan detects projects and ranks skills from concrete repository signals.
2. Choose — review the shortlist, search the catalog, inspect candidates, or save the selection as a bookmark.
3. Store — installed skills live under ~/.skill-tui/skills with source and commit metadata.
4. Inject — load a project-specific set into .agents/skills, copy it for a self-contained project, or write a prompt block.

Linked projects automatically see updates made to the central registry. Copy mode is available when the project must remain independent from that registry.

Common workflows

Discover locally or remotely

stc scan
stc scan --remote 15
stc find react
stc inspect vercel-labs/agent-skills --skill web-design

Remote scan only sends public technology terms derived from built-in mappings. It does not send the project path, repository name, README text, or unknown private dependency names. Its generic fallback puts every detected framework first, actual components second, and engineering capabilities last. The remote picker supports unlimited Next batch actions and wraps after the finite candidate pool is exhausted.

Long-running TTY operations show loading feedback for remote scan, direct find, inspect, source downloads, project refresh, and apply. JSON and redirected output remain animation-free.

Ask an AI to prepare an exact plan

stc agent install --agent codex --dry-run
stc agent install --agent codex -y
stc recommend . --llm

recommend --llm does not call a model or upload project files. It creates a self-contained prompt that asks the AI to rebuild a profile from current project evidence, search every core framework and actual component through stc, inspect candidates, show the exact registry plan, and stop for approval before add -y. It uses no fixed Next.js, NestJS, or other stack recipe; newly added dependencies participate in the next analysis.

Make project state reproducible

stc project init
stc project add --from-bookmark web --dry-run
stc plan --refresh
stc apply --dry-run
stc apply -y
stc check --frozen

Example stc.yaml:

version: 1
defaults:
  agents: [codex]
  mode: link
skills:
  - name: react-best-practices
    source: vercel-labs/agent-skills
    path: skills/react-best-practices
    ref: main

apply stages changes, updates the registry and project targets, then writes the lock last. A failure restores the previous registry, targets, metadata, ownership markers, and lock.

Safety by design

| Boundary | Behavior | | --- | --- | | Global agent directories | Read-only discovery sources; only explicit stc agent install writes a bundled stc Skill there | | External sources | add --dry-run --json exposes the exact install, skip, or replace plan first | | Existing project content | Unmanaged name conflicts are reported, not overwritten | | Registry updates | Each source is checked once; missing upstream skills are kept in automatic or dry-run flows | | Project cleanup | prune only targets paths recorded in .stc-managed.json and blocks on external changes | | CI checks | check --frozen performs no writes and no network requests |

Command map

| Goal | Command | | --- | --- | | Recommend skills for a project | stc scan [path] | | Include explainable remote suggestions | stc scan [path] --remote [count] | | Search remote catalogs | stc find [query] | | Generate a guarded AI planning prompt | stc recommend [path] --llm | | Inspect one remote skill without installing | stc inspect <source> --skill <name> | | Preview or install a source | stc add <source> [--dry-run] [-y] | | Browse discovered skills | stc ls [query] | | Save and reuse selections | stc bm <sub> · stc inject <bookmark> | | Diagnose stores and loading | stc audit · stc status | | Update registry skills | stc update [-y] | | Plan and apply declared state | stc plan · stc apply --dry-run\|-y | | Detect or inspect drift | stc check --frozen · stc diff | | Preview managed cleanup | stc prune --dry-run |

Run stc --help or open the usage guide for flags, JSON output, interactive navigation, and recovery behavior.

Language

English is the default. Choose a language for one command, via an environment variable, or persist it:

stc --lang zh-CN scan
STC_LANG=zh-CN stc scan
stc config set language zh-CN

Priority: --lang → STC_LANG → saved configuration → en.

Documentation

• Usage guide
• Architecture and design
• Product direction
• Implementation plan
• New capabilities guide
• FAQ

让每个项目只装载真正需要的 Agent Skills

stc 面向 Codex、Claude Code、Cursor 等支持 SKILL.md 的 Agent。它读取项目依赖、语言、配置和 workspace 等信号，给出可解释的技能推荐，并把选中的小集合按项目装载；技能实体统一保存在中心 registry，可通过书签跨项目复用。

快速开始

npm install -g skill-tui-cli
stc scan

不全局安装：

npx --package skill-tui-cli stc scan

需要 Node.js 20 或更高版本。使用 npx 时请指定包名 skill-tui-cli；npx stc 可能解析到另一个无关包。

核心工作流

1. 扫描 — stc scan 从具体项目结构和代码信号中排序推荐。
2. 选择 — 查看候选、搜索远端目录、安装前检查 SKILL.md，或把组合保存成书签。
3. 集中存储 — 技能保存在 ~/.skill-tui/skills，同时记录来源和 commit。
4. 按项目装载 — 通过软链接、复制或 AGENTS.md Prompt Block，把选定技能装载到当前项目。

stc scan --remote 15
stc find react
stc bm add web -s testing,typescript
stc inject web --project .

交互快捷键：Esc 从子步骤返回上一层（根步骤则取消命令）；Ctrl+C 始终中断整个命令并返回退出码 130。

scan --remote 只发送内置映射得到的公开技术词，不会发送项目路径、仓库名、README 原文或未知的私有依赖名。通用兜底排序会先覆盖全部已检测框架，再覆盖实际组件，最后补充工程能力；远端选择器可不限次数“换一批”，有限候选查看完后会循环到第一批。

TTY 中的远端扫描、直接 find、inspect、来源下载、项目 refresh 与 apply 会显示 loading；JSON 和重定向输出不包含动画。

AI 辅助计划

stc agent install --agent codex --dry-run
stc agent install --agent codex -y
stc recommend . --llm

recommend --llm 不调用模型，也不上传项目文件。它会在本地生成一份自包含 Prompt，要求 AI 每次基于当前依赖、配置和架构重建证据，不套用固定技术栈模板；AI 会通过 stc 搜索每个核心框架和实际组件，检查候选、展示精确 registry 计划，并在 add -y 前停下来等待确认。新增依赖会自然进入下一次分析。

声明式项目状态

stc project init
stc project add --from-bookmark web --dry-run
stc plan --refresh
stc apply --dry-run
stc apply -y
stc check --frozen

• stc.yaml 描述期望状态；lock 文件保存精确解析结果。
• apply 使用 staging、备份和回滚，最后才写 lock。
• 非受管同名目录只报告冲突，不会覆盖。
• prune 只处理 .stc-managed.json 记录的目标，发现外部改动时会阻断。
• 除显式执行 stc agent install 外，全局 Agent 技能目录始终作为只读发现源。

完整命令、交互流程与恢复行为请查看使用指南，设计边界请查看架构文档。

License

MIT. Adapted third-party code is documented in THIRD_PARTY_NOTICES.md.