This skill is distributed with the standalone skilldock plugin, can be used in Codex or Claude, and only opens the local skill management application. Both sides open the same local instance and the same data. In Codex versions that support the native entry point, you can open the full main page from SkillDock in More / Explore and pin it to the sidebar; in Claude, open the local skill manager in the built-in browser panel. The GUI buttons directly call the local service and load the local skill library upon opening. When the user only asks to open the interface, do not install, disable, or remove actual skills on their behalf.
Codex Native Entry Point
Only Codex has this entry point (Claude does not load it). The plugin ships with a local MCP service and the full UI. After a new session/reload, select in More / Explore SkillDock; you can use Pin to sidebar to pin it. The first time it is opened, it automatically prepares the backend, and subsequent times reuse the verified instance. The global page continues to use the saved project; when there is no selection the first time, the user's home directory is used, and the user can switch from the project selector. When the backend is interrupted, the interface reconnects and does not automatically replay write operations. The prototype SkillDock Preview is a different test plugin, and the official entry point needs to be pinned separately; the user's Preview is not automatically uninstalled.
For distribution and lifecycle instructions, see Native Application Integration。
Startup and Opening
From the directory where the actually loaded SKILL.md is located, locate scripts/launch.sh; do not assume the repository checkout or plugin cache path. The launcher searches in a fixed order for local Node.js 22.12+ (Codex workspace, downloaded dedicated version, Homebrew, nvm/fnm/Volta/asdf/mise/nodenv, PATH), saves the selected path for reuse by both entry points and background tasks, and searches again if it becomes invalid; if not found, it displays an installation guide (open the download page or "Detect Again" after installation) and no longer downloads automatically.
/bin/sh "/实际安装位置/skill-manager/scripts/launch.sh" start --project "/用户项目的绝对路径"
Before starting, determine the user's project directory and pass it explicitly with --project ; do not first switch to the download directory or installation directory and then use it as the user's project. When unspecified, use in order SKILLDOCK_PROJECT_DIR, the project saved in the interface, and the calling working directory. The interface's "Switch Project" can save a new scan selection. You can use SKILLDOCK_STATE_DIR to specify a separate application data directory, andPORT to specify the port; by default the data is located in ~/.local/share/skilldock, and the default port is 4771. The launcher copies the source files to the application data directory, installs dependencies according to the lockfile and builds (output is written to the data directory's build.log), and does not write runtime data to the installed plugin cache. The first startup requires the npm registry to be reachable, and subsequent startups reuse the same build.
Codex CLI verifies PATH, the desktop app's built-in CLI, and Codex-managed copies one by one; damaged old wrappers are skipped. The Claude command line takes in order the explicitly specified value, the saved value manually specified by the user, the path provided by the session when opened from Claude, the highest version bundled with the Claude desktop app, the previously automatically selected saved value, PATH, and installations under the user directory; after selection it is saved and the version is verified before use, so it keeps up with Claude upgrades. When specifying SKILLDOCK_CODEX_BIN or SKILLDOCK_CLAUDE_BIN , it must be a valid absolute path. SkillDock's service and the command line it invokes only inherit whitelisted environment variables and do not bring in host session variables. CLI diagnostics are also included in doctor , and for the actual source description see Application Installation Instructions。
When runtime environment discovery fails, first run launch.sh doctor(read-only, does not write any files). If the host provides load_workspace_dependencies, you can read the real Node path it returns and specify it with SKILLDOCK_NODE_BIN ; for a custom Codex application location use SKILLDOCK_CODEX_APP_DIR. In unattended environments or environments without a graphical interface, set SKILLDOCK_NO_DIALOG=1 to turn off the installation guide dialog. Do not modify Codex's signature or the user's shell configuration to bypass loading restrictions. For diagnostics and compatibility boundaries see Runtime environment integration。
Verify the requested directory and final scanned directory printed before and after startup, the directory source, the absolute path of the Codex CLI, and the selected Claude command line when Claude is present on the machine. If the real path differs from the requested path there will be a symbolic link explanation; if the final directory does not match the user's intent, correct --project and reopen, and do not treat HTTP 200 as evidence that the scanned directory is correct.
Read the actual URL returned by the launcher and open it according to the current host:
- Codex: When the host provides
open_in_codex, open the URL with browser target,placement: right; otherwise use the provided browser tool, or give a clickable link. The native global entry has been verified in 26.924.22138; when the host does not show that entry, use this browser path. - Claude: Use the browser tool provided by the host to open the URL in the built-in browser panel (for example, a desktop application's browser panel); when there is no such tool, give a clickable link.
When the tool does not exist, do not pretend that the panel has been opened. Do not rewrite the host's fixed records yourself.
By default, read the machine's known skill roots and available CLI evidence, and do not claim to scan the entire disk. The interface displays the available operations and reasons for each object. Already-running Codex or Claude sessions are not guaranteed to reload configuration immediately; follow the application's feedback to prompt a restart, a new session, or a plugin reload.
Status and stop
/bin/sh "/实际安装位置/skill-manager/scripts/launch.sh" status
/bin/sh "/实际安装位置/skill-manager/scripts/launch.sh" stop
Exit code 3 means the data is already managed by a higher version of SkillDock and this side's SkillDock needs to be updated first: tell the user the prompt from the output verbatim, do not retry, and do not switch to another data directory.
Exit code 4 means a SkillDock lower than 0.10.3 is still installed in some Agent, and 0.11 will not take over the data for now (the old version works as usual, and no data has been changed): tell the user the explanation and handling steps in stderr, and ask whether SkillDock should update with one click the SkillDock in that Agent (Codex or Claude) listed in stderr. After the user agrees, add SKILLDOCK_UPDATE_AGENT=codex or SKILLDOCK_UPDATE_AGENT=claude before the original startup command and run it again (only for the listed Agent); the launcher will update via that Agent's command line, read back, and recheck. If the user does not agree, change nothing, and ask the user to update or uninstall the old SkillDock in the corresponding Agent and then reopen. When both sides are blocked, name only one side at a time; if after updating it is still blocked by the other side, ask the user once more. If the one-click update fails, tell the user the reason in stderr and the manual steps, do not retry repeatedly, do not skip the check, and do not switch to another data directory. On a non-zero exit, stdout has no content.
Startup is a web background service operation, and interrupting the call does not necessarily stop the service that has already been created; first use status to verify the actual result, and when you need to stop the web service run stop. Since 0.4.0, automatic updates are handled by an independent macOS user background task;stop does not turn off automatic updates. When the user asks to stop automatic updates, turn off the schedule on the updates page and read back that the background task has been removed.
The launcher stops only the services it has recorded itself: those confirmed by a health check to match, or (since 0.11.3) those whose process is still running, whose port no longer has a program listening on it, and whose command line is verbatim identical to when the launcher originally started it; do not kill other programs yourself by port or process name. When a port is occupied, a PID cannot be verified, or the CLI is unavailable, keep the actual error and follow Application Notes to troubleshoot. After updating the app source code, start will rebuild and restart this verified instance.
After the user adds the associated plugin to the auto-update schedule, an independent task prepares the new version when the entire batch ends, and the next task uses the new version; the web service does not start when the panel is not opened. A running web service automatically restarts after detecting a new version, and the browser automatically reconnects; the same installation retains its original data directory across versions. If the build fails, the old service is retained; if startup fails, it attempts to restore the old run directory. On failure, check the logs and restart status, and do not delete the data directory or manually alter ownership records to bypass verification. For implementation and verification, see Self-Update and Restart。
When the macOS schedule is first enabled, it registers a LaunchAgent for the current user and exits upon completion; both Codex and the web panel can turn it off. After a restart and login, or resuming from sleep, it performs one catch-up due check. When the background status is abnormal, read the actual registration status and execution records on the update page, and do not treat "schedule enabled" as the task having run. A schedule enabled by an old version is automatically migrated the first time 0.4.0 starts, and the automatic restart after an update also counts; only when the plugin files have been updated but the new version has not yet run do you need to start it manually once. Do not restart on your own when the user or system has disabled background running. For the design, data locations, and verification, see Independent Background Update。
Migrating from an Old Version
The old SkillDock 0.1.0 belongs to testany-eng. When the standalone plugin first takes over the old data, under an explicit request to open the new plugin, execute with the real path of this skill start --project "/用户项目" --migrate-from testany-eng; the launcher only takes over the fixed old identity of the same marketplace and Codex root. It retains the old schedule and history and does not automatically uninstall the entire testany-eng. When old and new skills of the same name coexist, the installation path of the standalone skilldock takes precedence; updating the old toolkit to 2.4.1 removes the old app entry. The testany-eng target of the old schedule is retained, and the new app's self-update must select the skilldock target.
Usage Examples
- "Open the skill management panel" → Launch and open the GUI, leaving the user to choose the target.
- "Set up skill auto-update" → Open the schedule settings on the update page; let the user choose the target, interval, and auto-apply switch. Merely opening the interface does not authorize creating a local schedule.
- "See which skills with the same name this project has" → Use the project directory as the scan root, open the skill library, and filter for duplicate names.
- "SkillDock cannot start" → Read the startup result, service logs, and Application Notes, and handle only this instance.
Maintenance and Completion Criteria
For the requirements, design, interface contract, and implementation progress of cross-Agent (0.11), see PRD、HLD、Interface Contract and Implementation Plan; read the contract before changing cross-version identification, startup handover, or data format. For this round's standalone distribution and project selection rectification, see Seed Feedback Record. When maintaining the source code, read Engineering Design and Test Plan; for requirements or interaction changes, read PRD and Interface Design. See the first-round UAT topic, three languages, sources, and scheduled update changes in Change Baseline. For the latest product boundaries and validation, see Third-Round Rectification Delivery; Sandbox has been removed from the product, and the isolation fixture is for development testing only. This software is licensed under AGPL-3.0-only, and third-party materials retain their own licenses.
Successful startup must have an actual health check and an accessible page; successful operations must be proven by backend read-back. The existence of a cache directory does not equal a valid installation, and a marketplace refresh does not equal a skill/plugin upgrade; protect the system and hosted components of unclear origin. Failures, partial completion, recovery, and user UAT must each be reported truthfully.