Usora Dock

A standalone, read-only VS Code extension that lists the Agent Skills discoverable on this machine through Usora Dock: Global, Workspace, and Usora Hub.

It is a companion viewer, not a Hub backend and not a skill marketplace.

What it does

The Usora Dock panel is the single view of the data — the extension contributes an Activity Bar launcher, while the command opens a dedicated panel with a navigation rail (brand row, Skills Explorer root, one entry per source with counts and a gradient Usora hero card); a search toolbar with a 来源 menu over a chip row of agents, then the list grouped into collapsible N 项 groups with gradient avatars and tag pills; and a detail pane with a tag row, a three-column fact card and four tabs (详情 / 文档 / 使用示例 / 相关技能) above a footer action pair. Run Usora Dock: Open Usora Dock Panel from the Command Palette or the Activity Bar launcher.

The panel:

• Group skills into three sources: Global Skills (n), Workspace Skills (n), Usora Hub (n).
• Show name, short description, source and path, with full path and diagnostics in the tooltip / detail pane.
• Filter on name, description, tags, source label, path and Hub state.
• Narrow the list to a single agent label from the rail, the chip row or the 来源 menu.
• Preview Markdown, read the raw SKILL.md, jump to sibling skills and open SKILL.md with native VS Code APIs.
• Explain empty, missing and broken sources instead of hiding them.

Theming

Colours resolve through media/tokens.css in three layers:

1. Have the layout follow the VS Code theme. Surfaces, text, borders, hover and focus all come from --vscode-* variables (sideBar-background, editor-background, foreground, descriptionForeground, panel-border, list-hoverBackground, focusBorder, input-background, textCodeBlock-background, …), so the panel repaints on theme switch with no reload and no theme picker.
2. Keep the brand accent. The reference mockups use a blue→violet gradient. It survives as --ud-brand-* / --ud-tint-* / --ud-gradient-brand / --ud-tile-*, redefined per vscode-light / vscode-dark / vscode-high-contrast body class. This is the one deliberate exception to "no hardcoded colour": a fixed accent is what makes the panel recognisably Usora Dock rather than a generic list. It never overrides a semantic surface, text or border.
3. Geometry is exact. Spacing (4/8/12/16/20/24/32), radii (6/10/14/999) and the type scale (18/13/13/11) come from spec/design-tokens.json verbatim.

Avatars, chip icons, group icons and related-skill icons all paint through six --ud-tile-0…5 gradients, chosen by a stable hash of the skill or group name, so a skill keeps the same colour across scans. They are declared as background shorthands precisely so the high contrast theme can swap a gradient for a flat colour in one place.

High contrast themes are handled explicitly rather than approximated: accents collapse to --vscode-contrastActiveBorder, the gradients are removed and tiles become transparent with a contrast border, tinted chips become transparent with a contrast border, and cards rely on --vscode-contrastBorder. All controls are keyboard reachable with a visible focus ring, arrow keys move through the list, Ctrl/Cmd+K focuses search, and prefers-reduced-motion disables transitions.

What it deliberately does NOT do

• It never executes a SKILL.md, script or command.
• It never writes, deletes, moves or renames a skill.
• It never installs, uninstalls, enables or disables anything.
• It has no marketplace, account, sync, database, MCP or HTTP server.
• It does not create directories. Missing roots are skipped and reported, never created.
• It does not read config.hub_path as the skills location (see Directory discovery).
• Discovering a file is not a statement that any Agent has that skill enabled.

Install

From a local .vsix

bun install
bun run package:vsix

To generate the HTML panel previews and package the VSIX in one step:

bun run package:preview

Then in VS Code:

1. Ctrl+Shift+P → Extensions: Install from VSIX…
2. Pick usora-dock-0.1.2.vsix
3. Reload the window.

Or from the terminal:

code --install-extension usora-dock-0.1.2.vsix

Development (Extension Development Host)

bun install
bun run build

Open this folder in VS Code and press F5 (Run Extension). A second window opens with the extension loaded.

Commands

All commands are read-only.

Settings

Directory discovery

Scanning is intentionally shallow: only the configured roots and their direct children. The home directory, node_modules, build output and .git are never walked recursively. A child directory is only a Skill when its SKILL.md exists; ordinary folders are ignored instead of becoming broken rows.

Global Skills

The default roots are the Agent directories known to npx skills (vercel-labs/skills), plus the layouts documented by the tools themselves. They are best-effort conventions, not a guarantee that a given tool version reads them.

…plus the remaining agents from the npx skills table (~/.augment, ~/.continue, ~/.aider-desk, ~/.kilo, ~/.factory, ~/.bob, ~/.hermes, ~/.forge, ~/.junie, ~/.zencoder, and more). The lists live in one place — src/discovery/agents.ts — and a unit test keeps the package.json defaults in sync with it.

All entries are ordinary settings values. Remove or add entries to match your machine; missing directories are skipped silently.

Workspace Skills

The same registry's project roots, resolved against each workspace folder. Multi-root workspaces are scanned per folder and grouped under Workspace · <folder>. Absolute entries are accepted only when you configure them yourself.

Generic folder names (skills, data/skills, agent/skills) are deliberately not defaults: in an unrelated repository they would match ordinary folders.

Usora Hub

Verified against Usora Foundry plugins/foundry/src/core/storage.ts and core/skills.ts:

• Skills live in the knowledge directory: <knowledgeHome>/skills.
• knowledgeHome is USORA_HOME when set, otherwise ~/.usora.
• config.hub_path moves the host data (activities, sessions, runtime) and deliberately does not move skills. This extension therefore does not read config.json at all — reading hub_path would point at host data and miss every skill.

Resolution order: usoraSkillsExplorer.usoraHome → USORA_HOME → ~/.usora.

Codex system Skills

Codex-managed built-ins are stored under <global Codex root>/.system/<skill>/SKILL.md and are recognized only when .system/.codex-system-skills.marker exists. They are shown under the explicit Codex · .system source label. The marker is a support rule, not a reason to hide diagnostics; a present but unreadable SKILL.md remains visible with its warning.

Hub entries are built from skill.json (name, description, state, revision, updated_at) and enriched from SKILL.md. state is displayed verbatim (DRAFT, EVALUATED, REJECTED, PUBLISHED); it is never translated into "enabled" or "installed". A missing SKILL.md is reported as a warning and never generated.

If no Hub is found, the group says so and tells you where to set the path. Nothing is initialised.

Known limitations

• USORA_HOME is read from the Extension Host process environment, which is inherited from the VS Code launcher. A variable exported only in another shell will not be visible. Use usoraSkillsExplorer.usoraHome in that case.
• ~ expands to os.homedir(). On Windows with a redirected profile, set an explicit path.
• Descriptions come from frontmatter, or fall back to the first heading and paragraph. Nested YAML, anchors and complex structures are intentionally not parsed; such files are still listed, with a warning.
• Very large SKILL.md files above maxMetadataFileSizeKb are listed without a parsed description.
• Symbolic links are not followed by default; enabling the setting can surface duplicate paths for the same physical skill.
• File watching is global for **/SKILL.md and debounced by 500 ms.
• Hub state semantics were verified against Foundry source at implementation time. A future schema change may require an update; unknown fields are ignored rather than guessed.

Requirements

• VS Code ^1.85.0
• Node.js 18+ for building
• Git only if you want the hooks; a checkout without git still builds, tests and packages normally.

Design provenance

Generated brand assets

The current panel references one generated raster mark; the rail footer itself is drawn with HTML/CSS so its text and spacing remain editable:

The existing media/usora-dock-mark.png is used as the Marketplace icon and the in-panel Usora brand mark. The Activity Bar uses the restored monochrome resources/usora-skills.svg variant so VS Code can theme it correctly at small sizes.

Built against the handoff package one directory up:

Two deliberate deviations:

1. The mockups show a green 已安装 (installed) badge on every row. That badge is not reproduced: this extension can read a directory but it cannot know what any Agent has enabled, and the plan explicitly forbids reporting discovery as installation. Usora Hub rows show their real lifecycle state (DRAFT / EVALUATED / REJECTED / PUBLISHED) on a tinted pill instead, and other rows show a warning marker only when their metadata is incomplete. 相关技能 is implemented, but from what is actually verifiable: sibling skills discovered in the same source, not a relationship index this extension has no way to read.
2. The activity bar icon uses currentColor rather than the fixed brand gradient, because a fixed gradient disappears against a light or high-contrast activity bar. Inside the panel, where the background is ours, the gradient is used. The original asset is untouched.

Development

The staged audit and implementation checklist is kept in IMPLEMENTATION_PLAN.md.

Bun is the package manager and the runtime for every script: it installs dependencies, runs TypeScript directly and provides the test runner, so no node, npm, npx or tsx is needed.

bun install         # install devDependencies, write bun.lock, install husky hooks
bun run typecheck   # tsc --noEmit
bun run lint        # oxlint
bun run test        # bun test (runs test/*.test.ts, node:test-compatible)
bun run format      # prettier
bun run check       # typecheck + lint + test
bun run build       # esbuild -> dist/extension.js
bun run watch       # rebuild on change
bun run package:vsix
bun run release       # check, preview, package and publish to the Marketplace

bun.lock is committed; package-lock.json is not used and no longer exists.

To inspect the panel layout without launching VS Code, render it to files and open them in a browser:

bun run preview:panel   # writes out/panel-preview*.html
bun run package:preview # preview first, then package the VSIX

One-click release

The release command uses semantic-release for version calculation, CHANGELOG generation, Git tags and GitHub Releases. It builds the VSIX and attaches it to the GitHub Release, but does not upload the extension to the Visual Studio Marketplace. The pipeline runs typecheck, lint, tests, panel preview generation and VSIX packaging.

Run:

# PowerShell
bun run release       # calculates the next version and creates the GitHub Release

# macOS / Linux
bun run release

Use Conventional Commits so semantic-release can calculate the next version:

fix: correct skill path diagnostics   -> patch
feat: add a source filter             -> minor
feat!: change the extension contract  -> major

The GitHub workflow runs on main, creates the release tag and GitHub Release, and attaches the VSIX. No Marketplace token is required. GITHUB_TOKEN is supplied by GitHub Actions; upload the attached VSIX to the Marketplace manually when you are ready. Use bun run release:dry-run locally to inspect the calculated release without publishing.

Those files are generated from the real renderView() with illustrative fixtures — one per detail tab, plus a dark-theme variant — so a layout regression shows up as a diff there. The fixture injects the vscode-light / vscode-dark body class and the --vscode-* variables the host normally provides, because outside VS Code neither exists.

Husky + lint-staged run Prettier and oxlint on staged files before each commit, and bun run check before each push. The hooks install themselves on bun install and require a git repository (create one with git init if needed).

License

MIT