toolkit-foundry
Use when creating a new skill for jabworks/agentic-toolkit, registering it, or shipping the generated trees — "scaffold a new skill", "register this skill", "sync dist", "bump the toolkit version" — plus changes to the @jabworks/condux npm package. Not for adapting a generic skill to the jabworks stack (adapting-skills), nor for reviewing a SKILL.md's content and trigger wording (toolkit-skill-standards).
- License 许可
- MIT
- 最近更新
- 2026-11-03
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- toolkit-foundry
- description
- Use when creating a new skill for jabworks/agentic-toolkit, registering it, or shipping the generated trees — "scaffold a new skill", "register this skill", "sync dist", "bump the toolkit version" — plus changes to the @jabworks/condux npm package. Not for adapting a generic skill to the jabworks stack (adapting-skills), nor for reviewing a SKILL.md's content and trigger wording (toolkit-skill-standards).
03 SKILL.md 正文
Toolkit Foundry
Purpose
Create and maintain skills in jabworks/agentic-toolkit. Covers scaffolding, marketplace registration, generation of the dist trees, the npm package, and publishing.
When to Use
- Adding a new skill to the toolkit
- Updating an existing skill and regenerating the dist trees
- Registering or modifying a marketplace entry
- Changing
packages/condux-opencode/(the@jabworks/conduxnpm plugin) - Bumping the toolkit version
Skill Structure
Source tree (editable):
skills/<name>/
SKILL.md # Required — agent instruction file
README.md # Optional — human docs
references/ # Optional — templates, checklists
<file>.md
package.json # Only if references/ ships .js — see "CommonJS scripts"
One source, four generated distributions — scripts/sync.sh produces all of them:
| Generated tree | Channel | Layout |
|---|---|---|
dist/plugins/<name>/skills/<name>/ |
/plugin install (marketplace) |
mirrors skills/<name>/ byte-for-byte |
dist/opencode/skills/<name>/ |
OpenCode | same files, but SKILL.md has when_to_use folded into description |
dist/cursor/skills/<name>/ |
Cursor (2.4+) | the same fold, emitted to its own tree by scripts/build-cursor.mjs |
packages/condux-opencode/agents/ |
@jabworks/condux on npm |
translated from skills/subagent-execution/agents/*.md |
packages/condux-opencode/skills/ |
@jabworks/condux on npm |
the 13 condux skills, byte-identical to their dist/opencode/skills/ form |
npx skills add is the remaining channel and needs no generation — it installs from
top-level skills/ directly and ignores everything above.
Every skills tree is flat — one dir per skill, no bundle nesting. A
bundle-member skill mirrors to dist/plugins/<bundle>/skills/<name>/, the same
depth as a standalone plugin's own skill. This changed on 2026-08-14 with Agent
Plugins conformance (docket #29): the spec discovers skills only as immediate
children of skills/, never recursively, so the old
dist/plugins/<bundle>/skills/<bundle>/<name>/ nesting hid every bundle member
from spec-conformant clients. tests/agent-plugins.test.mjs now pins depth one.
The OpenCode and Cursor trees were always flat, and carry no manifests.
Never edit a generated tree directly. Edit skills/, then sync.
CommonJS scripts under references/
The root package.json must NOT carry "type": "module" — it would reinterpret
every references/*.js reference script as ESM and break it. Skills that ship
such scripts also self-protect with their own references/package.json:
{ "type": "commonjs" }
discovery, plan-review, and spec-browser carry one (f1e4b53). Add it to any
new skill whose references/ contains .js. CI syntax-checks every one with
node --check.
Creating a New Skill
1. Scaffold
mkdir -p skills/<name>/references
mkdir -p dist/plugins/<name>/.codex-plugin
mkdir -p dist/plugins/<name>/.claude-plugin
The dist skill tree is not in that list on purpose — sync.sh creates it. It
used to be listed, and creating it by hand was load-bearing: rsync cannot make
nested parents, so a new plugin whose tree was missing failed the copy while
sync still printed 0 failed (docket #31).
2. Write SKILL.md
Required frontmatter:
---
name: <name>
description: Use when [triggering conditions only — no workflow summary]
---
name: kebab-case, letters/numbers/hyphens onlydescription: third-person, max ~500 chars, starts with "Use when..."- Frontmatter total ≤ 1024 chars
3. Write plugin manifests
Both agents read from the same plugin root (dist/plugins/<name>/) but look in different subdirectories.
Codex — dist/plugins/<name>/.codex-plugin/plugin.json:
{
"name": "<name>",
"version": "1.0.0",
"description": "<short description>",
"author": { "name": "jabworks" },
"repository": "https://github.com/jabworks/agentic-toolkit",
"license": "MIT",
"keywords": ["keyword1", "keyword2"],
"skills": "./skills/<name>",
"interface": {
"displayName": "<Display Name>",
"shortDescription": "<one line>",
"longDescription": "<two sentences>",
"developerName": "jabworks",
"category": "Productivity",
"capabilities": ["Skills"],
"defaultPrompt": ["<prompt 1>", "<prompt 2>"]
}
}
Claude Code — dist/plugins/<name>/.claude-plugin/plugin.json: same structure minus interface — that field is codex-manifest-only (since 2026-07-29; manifest-parity fails if the Claude manifest carries it). description may carry the platform prefix ("Claude Code skill for..."), while name/version/skills must match the Codex manifest exactly (enforced by tests/manifest-parity.test.mjs).
The skills path is relative to the plugin root and must start with ./.
4. Declare in composition.json
composition.json (repo root) is the source of truth for what every plugin is
made of. Register the skill there — never hand-edit
.claude-plugin/marketplace.json or the catalog tables in README.md /
CLAUDE.md; sync generates all of them from the declaration
(scripts/generate-catalogs.mjs).
- Standalone plugin: add a
plugins.<name>entry withmarketplace.description(the marketplace text — deliberately independent of the SKILL.md description, a ratified divergence). - Bundle member: add the skill name to the bundle's
skillsarray. - Either way: add a catalog row —
catalogs.readme-skills(or the bundle's block) and, for a new plugin, acatalogs.claude-md-skillsrow. A plugin with no catalog row fails validation before anything is written. - A plugin-level dir loaded from the plugin root (like condux
agents//hooks/or docketserver/) is onepluginDirsentry — data, not a new sync.sh case.
5. Sync the generated trees
bash scripts/sync.sh <name>
The script copies every pair composition.json declares for the skill —
bundle membership, standalone target, and any plugin-level dirs — then
regenerates marketplace.json and the doc catalog blocks. Run without
arguments to sync everything. A skill missing from the declaration is a hard
error, so step 4 must land first.
Either way it then runs both variant builds. node scripts/build-opencode.mjs
regenerates all of dist/opencode/skills/, packages/condux-opencode/agents/,
and packages/condux-opencode/skills/ from scratch (the last two are rm -rf'd
first); node scripts/build-cursor.mjs regenerates dist/cursor/skills/ the same
way, importing the fold transform from the OpenCode script rather than duplicating
it. One sync.sh covers every generated tree, so never invoke the pieces
separately expecting different results, and never hand-edit any of the four.
A brand-new skill that step 4 has not declared fails the sync outright (the
old behavior — a silent SKIP — is exactly the quiet failure the declaration
replaced). Neither variant build has such a gate — both pick up every dir under
skills/ unconditionally.
6. Verify
node --test
Runs the invariant suite. What each file guards:
| Test | Guards |
|---|---|
dist-mirror |
dist/plugins/ skill trees match skills/ byte-for-byte |
opencode-dist |
dist/opencode/skills/ + packages/condux-opencode/agents/ match the build script's output; merged descriptions within OpenCode's 1024-char cap; the plugin loads and never clobbers user-defined agents |
cursor-dist |
dist/cursor/skills/ matches build-cursor.mjs output; no orphaned dirs; when_to_use never survives; frontmatter name == folder (Cursor requires it); merged descriptions ≤ 1024 chars |
agent-plugins |
each plugin's root plugin.json matches the generator and stays inside the spec's closed schema; every skill sits at skills/ depth one; docket's spec mcp.json keeps the spec dialect |
composition |
every pair composition.json declares mirrors byte-for-byte; nothing undeclared in any dist/plugins/ root; marketplace.json + doc catalog blocks match the generator |
skill-invariants |
frontmatter budgets, kebab-case name == dir, marketplace/plugin paths resolve, plan-review no-egress |
plugin-manifests |
plugin.json / marketplace.json validity, ./-prefixed paths |
manifest-parity |
the .claude-plugin/.codex-plugin pair agrees on name/version/skills; interface codex-only (absent from the Claude manifest); hooks codex-only; trigger contract per skill |
skill-routing-contracts |
mutually-guarded trigger pairs name each other in frontmatter |
scaffold / script-safety / annotate-server / browser-security / session-report |
shipped reference scripts: syntax, no-egress, server behavior |
concord-* (4 files) |
the concord plugin's store, rollout sync, paths, budget |
local-hooks |
warn-only — tells you this clone lacks the pre-commit hook |
CI runs the same command — a red suite here is a red build there.
Optionally also run the official validator:
claude plugin validate dist/plugins/<name> --strict
Use --strict — expect a clean pass, no warnings. (interface moved to the Codex
manifest on 2026-07-29 precisely so --strict passes clean; see
toolkit-plugin-reference.) Anything it reports is a real problem.
7. Commit and push
git add skills/<name>/ dist/ packages/ composition.json .claude-plugin/marketplace.json README.md CLAUDE.md
git commit -s -m "feat: add <name> skill"
git push origin main
Stage dist/ as a whole, not dist/plugins/<name>/ — the sync regenerated
dist/opencode/ and dist/cursor/ too, and leaving either out ships a drifted
tree that opencode-dist.test.mjs / cursor-dist.test.mjs fails on.
packages/ is usually clean for a brand-new
skill (only agent-source edits dirty it), but staging it costs nothing and keeps
this command identical to the update flow below.
Updating an Existing Skill
# 1. Edit skills/<name>/ files
# 2. Sync (mirrors dist/plugins, regenerates dist/opencode + dist/cursor + package agents)
bash scripts/sync.sh <name>
# 3. Verify
node --test
# 4. Commit
git add skills/<name>/ dist/ packages/
git commit -s -m "fix: update <name> skill"
git push origin main
Editing skills/subagent-execution/agents/*.md touches three generated
destinations — dist/plugins/condux/skills/, dist/plugins/condux/agents/, and
packages/condux-opencode/agents/. One sync produces all three; stage all three.
An optional pre-commit hook automates the sync + dist staging — install it with
bash scripts/install-hooks.sh. It lives in .git/hooks/ (not version-controlled),
so every fresh clone must install it again. Never assume the hook is present.
Changing the npm Package
packages/condux-opencode/ publishes @jabworks/condux — the OpenCode plugin that
injects the condux specialist agents. Its agents/ dir is generated (edit
skills/subagent-execution/agents/ instead); index.js and package.json are
hand-edited.
Condux changes go on a branch — never straight to main. A push to main is
what arms the release, so committing there does the review and the release
trigger in one irreversible step. Branch, PR, merge.
# 1. Branch first
git switch -c <type>/condux-<what>
# 2. Edit packages/condux-opencode/index.js (or the agent sources + sync)
# 3. Describe the release
pnpm changeset # pick @jabworks/condux, pick the bump, write the summary
# 4. Verify
node --test
# 5. Commit the changeset alongside the change
git add packages/ .changeset/
git commit -s -m "fix(opencode): <what changed>"
git push -u origin HEAD
gh pr create --fill
Merging that PR into main triggers .github/workflows/release.yml: changesets
opens (or updates) a version PR that consumes the .changeset/*.md files and
bumps version. Merging that second PR is what actually publishes to npm, via
OIDC trusted publishing — there is no NPM_TOKEN. Two merges, not one.
Never hand-edit version in packages/condux-opencode/package.json —
changesets owns it.
A change with no changeset still merges and still ships to the marketplace channel — it just never reaches npm. Nothing warns you. If the change alters what the published tarball contains, it needs a changeset.
That includes editing skills/subagent-execution/agents/*.md: those regenerate
packages/condux-opencode/agents/, which is inside the package's files array, so
an agent-wording tweak is a published change like any other.
Constraints that are easy to break:
index.jsmust export the plugin named only. OpenCode calls every export as a plugin function, so a default re-export registers the hooks twice (08cc554).- Keep generated
agents/in the package'sfilesarray, or the published tarball ships a plugin with no agents. - Keep
publishConfig.provenanceset totrue. It is what makes releases carry a signed attestation tying the tarball to the workflow run and commit; the workflow'sid-token: writepermission is necessary but not sufficient on its own.0.1.0predates it and has none — verify withnpm view @jabworks/condux dist.attestations.
Version Bump
Two independent version schemes — don't confuse them:
| What | Where | How |
|---|---|---|
Plugins (condux, toolkit-ops, standalone skills) |
version in both paired plugin manifests, kept identical |
hand-edited |
@jabworks/condux |
packages/condux-opencode/package.json |
changesets only — never by hand |
marketplace.json entries carry no version field, and neither variant skill tree
(dist/opencode/, dist/cursor/) has a version at all — both refresh with the repo.
For plugins, short form: breaking install path = major, new skill/capability =
minor, anything else that ships = patch. The full bump policy — and the
cache-refresh rationale for bumping on ANY shipped change — has one home:
toolkit-change-control.
Marketplace Entry Fields
The step-4 template above is the complete field set — the schema of record for
marketplace entries and both plugin.json variants is toolkit-plugin-reference.
Add nothing from upstream examples (strict / skills / keywords are not used
in this repo's marketplace.json).
Component Types
| Component | Location | When to add |
|---|---|---|
| Skill instructions | skills/<name>/SKILL.md |
Always |
| Human docs | skills/<name>/README.md |
Non-trivial setup |
| Templates / checklists | skills/<name>/references/*.md |
Agent needs reusable scaffolds |
| Reference scripts | skills/<name>/references/*.js + references/package.json |
Skill ships runnable helpers (CommonJS) |
| Trigger evals | skills/<name>/evals/trigger_eval.json |
Skill needs a measured routing baseline |
Writing trigger-eval oracles
The oracle is what the corpus asserts is correct. Get it wrong and the harness scores a correct routing decision as a miss — and since each run is compared against the last, one wrong oracle poisons every later comparison.
condux's routing payload states that every implementation request starts at
/workflow, and names the skills that execute within workflow rather than
instead of it (discovery, draft-plan, blueprint, test-first-development,
preflight, finalize, code-review, root-cause-analysis,
live-verification, plan-review, technical-spec, subagent-*). For any of
those, workflow is a legitimate first answer whenever the prompt asks to build,
fix, or change something.
Encode that by the shape of the request, never by which cases happened to flake — loosening only the observed failures overfits to model variance and has to be re-chased every run:
| Request shape | Oracle |
|---|---|
| implementation request aimed at a within-workflow skill | accept: ["workflow"] |
| bug-shaped | also accept root-cause-analysis |
| question about the practice itself, or ownership of an artifact only that skill owns | strict — no accept |
Keep some cases strict on purpose. A corpus where every case accepts workflow
measures nothing.
Two failure signatures, two different fixes:
- Missing to another skill that doctrine also allows → too-strict oracle.
Widen
accept. Changes no behaviour, so no re-run is needed. - Missing to
null→ a reach gap in the description; nothing fired at all. That is a real routing defect, and fixing it changes behaviour, so it needs an eval re-run to verify — and watch the neighbouring skills' scores, not just the ones you meant to fix. - An answer the judge was never shown → out-of-catalog harness
contamination. No
acceptalternate can fix one; leave it.
Common Mistakes
| Mistake | Fix |
|---|---|
Editing dist/ directly |
Edit skills/, then bash scripts/sync.sh <name> |
Editing packages/condux-opencode/agents/ |
Generated too — edit skills/subagent-execution/agents/, then sync |
| Forgetting to sync after edits | Run bash scripts/sync.sh — the pre-commit hook does it only if installed (bash scripts/install-hooks.sh); never assume it's present |
Staging only dist/plugins/ after a sync |
Stage dist/ and packages/ — the same sync regenerated the OpenCode tree, the Cursor tree, and the package agents |
Pointing a Cursor install at top-level skills/ |
Use dist/cursor/skills/ — Cursor never reads when_to_use, so raw source skills load with a thin trigger and fail silently |
Committing a condux change straight to main |
Branch first — a push to main arms the release, so main-first collapses review and release into one irreversible step |
Shipping a packages/ change with no changeset |
Run pnpm changeset and commit the .changeset/*.md with the change, or nothing publishes |
| Assuming an agent-wording tweak needs no changeset | It regenerates packages/condux-opencode/agents/, which is published — it does |
Hand-bumping @jabworks/condux version |
Changesets owns that field — a manual bump collides with the version PR |
Adding "type": "module" to the root package.json |
Breaks every CommonJS reference script — the package is ESM-scoped at packages/, not repo-wide |
references/*.js with no references/package.json |
Add { "type": "commonjs" } beside it |
| Co-author trailer in commit | Use -s (--signoff) — no Co-Authored-By: |
| Workflow summary in description | Description = triggering conditions only |
expected_skill: null on an implementation request |
Doctrine routes it to workflow, so the model answers correctly and the corpus records a miss — use accept: ["workflow"] |
| Widening a description to fix a reach gap, without re-running the eval | A description edit changes real routing; only a re-run shows what it stole from neighbouring skills |
Leaving [FILL] placeholders in SKILL.md |
Run quality check before committing |
Missing .codex-plugin/plugin.json |
codex plugin add will fail with "missing plugin.json" |
Missing .claude-plugin/plugin.json |
Claude Code /plugin install won't find plugin metadata |
Wrong skills path in plugin.json |
Must be "./skills/<plugin-dir-name>" starting with ./ |
| Editing only one of the two plugin manifests | Edit the pair together — name/version/skills must match (tests/manifest-parity.test.mjs) |
Skipping node --test before commit |
CI runs the same suite and will fail the build — run it locally first |
04 同仓库更多 Skills
orphan
暂无简介
no-blurb
暂无简介
workflow
Routes any dev task into the right execution tier (Small/Medium/Large) and carries condux's operating rules — proportional effort, lazy skill loading, soft gates, implement-yourself-by-default.
usage-trace
Checks and manages durable, local usage capture — ingest, health status, and the opt-in limit snapshot — for Claude Code and Codex. Capture itself runs automatically at session start.
toolkit-skill-standards
Use when writing or reviewing a SKILL.md for jabworks/agentic-toolkit — frontmatter budgets, the trigger contract ("Use when…" description or when_to_use field), progressive disclosure into references/, and keeping a new description out of existing skills' trigger space. Triggers include "review this skill description", "write the frontmatter", "does this collide with an existing skill", "where should this content live". Not for scaffold/sync mechanics; use toolkit-foundry.
toolkit-research-frontier
Use when planning improvement work on jabworks/agentic-toolkit itself — open problems (trigger-collision automation, YAML-strict frontmatter checks, docs-catalog enforcement), existing assets, the next three concrete steps, and the four-front library-health campaign with commands and success criteria. Triggers include "let's improve our toolkit", "let's improve this repo", "what should we improve next", "toolkit roadmap", "open problems", "run the health campaign".