Skip to content
Back to search

dsh-skill-forge

Import AI skills written for other agents (Claude Code, Cursor, Codex, plain Markdown) into DeepSeek Harness, and publish them as native DSH skills.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/frederickimanuels--dsh-skill-forge/badge.svg)](/listings/frederickimanuels--dsh-skill-forge)

HTML

<a href="/listings/frederickimanuels--dsh-skill-forge"><img src="/api/listings/frederickimanuels--dsh-skill-forge/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

dsh plugin --profile web add @frederickimanuels/dsh-skill-forge

Until the package is published, the same command works against the repository:

dsh plugin --profile web add "git+https://github.com/frederickimanuels/dsh-skill-forge.git"

or from a local checkout, while you are iterating on it:

dsh plugin --profile web add "file:$PWD"

The package has no build step — the published files are the source — so a git install needs no `prepare` script and no pnpm build allowance.

Either way the profile stores the package under its scoped name, so the bundle row in your composed config reads `@frederickimanuels/dsh-skill-forge`.

Verify the layer resolved:

dsh --profile web --dump-config | grep -A2 skill-forge

Then restart the web host once so it loads the new bundle, and open **Skills** in the sidebar.

Compatibility

`engines.dsh` declares the harness releases this bundle supports, and the harness reads it before it imports a line of plugin code:

"engines": { "node": ">=20", "dsh": ">=0.2.1-rc.2 <0.4.0-0" }

Installation and profile startup refuse a bundle whose range the running DSH does not satisfy. The range must sit at the **root** `engines` object — a nested `dsh.engines` block is read by nothing, and the check silently falls back to the `@deepseek-ai/dsh*` peer ranges instead.

The sidebar icon comes from `package.json` `icon`, which the loader resolves as a relative path inside the package (SVG, PNG, JPEG or WebP, at most 256 KiB).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 364 lines
  1. <img src="docs/icon.svg" width="72" height="72" align="left" alt="Skill Forge">
  2. # dsh-skill-forge
  3. Import AI skills written for *other* agents into [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
  4. and publish them as native DSH skills.
  5. [![npm](https://img.shields.io/npm/v/@frederickimanuels/dsh-skill-forge?style=flat-square&label=npm&color=cb3837)](https://www.npmjs.com/package/@frederickimanuels/dsh-skill-forge)
  6. [![DSH plugin](https://img.shields.io/badge/DSH-plugin-0e7490.svg?style=flat-square)](https://github.com/topics/dsh-plugin)
  7. [![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)
  8. [![tests](https://img.shields.io/badge/tests-126%20passing-brightgreen.svg?style=flat-square)](#tests)
  9. <br clear="left">
  10. Every agent ecosystem invented its own skill format. Claude Code has `SKILL.md` plus
  11. slash commands. Cursor has `.cursor/rules/*.mdc`. Codex has `AGENTS.md`. Half the
  12. ecosystem ships bare Markdown with no frontmatter at all. None of it loads in DSH,
  13. which wants a kebab-case `name`, a non-empty `description`, invocation flags and a
  14. resource base.
  15. `dsh-skill-forge` is a DSH plugin that reads all of those, adapts them, and
  16. registers them as first-class skills — no rewriting your files, no fork of the
  17. skill, no copy step required.
  18. ```
  19. $ dsh-skill-forge scan .
  20. agents repository instructions user-only repo-instructions:AGENTS.md
  21. stageshow Agent Skills bundle model agent-skills:stageshow/SKILL.md
  22. 2 skills would be published.
  23. ```
  24. <img src="docs/skills-page.png" alt="The Skills page: import card, filter chips, and a dense list of 502 forged skills" width="820">
  25. ## Install
  26. ```bash
  27. dsh plugin --profile web add @frederickimanuels/dsh-skill-forge
  28. ```
  29. Until the package is published, the same command works against the repository:
  30. ```bash
  31. dsh plugin --profile web add "git+https://github.com/frederickimanuels/dsh-skill-forge.git"
  32. ```
  33. or from a local checkout, while you are iterating on it:
  34. ```bash
  35. dsh plugin --profile web add "file:$PWD"
  36. ```
  37. The package has no build step — the published files are the source — so a git install
  38. needs no `prepare` script and no pnpm build allowance.
  39. Either way the profile stores the package under its scoped name, so the bundle row
  40. in your composed config reads `@frederickimanuels/dsh-skill-forge`.
  41. Verify the layer resolved:
  42. ```bash
  43. dsh --profile web --dump-config | grep -A2 skill-forge
  44. ```
  45. Then restart the web host once so it loads the new bundle, and open **Skills** in the
  46. sidebar.
  47. ### Compatibility
  48. `engines.dsh` declares the harness releases this bundle supports, and the harness
  49. reads it before it imports a line of plugin code:
  50. ```json
  51. "engines": { "node": ">=20", "dsh": ">=0.2.1-rc.2 <0.4.0-0" }
  52. ```
  53. Installation and profile startup refuse a bundle whose range the running DSH does not
  54. satisfy. The range must sit at the **root** `engines` object — a nested
  55. `dsh.engines` block is read by nothing, and the check silently falls back to the
  56. `@deepseek-ai/dsh*` peer ranges instead.
  57. The sidebar icon comes from `package.json` `icon`, which the loader resolves as a
  58. relative path inside the package (SVG, PNG, JPEG or WebP, at most 256 KiB).
  59. ## What it understands
  60. | Dialect | What it looks like | Invocation |
  61. | --- | --- | --- |
  62. | **Agent Skills bundle** | `<dir>/SKILL.md` with `name` + `description` ([spec](https://agentskills.io)) | model + user |
  63. | **Claude Code skill** | `SKILL.md` using Claude-only keys (`allowed-tools`, `argument-hint`, …) | per `disable-model-invocation` |
  64. | **Claude Code command** | `.claude/commands/*.md` | per `disable-model-invocation` |
  65. | **Single-file skill** | any `.md` with YAML frontmatter | model + user |
  66. | **Cursor rule** | `.cursor/rules/*.mdc` (`description`, `globs`, `alwaysApply`) | per `alwaysApply` |
  67. | **Legacy Cursor rules** | `.cursorrules` | model + user |
  68. | **Repository instructions** | `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `CODEX.md`, `.github/copilot-instructions.md` | user-only |
  69. | **Loose Markdown** | prose files, opt-in via `includeLoose` | model + user |
  70. Repository instructions default to **user-invocable only**. An `AGENTS.md` describes
  71. a whole repository; making it model-invocable would let it win unrelated requests.
  72. It stays reachable by name, and the file's own frontmatter can override that.
  73. A directory containing `SKILL.md` is treated as a bundle: its `references/`,
  74. `scripts/`, `assets/`, `examples/`, `templates/` and `resources/` ship as the
  75. skill's resources, and the scan does not descend into it — sibling Markdown files
  76. belong to the skill, not to the catalog.
  77. ## What "adapt" means
  78. The plugin never modifies your files. It rewrites the content it publishes:
  79. - `!`command`` (Claude's dynamic context injection) becomes "the output of the
  80. command `command`". DSH does not run it for you, so the instruction stays actionable
  81. instead of turning into punctuation the model cannot interpret.
  82. - `@path/to/file` references become "the file `path/to/file`" so the model is not
  83. left looking for a mention syntax DSH does not have.
  84. - `$ARGUMENTS`, `$1` … `$9` become "the user's request".
  85. - `allowed-tools` is translated to DSH tool names where a mapping exists
  86. (`Read` → `read`, `WebFetch` → `web_fetch`, `Task` → `subagent`, …) and reported
  87. as an unmapped grant where it does not. Nothing is enforced or hidden — the grant
  88. is advisory text in the skill, exactly as it was in the source format.
  89. - A short preamble records where the skill came from, what it was adapted from, and
  90. what was rewritten.
  91. Skills missing a `description` get one derived from the first real paragraph of the
  92. body (headings are skipped — a title describes the file, not the task). Missing
  93. names are derived from the directory or file name and slugified to the harness
  94. grammar. A bad skill is adapted, not rejected, unless it cannot be named at all.
  95. ## Configuration
  96. All keys are optional; the defaults are what most people want.
  97. ```yaml
  98. - id: skill-forge
  99. name: '@frederickimanuels/dsh-skill-forge'
  100. config:
  101. providerName: skill-forge # provider name on ctx.skills
  102. roots: # extra directories to scan
  103. - ~/.dsh/skill-forge
  104. autoDiscover: true # also read .claude/, .cursor/, AGENTS.md … per project
  105. includeLoose: false # import Markdown with no frontmatter
  106. depth: 3 # directory depth per root
  107. maxFiles: 2000 # total file budget; warns when exhausted
  108. exclude: [] # extra directory names to skip (additive)
  109. deny: [] # skill names to refuse
  110. rankBoost: 0 # add to every rank; negative outranks host skills
  111. includeCommandArgumentHint: true
  112. watch: true # rescan when files change
  113. logAdaptations: true # log each skill every time the catalog is rebuilt
  114. store: ~/.dsh/skill-forge # where the Skills page imports into
  115. ui: true # serve the Skills page and its bridge
  116. ```
  117. With `autoDiscover`, each project you open contributes whatever it already has under
  118. `.claude/skills`, `.claude/commands`, `.agents/skills`, `.cursor/rules`,
  119. `.cursorrules`, `AGENTS.md`, `CLAUDE.md` and `.github/copilot-instructions.md`.
  120. ### Rank: why forged skills never shadow yours
  121. The skill registry sorts candidates by ascending rank and keeps the first, so a
  122. *lower* number wins. The bundled filesystem provider uses `100` (project skills)
  123. through `600` (bundled skills). Forged skills start at `620`, so importing a
  124. `pdf-tools` skill never displaces a `pdf-tools` you wrote yourself. Set
  125. `rankBoost: -100` if you explicitly want an import to win.
  126. ## The Skills page
  127. With the web profile there is a **Skills** entry in the sidebar — and the same panel
  128. at **Settings → Skills** — that does what the CLI does without a terminal:
  129. - lists every skill in the store as a dense row: name, dialect, whether the model
  130. may invoke it, and a two-line description — a few hundred skills stay scannable;
  131. - filters that list by name or description and by invocation (all / model / user-only),
  132. with a live `shown of total` count;
  133. - imports a local path or a git URL, with a **Preview** button that shows what the
  134. source would contribute before anything is copied;
  135. - removes a skill from the row itself — the remove glyph appears on hover or focus,
  136. then asks for a second click before anything is deleted.
  137. The page owns its scroll container: `.sf-page` is a `flex: 1 1 auto` column with
  138. `min-height: 0` and `.sf-pageScroll` below it is the only `overflow: auto` box. Nothing
  139. above it in the frame scrolls — the layout shell clips overflow on purpose — so a page
  140. that forgets a scroller is simply cut off at the viewport. Keep those two rules if you
  141. restyle it.
  142. The sidebar entry and the settings section are two registrations over one component,
  143. so they never disagree about what is in the store. A destination in the DSH sidebar
  144. is exactly two slot registrations sharing one id: a `sidebar.panellist` row (the
  145. shell paints the button, label and active state; the plugin supplies only the glyph)
  146. and a `main` entry keyed by that same id, which the frame renders when the row is
  147. clicked. The glyph is drawn inline because `client/index.js` may require nothing but
  148. React.
  149. The page is a client module (`client/index.js`, declared as `dsh.client` in
  150. `package.json`) and it never touches the filesystem: it calls five JSON routes under
  151. `api/dsh-skill-forge` (`state`, `preview`, `import`, `remove`, `store`) that the host
  152. half registers. A request from another origin is refused. Because the page and the
  153. CLI share `src/store.js`, both do exactly the same thing to the store — that is also
  154. why `--force` exists only on the CLI, where a half-finished import is easy to see.
  155. Set `ui: false` in the config to serve no page and no routes, for a profile with no
  156. web server or one where you would rather not expose them.
  157. ## CLI
  158. ```bash
  159. dsh-skill-forge scan [paths...] # what would be published, from anywhere
  160. dsh-skill-forge import <source> # copy a directory or git repo into the store
  161. dsh-skill-forge list # what is in the store
  162. dsh-skill-forge remove <name> # delete one skill from the store
  163. dsh-skill-forge doctor # store, ranks, and what this project offers
  164. ```
  165. The commands above are the binary the profile installs (`dsh-skill-forge`, from the
  166. package's `bin` field). From a checkout without a global install, use
  167. `node bin/forge.js scan …` instead.
  168. `import` accepts a local path or a git URL and copies the *whole bundle*, so
  169. `references/` and `scripts/` keep working. It never overwrites without `--force`, and
  170. `--dry-run` shows the plan first.
  171. `scan` and `list` describe the same corpus and therefore agree line for line,
  172. including the `model`/`user-only` column — that column is read from the adapted
  173. skill, not guessed from the dialect. Both stop at a skill budget (2000 by default):
  174. `scan` says so on stderr, and `import` refuses a source larger than the budget
  175. rather than copying a prefix that would look complete.
  176. ```bash
  177. dsh-skill-forge import https://github.com/benjitaylor/skills.git
  178. ```
  179. ### The first example: benjitaylor/skills
  180. ```bash
  181. git clone --depth 1 https://github.com/benjitaylor/skills.git /tmp/bt-skills
  182. dsh-skill-forge scan /tmp/bt-skills
  183. dsh-skill-forge import /tmp/bt-skills
  184. ```
  185. ```
  186. agents repository instructions user-only repo-instructions:AGENTS.md
  187. stageshow Agent Skills bundle model agent-skills:stageshow/SKILL.md
  188. ```
  189. `stageshow` is already standards-compliant, so it imports unchanged and its 15
  190. `references/*.md` files and `scripts/*.mjs` stay addressable through the skill's
  191. resource base. The repository's `AGENTS.md` — which no other agent would present to
  192. the model as anything addressable — becomes a user-invocable skill.
  193. The repo's `CLAUDE.md` is not imported: it contains exactly one line, `@AGENTS.md`,
  194. which is a redirect rather than instructions. Publishing it would put a catalog entry
  195. whose entire body is a file path next to the real instructions it points at, so the
  196. redirect is reported and skipped.
  197. ## Design notes
  198. **No runtime dependencies.** The plugin imports only packages the harness already
  199. provides (`@deepseek-ai/cordis`, `@deepseek-ai/schemastery`) and Node built-ins. YAML
  200. frontmatter is parsed by a small purpose-built parser in `src/frontmatter.js`; a
  201. skill whose frontmatter it cannot parse still imports (the parse error is reported
  202. in the skill's preamble) rather than disappearing.
  203. **No bundler, no build step.** The published files are the source: `package.json`
  204. points `main` at `src/index.js`, plain ESM, so a profile loads it straight from
  205. `node_modules`. The bundle descriptor is `dsh/cordis.patch.yml`. The browser half is
  206. hand-written CJS-in-a-factory (`window.__ModuleLoader__.load`) that requires only
  207. `react` from the modules the harness already seeds, and it builds its DOM with
  208. `React.createElement` rather than JSX — a transform step would buy nothing but a
  209. toolchain.
  210. **Failures are local.** A missing root, an unreadable file, a duplicate provider
  211. name or a skill that cannot be named produces a warning and skips that item. Nothing
  212. in this plugin can take a profile down.
  213. **Live catalog.** The provider watches every configured root with `fs.watch` and
  214. invalidates the registry cache when a file changes, so an edit or a `forge import`
  215. shows up without restarting the host. A root that does not exist yet is watched
  216. through its nearest existing ancestor and upgraded to a recursive watcher the moment
  217. it appears — which is what makes the normal first-run sequence (start the host, then
  218. import skills) work without a restart.
  219. ## Permissions and trust
  220. - **No network access.** The plugin never calls out. `import` runs `git clone` and
  221. `cp` against the source you name; nothing else leaves the machine.
  222. - **No skill scripts are executed.** Importing copies files into the store. A skill's
  223. `scripts/` directory is published as a resource, and the model only runs something
  224. from it if you ask it to.
  225. - **Local HTTP routes.** With `ui: true` the host half serves five JSON routes under
  226. `/api/dsh-skill-forge` (`state`, `preview`, `import`, `remove`, `store`) on the same
  227. origin as the DSH web server, behind the same authentication. A request from another
  228. origin is refused. Set `ui: false` to register no routes at all.
  229. - **Writes only inside the store.** The default store is `~/.dsh/skill-forge`.
  230. `remove` deletes a directory below it; nothing outside it is touched.
  231. - **No runtime dependencies.** No transitive supply chain: only the harness packages
  232. and Node built-ins are imported.
  233. ## Publishing
  234. This package is an npm-installable DSH **bundle**: `package.json` declares
  235. `dsh.bundle.patch` and the patch file names the plugin rows a profile composes.
  236. That is what `dsh plugin add` installs and what the Plugin Hub indexes.
  237. To cut a release:
  238. ```bash
  239. npm pack --dry-run # what ships: 20 files, no build output needed
  240. npm login # if you are not authenticated yet
  241. npm publish --access public # scoped, so --access public is required
  242. git tag v0.1.0 && git push origin master --tags
  243. ```
  244. If `npm config get registry` points at a mirror, pass the public registry
  245. explicitly or the upload lands somewhere users cannot install from:
  246. ```bash
  247. npm publish --access public --registry=https://registry.npmjs.org
  248. ```
  249. Users then install with `dsh plugin --profile web add @frederickimanuels/dsh-skill-forge`.
  250. **Discovery.** Three things get a plugin into the catalog, and the first one is the
  251. only one that cannot be skipped:
  252. 1. The repository carries the `dsh-plugin` GitHub topic. New repositories are found
  253. by topic only.
  254. 2. `repository` in `package.json` points at that same `owner/repo`. If it points
  255. somewhere else the npm package cannot be bound to the entry and the plugin stays
  256. GitHub-install-only.
  257. 3. The package is published to npm. The **in-app** Settings → Plugin Hub market
  258. only lists one-step npm installs, so a git-only plugin is indexed on
  259. [dsh-plugin.org](https://dsh-plugin.org) but never appears inside DSH.
  260. The catalog is rebuilt daily from the topic, and
  261. [an issue on the hub repo](https://github.com/dshplugin/dsh-plugin-hub/issues/new)
  262. with the *Plugin submission* template gets a human to look at a new entry sooner.
  263. ## Developing
  264. `dsh plugin add "file:…"` installs a **pnpm snapshot**, not a symlink: edits to this
  265. checkout do not reach a running profile until you re-run the `add` command. The
  266. browser half is read once at host boot, so a change under `client/` also needs the
  267. restart below; the host half is re-read on reload. From a checkout that is:
  268. ```bash
  269. dsh plugin --profile web add "file:$PWD" # refresh the snapshot
  270. systemctl restart dsh-web # restart the host to load it
  271. ```
  272. ## Tests
  273. ```bash
  274. npm test
  275. ```
  276. 126 tests cover the frontmatter parser, dialect detection, discovery (symlink loops,
  277. excludes, bundle non-descent, redirect files), adaptation, tool-grant rewriting, the
  278. provider's cache, rehydration and live-refresh watchers, the plugin mounted into a
  279. real `SkillRegistry`, the CLI, the shared store module, the settings bridge routes
  280. (including the cross-site refusal), and the client manifest.
  281. ## License
  282. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.