Imports skills from a local Codex install into the DSH skill catalog without running them: scans ~/.codex/skills and the plugin cache, registers a skill by reference or as a snapshot copy (a snapshot rewrites the Codex home paths hard-coded in the copied body and keeps the upstream LICENSE/NOTICE), compresses oversized descriptions to a 220-character budget by default, and records every import in an atomic lockfile that is replayed at DSH startup. The same six operations ship as codex_scan, codex_inspect, codex_import, codex_list, codex_remove and codex_doctor tools plus a bridge CLI; zero runtime dependencies, no build step, Node.js 20 or newer.
Install
# from a prebuilt release tarball
dsh plugin --profile web add "https://github.com/DanceElephant/dsh-codex-bridge/releases/download/v0.1.2/dsh-codex-bridge-0.1.2.tgz"
# from GitHub (first run asks for allowBuilds approval — follow the hint, retry)
dsh plugin --profile web add github:DanceElephant/dsh-codex-bridge
Any plugin you install runs third-party code with your own permissions — it can read your files, use your credentials, and reach the network, and tool approvals don’t sandbox it. GitHub-sourced plugins also run build scripts at install time — pnpm blocks those until you allow them, so an install can stop with ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED or ERR_PNPM_IGNORED_BUILDS; dsh prints the exact key to add under allowBuilds in your profile’s pnpm-workspace.yaml, and the install works on the next run. Allowing a build is a trust decision: only install sources you trust, and pin a commit (github:owner/repo#sha).
README
Contents
- What it is
- What it fixes
- How it works
- Install
- Five-minute walkthrough
- Two import modes
- How a description gets down to 220 characters
- The six tools
- CLI
- Layout and lockfile
- Configuration
- Safety boundaries
- Troubleshooting
- Limitations
- Development
- License
What it is
Your Codex skills live in ~/.codex/skills (plus the plugin skills under ~/.codex/plugins/cache). They are invisible to DeepSeek Harness (DSH), which reads its own skill directory. This plugin is the bridge between the two.
Install it once and then, from inside DSH:
- scan, inspect and import those skills — imported ones show up in the DSH skill list and the model loads them on demand, like any native skill;
- descriptions are compressed to fit DSH's prompt budget, so a 900-character skill description does not eat your context every session;
- you can tell when upstream changed or vanished, and undo an import cleanly.
It never executes an imported skill: scripts are listed for your information, bodies are only read and registered.
In one sentence: skills you installed in Codex, without reinstalling them in DSH.
Who it is for
- People who use both Codex and DSH and do not want two copies of the same skill;
- Anyone with a pile of Codex plugin skills (docs, PDF, spreadsheets, presentations, browser automation) they want in DSH;
- People who care about context budget.
Who it is not for
- DSH-only users with no
~/.codexdirectory — scanning simply reports that the root is missing, harmlessly; - Anyone who wants to run the Codex agent itself — this moves skill files, not the Codex runtime.
What it fixes
Codex and DSH skills share nearly the same format: a SKILL.md with YAML frontmatter. Two things still block a straight copy:
| Problem | What happens | What this plugin does |
|---|---|---|
| Descriptions are long | Codex description fields are retrieval-oriented prose, 900–1500 characters in real skills. The skill catalog is injected into every session, so copying them verbatim eats a large slice of the prompt |
Compress to one trigger-style sentence (default ≤ 220 code points), keeping platform and tool names as keywords |
| Paths are hard-coded | Skill bodies often hard-code ${CODEX_HOME:-$HOME/.codex}/skills/<name>/..., so resources break in a new location |
snapshot mode copies the skill and rewrites five path spellings in the copy, keeping upstream LICENSE/NOTICE |
A real compression, from this machine's agent-reach skill (921 characters → 208):
before (921 chars, excerpt):
MUST USE when user wants to 调研/research/搜索/search/查/找/look up anything on the internet
— e.g. 全网调研 X / 帮我调研一下 X / 查一下 X / 搜搜 X / 看看大家怎么评价 X / X 上有什么讨论 …
(another 800-odd characters follow: platform list, URL rules, output format …)
after (208 chars, full output; line breaks are cosmetic):
MUST USE when user wants to 调研/research/搜索/search/查/找/look up anything on the internet
— e.g. 全网调研 X / 帮我调研一下 X / 查一下 X / 搜搜 X / 看看大家怎么评价 X / X 上有什么讨论
/ research this topic。;小红书;B站;bilibili;推特;Twitter;YouTube
Trigger sentences come first (that is what the model matches on), platform keywords last (that is what retrieval matches on).
How it works
flowchart LR
A["~/.codex/skills"] --> S["codex_scan<br/>read-only scan"]
B["~/.codex/plugins/cache"] --> S
S --> I["codex_inspect<br/>what will be injected"]
I --> M{"import mode"}
M -->|reference| R["lockfile .bridge.json<br/>source path only"]
M -->|snapshot| P["targetDir/<name>/<br/>copy + path rewrites"]
R --> L["replay on DSH startup"]
P --> L
L --> K["skills.register()<br/>appears in the skill list"]
Six stages:
- Scan — find importable skills; record hash, file count, script list, raw description length;
- Inspect — parse the frontmatter and show the first 500 characters of the body that will actually be injected;
- Plan —
dryRunby default: a plan, no writes; name conflicts are resolved here; - Compress — fit the description into the budget; idempotent (short enough descriptions pass through unchanged);
- Write — update the lockfile atomically;
snapshotadditionally copies and rewrites paths; - Replay — on every DSH startup the lockfile entries are registered as skills. The description comes from the lockfile (upstream description edits cannot shift an injected catalog), while the body is re-read from disk (upstream body fixes take effect immediately).
Install
The plugin is a DSH bundle: install it into a profile, then restart DSH.
Option 1 — one command (recommended)
dsh plugin add https://github.com/DanceElephant/dsh-codex-bridge/releases/download/v0.1.2/dsh-codex-bridge-0.1.2.tgz
Restart DSH afterwards. This writes the package into the profile's dependencies and dsh.profile.bundles; no manual registration.
Option 2 — plugin market
The plugin has been submitted to the DSH plugin market (entry PR #15734). Once merged, search codex-bridge under the skill category and click install. Before the merge, use option 1.
Option 3 — manual install into a profile
cd /path/to/dsh-codex-bridge
npm pack # produces dsh-codex-bridge-0.1.2.tgz
cd ~/.dsh/profiles/<your profile>
npm i /path/to/dsh-codex-bridge-0.1.2.tgz
If plugins already in the profile have peer conflicts (for example dsh-univer-office and @perrylink/dsh-github disagreeing about @deepseek-ai/dsh-llm), npm i reports ERESOLVE. That is a pre-existing profile problem, unrelated to this plugin (zero dependencies, no peers); add --legacy-peer-deps to get past it.
Then append to that profile's cordis.patch.yml:
- insert:
- id: dsh-codex-bridge
name: dsh-codex-bridge
config: {}
Make sure dsh.profile.bundles in the profile's package.json contains "dsh-codex-bridge", then restart DSH.
CLI only, no bundle
node bin/bridge.mjs scan
Five-minute walkthrough
After installing and restarting, in DSH. Every tool returns { ok, ...fields, data }.
① Scan
codex_scan({ "exclude": ["template-creator"] })
Real output from this machine:
agent-reach standalone 9 files 921 chars
playwright standalone 9 files 209 chars
visualize plugin/visualize 43 files 309 chars
documents plugin/documents 80 files 313 chars
pdf plugin/pdf 4 files 222 chars
9 importable skills
skipped: github MCP_ONLY MCP config only, no skills/
② Inspect — what the model will actually read:
codex_inspect({ "name": "playwright" })
Look at willInject (first 500 body characters) and scriptFiles (scripts that are named but never executed).
③ Plan — nothing is written:
codex_import({ "names": ["playwright"] })
planned[] shows the target name, mode, compressed description and whether it is already imported.
④ Import — explicit confirmation writes:
codex_import({ "names": ["playwright"], "confirm": true, "onConflict": "prefix" })
⑤ Restart DSH — the skill now appears in the skill list with its compressed description.
⑥ Maintenance
codex_list({}) // did upstream change? (re-hashes)
codex_doctor({ "fix": false }) // stale paths / over budget / missing binaries
codex_remove({ "names": ["playwright"], "purge": false })
Two import modes: reference vs snapshot
reference (default) |
snapshot |
|
|---|---|---|
| Where files live | Not copied; the lockfile stores sourcePath |
Copied to ~/.dsh/codex-bridge/<skill-name>/ |
| Upstream edits | Body reflects the new version on next startup | Requires re-import |
| Upstream deleted | Warned and skipped at startup | Copy still works |
| Best for | Most skills (no hard-coded paths) | Bodies containing ${CODEX_HOME:-$HOME/.codex}/skills/<name> and friends |
| Disk use | none | size of the skill dir (skips .git, node_modules, assets/ files >1 MiB) |
snapshot rewrites these five spellings in the copy so they point at the new directory:
${CODEX_HOME:-$HOME/.codex}/skills/<name> $CODEX_HOME/skills/<name>
$HOME/.codex/skills/<name> ~/.codex/skills/<name>
<absolute source directory>
Rewrites only touch text files ≤512 KiB and every replacement is recorded in the lockfile's rewrites, so it is auditable.
How a description gets down to 220 characters
Not a blunt cut — truncating would drop the "when to use me" sentence and break retrieval. lib/describe.mjs:
- Clean: strip code fences, backticks, images, links, URLs, heading marks; squeeze whitespace;
- Keep trigger sentences: sentences containing
use when/must use/使用时机/用于/当…时/适合…场景/triggers onmove to the front; - Reserve keywords: platform words (小红书, B站, GitHub…), backticked identifiers and capitalized product names get at most
min(keyword length, 45% × budget), up to 6; - Fill: spend the rest of the budget on whole sentences, cutting at clause boundaries with
…, joined by;.
Length is measured in Unicode code points; the default cap is 220 (maxDescription). A description that already fits passes through unchanged, so repeated imports are safe.
The six tools
| Tool | Purpose | Parameters | Key returns |
|---|---|---|---|
codex_scan |
Read-only scan | root, include[], exclude[] |
total, items[] (with alreadyImported), problems[] |
codex_inspect |
Inspect one skill | name or path |
willInject (500 chars), scriptFiles[], importable |
codex_import |
Import and record | names[], mode, onConflict, dryRun, confirm |
planned[], applied[], failed[] |
codex_list |
Imported entries + upstream diff | none | items[] (with upstreamChanged, upstreamMissing) |
codex_remove |
Unregister | names[], purge |
removed[], purged[] |
codex_doctor |
Health check | root, fix |
missingBinaries[], stalePaths[], overBudget[], healthy |
Details:
mode:reference(default) orsnapshot;onConflict:prefix(default — a clash becomescodex-<name>, thencodex-<name>-2, …),skip,overwrite;dryRundefaults totrue: nothing is written withoutconfirm: true;purge: truedeletes only snapshot copies insidetargetDir; areferencesource directory is never deleted.
CLI
bridge scan [--root DIR] [--target DIR] [--json]
bridge inspect <name|path> [--root DIR] [--json]
bridge import <name...> [--mode reference|snapshot] [--on-conflict prefix|skip|overwrite]
[--dry-run] [--yes] [--root DIR] [--target DIR] [--json]
bridge list [--target DIR] [--json]
bridge remove <name...> [--purge] [--target DIR] [--json]
bridge doctor [--fix] [--root DIR] [--target DIR] [--json]
importis a dry run unless you pass--yes;--jsonprints one line of JSON;- exit codes:
0success ·1usage error ·2execution or partial failure.
Layout and lockfile
~/.codex/ # codexRoot: read-only, never written
├── skills/<name>/SKILL.md # standalone skills
└── plugins/cache/<market>/<plugin>/<ver>/ # plugin skills
├── .codex-plugin/plugin.json
└── skills/<name>/SKILL.md
~/.dsh/codex-bridge/ # targetDir: the only writable location
├── .bridge.json # lockfile (version 1, mode 0600)
└── <skill-name>/ # snapshot copies only
Per-entry lockfile fields: name / sourceName, sourcePath / sourceKind / sourceVersion, hash (sha256 of the upstream directory, used to detect drift), mode, description / longDescription, files, importedAt, and optionally pluginName and rewrites.
Writes are atomic: temp file 0600 → fsync → rename. A batch that fails halfway leaves earlier entries valid.
Configuration
- insert:
- id: dsh-codex-bridge
name: dsh-codex-bridge
config:
maxDescription: 220
| Field | Default | Meaning |
|---|---|---|
codexRoot |
~/.codex |
Read-only Codex root |
targetDir |
~/.dsh/codex-bridge |
Lockfile and snapshot location |
maxDescription |
220 |
Description budget injected into DSH (Unicode code points) |
autoReplay |
true |
Replay lockfile skills on startup. false registers only the tools and never injects skills (the lockfile is left untouched) |
An empty config is fine, and a broken config cannot stop DSH from booting: each phase is wrapped, failures only log a [codex-bridge] warning.
Safety boundaries
codexRootis read-only; the only writable location istargetDir, and escapes raisePATH_ESCAPE(including symlink escapes);- no imported code is ever executed —
scriptFilesis informational,doctoronly checks whether those binaries are on PATH; - no network access, zero runtime dependencies, plain ESM, no build step;
- every delete (
remove --purge,overwritecleanup,doctor --fix) verifies the target is insidetargetDirfirst; snapshotpreserves upstreamLICENSE/NOTICEand records every rewrite.
Troubleshooting
Scan returns zero / "codexRoot does not exist" — pass codexRoot or --root if Codex lives elsewhere.
A plugin I installed does not show up — plugins with only MCP configuration produce no skill entries. They are reported in problems[] as MCP_ONLY; a plugin with a manifest but no skills/ is NO_SKILLS. "Nothing to import" and "plugin missing" are deliberately different answers.
Imported, but no skill in DSH — replay happens at startup: restart DSH. If it is still absent, run codex_doctor and check replayable (over-budget descriptions or a deleted SKILL.md cause a skip; the log carries a [codex-bridge] warning).
The skill name changed — the default conflict policy is prefix, so the new name is codex-<original>. Use onConflict: "overwrite" or remove the old entry first.
The description got shorter / ends with … — that is the compression. Raise maxDescription if you want more, at the cost of a longer prompt every session.
Upstream changed — reference mode: the body follows upstream automatically, the description keeps its imported value (re-import to refresh it). snapshot mode: re-import.
doctor reports missing binaries — the skill names tools such as playwright-cli, pandoc, ffmpeg, magick, pdftotext, jq, rg, python3, node, npx, git that are not on PATH. The plugin only reports; it never installs anything.
Limitations
- Only the
SKILL.mdlayer is moved. Codex-specificagents/openai.yamland.app.jsonare not translated; - name conflicts are judged on
namealone; same-named skills from two plugins are handled byonConflict; snapshotrewrites only the five path spellings above; other hard-coded absolute paths are left alone;- compression is heuristic: a very long description with no trigger sentence is cut at a clause boundary;
- with several plugin versions present, the highest version wins (
1.10.0 > 1.2.3); hash-like directories sort last;
Development
npm test # node:test, 74 cases (1 real-data case skipped unless CODEX_BRIDGE_REAL=1)
npm run coverage:check # lib/ line coverage gate ≥ 85% (currently 91.79%)
npm run smoke # lifecycle smoke: idempotent re-apply, clean dispose
CI runs on Node 20 / 22 / 24; the coverage assertion runs on Node 24. Modules:
lib/index.mjs # bundle entry: register tools, replay, dispose
lib/tools.mjs # the six tool definitions and argument validation
lib/discover.mjs # scanning: two sources, version pick, hash, skip reasons
lib/importer.mjs # importing: naming/conflicts, reference vs snapshot, lock entries
lib/describe.mjs # description compression
lib/lockfile.mjs # lockfile reads and atomic writes
lib/doctor.mjs # health check
lib/frontmatter.mjs lib/manifest.mjs lib/paths.mjs # parsing, manifests, path safety
License
Related: DeepSeek Harness · DSH plugin market (repo) · Codex
Links
More in this category
tw93/Mole#mole★ 75286
Official agent skill for the open-source Mole CLI (mo), a disk cleanup tool for macOS and Windows: read disk usage, preview and run cleanup, inspect installed apps, and read system health and cleanup history from Mole's JSON output. It previews with --dry-run and asks before removing anything, and leaves app uninstalls and privileged steps to the user's own terminal. The plugin ships only the skill; the CLI is installed separately.
zhu1090093659/dsh-web#packages/dsh-skill-explorer★ 10458
Skill center for the dsh web GUI: browse all loaded skills grouped by source, enable or disable model invocation, create new skills, and delete into a recoverable trash.
QingYunA/answer-me-with-html★ 6365
Answers a question with a one-page visual HTML explainer: the model writes a short Markdown draft and the bundled `am` CLI builds the page, with flow, sequence, tree, timeline and ER diagrams, tables and callouts.
iflytek/skillhub#dsh★ 5432
Browse and search a SkillHub registry and manage local skill installation, updates, and removal inside DeepSeek Harness. Targets DSH 0.2.0-rc.2 and 0.2.1-rc.2; not yet compatible with 0.2.1-rc.3.
hyhmrright/brooks-lint★ 1578
Provides six code quality skills for code review, architecture audits, technical debt, test quality, health dashboards, and remediation.
GanyuanRan/Aegis★ 1443
Software-engineering method pack for coding agents, with skills for baseline-first planning, systematic debugging, prompt hygiene, verification before completion, and repair/retirement tracking.
Community comments
Comments are public GitHub Discussions. Loading them connects to GitHub and Giscus; a GitHub account is required to post.