agentleFS
dork-labsdork-labs/dorkos/.claude/skills/marketplace-dev/SKILL.md

marketplace-dev

Skill11 starsChanged 51 days agoMITView on GitHub

Develop, validate, and publish DorkOS marketplace packages — agents, plugins, skill-packs, and adapters. Use when creating marketplace items, working in the dork-labs/marketplace repo, or helping users build packages for the personal marketplace.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 0 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Keep this minimal and in sync with .dork/manifest.json.

    line 146
  2. Very specific:

    Write state to ${CLAUDE_PLUGIN_DATA} (the install's own .dork/data, one per install), in commands, hooks, or via the environment variable.

    line 178
  3. Very specific:

    Never ship .dork/data/, .dork/secrets.json, .dork/install-metadata.json, .dork/installed-files.json, .dork/uninstalled-agent.json, or …

    line 181
  4. Very specific:

    Add registry entry: Add to .claude-plugin/marketplace.json plugins array with "source": "./plugins/<name>"

    line 286
  5. Very specific:

    Add sidecar entry: Add to .claude-plugin/dorkos.json plugins object with type, layers, icon, pricing

    line 287

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Marketplace Package Development

Build packages that work for both DorkOS and Claude Code. Every package must pass dorkos package validate before submission. Claude Code compatibility of the whole marketplace is not verified end to end, so package copy never claims "works with any Claude Code setup".

An agent package ships a co-worker, not an assistant: its persona and description state the agent's job (what it owns and who it works with), so the person who installs it, and the agents beside it, can read what it does.

When to Use

SignalExampleAction
Creating a new marketplace item"create a code-review agent for the marketplace"Scaffold with dorkos package init, fill manifest, write skills
Working in the marketplace repoAny work in dork-labs/marketplaceFollow same-repo monorepo conventions (ADR-0237)
Building a personal package"I want to make a skill pack for my workflow"Scaffold in ~/.dork/personal-marketplace/packages/
Fixing validation errorsdorkos package validate failsDiagnose using issue codes below
Adding to the registry"publish this to the marketplace"Add entries to marketplace.json + dorkos.json sidecar

Package Types

There are exactly 5 types. Choose based on what the package delivers:

TypeWhat It IsHas .claude-plugin/plugin.json?Key Directories
agentReusable agent definition with persona, skills, tasksNo.claude/skills/, .dork/tasks/
pluginClaude Code extension with commands, hooks, UIYesskills/, hooks/, commands/
skill-packBundle of SKILL.md files providing reusable expertiseYesskills/
adapterIntegration bridge (relay transport, mesh discovery)Yes.dork/adapters/
shapeA "place" composing packages, agents, schedules, and chromeYesextensions/

Decision rule: If it defines an agent identity (persona, traits) → agent. If it adds UI slots or commands → plugin. If it's just skills → skill-pack. If it bridges an external service → adapter. If it composes existing packages, agents, schedules, and workspace chrome into a switchable place → shape.

Scaffolding

dorkos package init <name> [--type agent|plugin|skill-pack|adapter|shape] \
  [--parent-dir <path>] [--description <text>] [--author <text>] [--adapter-type <id>]
  • --type defaults to plugin
  • --parent-dir defaults to cwd
  • --adapter-type only meaningful for adapters; defaults to package name

What Gets Created

All types:

  • .dork/manifest.json — DorkOS package manifest (schemaVersion 1, version 0.0.1, MIT)
  • README.md

plugin/skill-pack/adapter/shape additionally:

  • .claude-plugin/plugin.json — CC-compatible manifest stub

Type-specific directories:

TypeDirectories CreatedManifest layers
pluginskills/, hooks/, commands/['skills', 'extensions']
skill-packskills/['skills']
adapter.dork/adapters/['adapters']
agent.claude/skills/, .dork/tasks/['skills', 'tasks', 'agents']
shapeextensions/['extensions', 'agents', 'tasks']

Manifest Reference

.dork/manifest.json (Required for all types)

{
  "schemaVersion": 1, // Always 1
  "name": "my-package", // Kebab-case, matches directory name
  "version": "1.0.0", // Semver
  "type": "plugin", // "agent" | "plugin" | "skill-pack" | "adapter" | "shape"
  "description": "What it does", // 1-1024 chars, required
  "displayName": "My Package", // Optional, max 128 chars
  "author": "Dork Labs", // Optional, max 256 chars
  "license": "MIT", // Optional, SPDX ID
  "tags": ["review", "ci"], // Optional, max 20 items, each max 32 chars
  "category": "code-quality", // Optional, max 64 chars
  "icon": "🔍", // Optional, emoji or icon ID
  "layers": ["skills"], // Optional, see Layer enum below
  "requires": ["adapter:slack"], // Optional, dependency declarations
  "featured": false, // Optional, set by registry
}

Layer enum: skills, tasks, commands, hooks, extensions, adapters, mcp-servers, lsp-servers, agents

Requires format: <type>:<name>[@<version>] — e.g., adapter:slack@^1.0.0, plugin:linear-integration

Type-Specific Fields

Agent — adds agentDefaults:

{
  "type": "agent",
  "agentDefaults": {
    "persona": "A security-focused code reviewer", // Max 4000 chars
    "capabilities": ["code-review", "security"],
    "traits": {
      "tone": 3, // 1-5 (formal → casual)
      "autonomy": 4, // 1-5 (guided → self-directed)
      "caution": 5, // 1-5 (conservative → bold)
      "communication": 2, // 1-5 (brief → verbose)
      "creativity": 2, // 1-5 (literal → imaginative)
    },
  },
}

Plugin — adds extensions:

{
  "type": "plugin",
  "extensions": ["my-sidebar-widget"], // Extension IDs registered via ExtensionAPI
}

Adapter — adds adapterType (required):

{
  "type": "adapter",
  "adapterType": "discord", // 1-64 chars, identifies adapter category
}

Skill-pack — no additional fields.

.claude-plugin/plugin.json (Required for plugin, skill-pack, adapter, shape)

{
  "name": "my-package",
  "version": "1.0.0",
  "description": "What it does"
}

Keep this minimal and in sync with .dork/manifest.json. Real CC plugins may also declare commands, agents, hooks, mcpServers, lspServers here.

SKILL.md Files

Skills live in directory-based format: <skill-name>/SKILL.md

---
name: example-skill
description: An example skill for this package.
kind: skill
---

# Example Skill

Content here.

Frontmatter fields:

  • name — kebab-case, matches directory name
  • description — one-line human-readable description
  • kind — skill | task | command (marketplace authors SHOULD include explicitly)
  • For tasks: cron field for scheduling

Skill directories scanned by validator (in order): skills/, tasks/, commands/, .claude/skills/, .claude/commands/, .dork/tasks/

Where a package keeps its state

DorkOS records every file an install puts in the package's folder and replaces or removes only those; everything else is the person's and survives update, reinstall and uninstall (DOR-2245).

  • Write state to ${CLAUDE_PLUGIN_DATA} (the install's own .dork/data, one per install), in commands, hooks, or via the environment variable. Never write into files the package ships: an edited shipped file is replaced on update and the person's copy saved as <file>.dork-old.
  • A shipped default meant to be edited goes in userEditable in .dork/manifest.json (exact paths or dir/**); then the person's copy stays and a changed default is saved as <file>.dork-new. Set minDorkosVersion when relying on it. Nothing that decides what the package runs can be userEditable (hooks, .mcp.json, .lsp.json, monitors, bin/, extensions, tasks, skills, commands, subagents (agents/), output styles, package.json, or a path plugin.json declares one at, or a harness config folder: .claude/, .agents/, .codex/, .opencode/, .gemini/, opencode.json(c)): the schema and validatePackage refuse it (EFFECT_BEARING_PATHS, USER_EDITABLE_EFFECT_PATH).
  • An agent package's folder is its sessions' working directory, so it may not ship harness config for them: .claude/settings*.json, a root .mcp.json, .codex/, opencode.json(c), .opencode/, .agents/harness.manifest.json, .gemini/settings.json, a nested .claude/, or a .claude/agents/ subagent setting hooks/mcpServers/permissionMode (or with a non-YAML header, a repeated key, or too deep) (AGENT_WORKSPACE_CONFIG_FORBIDDEN, ADR 260924-212826). Its .claude/skills, .claude/commands and .agents/skills are read by the install preview. Ship hooks or servers in a plugin the agent requires.
  • Never ship .dork/data/, .dork/secrets.json, .dork/install-metadata.json, .dork/installed-files.json, .dork/uninstalled-agent.json, or *.dork-old / *.dork-new: validatePackage refuses them (RESERVED_PATH_SHIPPED).
  • An agent package's .dork/agent.json, SOUL.md, NOPE.md and MEMORY.md are the agent's: a shipped copy only seeds an install where the file is absent.

Validation

dorkos package validate [path]   # path defaults to cwd

Pipeline (in order, stops early on errors)

StepCheckError CodeSeverity
1.dork/manifest.json exists (or .claude-plugin/plugin.json for CC fallback)MANIFEST_MISSINGError (early return)
2JSON parsesMANIFEST_INVALID_JSONError (early return)
3Passes Zod schemaMANIFEST_SCHEMA_INVALIDError (early return)
4.claude-plugin/plugin.json exists (when type requires it)CLAUDE_PLUGIN_MISSINGError
5All SKILL.md files validSKILL_INVALIDError (per skill)
6Directory name matches manifest.nameNAME_DIRECTORY_MISMATCHWarning

Exit codes: 0 = pass (warnings OK), 1 = errors found

Common Validation Fixes

Error CodeTypical CauseFix
MANIFEST_MISSINGNo .dork/ directoryRun dorkos package init or create manually
MANIFEST_SCHEMA_INVALIDBad name (uppercase), bad version (not semver), missing typeFix the specific field — name must be kebab-case, version must be X.Y.Z
CLAUDE_PLUGIN_MISSINGPlugin/skill-pack/adapter/shape missing CC manifestCreate .claude-plugin/plugin.json with name, version, description
SKILL_INVALIDSKILL.md missing frontmatter or invalid fieldsAdd --- frontmatter block with name, description, kind
NAME_DIRECTORY_MISMATCHDirectory named differently than manifest.nameRename directory or update manifest.name (warning only)

Registry Format (Official Marketplace)

The official marketplace at dork-labs/marketplace uses a same-repo monorepo pattern (ADR-0237). Two registry files work together:

.claude-plugin/marketplace.json (CC-standard)

{
  "name": "dorkos",
  "owner": { "name": "Dork Labs", "email": "hello@dorkos.ai" },
  "metadata": {
    "description": "Official marketplace for DorkOS",
    "version": "0.1.0",
    "pluginRoot": "./plugins",
  },
  "plugins": [
    {
      "name": "my-package",
      "source": "./plugins/my-package", // MUST use ./plugins/ prefix
      "description": "What it does",
      "author": { "name": "Author Name" },
      "license": "MIT",
      "category": "code-quality",
      "tags": ["review", "ci"],
      "keywords": ["code-review"],
    },
  ],
}

Critical: Source paths MUST start with "./plugins/<name>" — the pluginRoot field is ignored when source starts with ./.

.claude-plugin/dorkos.json (DorkOS sidecar — ADR-0236)

{
  "$schema": "https://dorkos.ai/schemas/dorkos-marketplace.schema.json",
  "schemaVersion": 1,
  "plugins": {
    "my-package": {
      "type": "agent", // agent | plugin | skill-pack | adapter | shape
      "layers": ["agents", "tasks"],
      "icon": "🔍",
      "featured": true,
      "pricing": { "model": "free" }, // free | paid | freemium | byo-license
    },
  },
}

Why separate files? CC enforces additionalProperties: false on plugin entries. Any inline DorkOS field is rejected. The sidecar is the only safe extension mechanism.

Drift rules:

  • Plugin in marketplace.json but not dorkos.json → defaults to type: 'plugin' (not an error)
  • Plugin in dorkos.json but not marketplace.json → orphan, silently dropped (logged as warning)
  • dorkos.json missing entirely → all entries get default type (not an error)

Source Path Forms (for community packages in separate repos)

FormExample
Relative path"./plugins/code-reviewer"
GitHub{ "source": "github", "repo": "owner/repo", "ref": "main" }
URL{ "source": "url", "url": "https://gitlab.com/foo/bar.git" }
Git subdirectory{ "source": "git-subdir", "url": "https://...", "path": "packages/plugin-a" }
npm{ "source": "npm", "package": "@scope/name", "version": "^1.0.0" } (not yet supported)

Submission Flow (Official Marketplace)

  1. Scaffold: dorkos package init <name> --type <type> --parent-dir ./plugins
  2. Author: Fill .dork/manifest.json, write skills/hooks/commands, write README
  3. Validate locally: dorkos package validate ./plugins/<name> — must exit 0
  4. Add registry entry: Add to .claude-plugin/marketplace.json plugins array with "source": "./plugins/<name>"
  5. Add sidecar entry: Add to .claude-plugin/dorkos.json plugins object with type, layers, icon, pricing
  6. Validate registry: dorkos marketplace validate .claude-plugin/marketplace.json
  7. Open PR against main of dork-labs/marketplace

Registry Validation Checks

The marketplace validator performs 6 checks:

  1. Fetch/read marketplace.json and dorkos.json
  2. DorkOS schema validation (passthrough — any CC-valid marketplace accepted)
  3. Sidecar schema validation (strict when present)
  4. CC compatibility check (ported CC validator)
  5. Plugin sources reachable (probes each plugin's .claude-plugin/plugin.json)
  6. Reserved-name check (marketplace name not in reserved list)

Exit codes: 0 = pass, 1 = schema/validation error, 2 = CC validator fails or sources unreachable

Personal Marketplace (Local Development)

For iterating before official submission:

  • Location: ~/.dork/personal-marketplace/
  • Auto-bootstrapped on server boot with marketplace.json, README.md, packages/ subdirectory
  • Registered as file:// source named personal
  • Create via MCP: marketplace_create_package tool scaffolds directly into personal marketplace

Workflow: Scaffold in personal marketplace → iterate → validate → move to official repo for submission.

Extension API (Plugin Type Only)

Plugins can register UI extensions. Available slots:

SlotPurpose
sidebar.footerFooter area of left sidebar
dashboard.sectionsDashboard widget grid
command-palette.itemsCommand palette entries
dialogModal dialog slots
settings.tabsSettings dialog tabs
right-panelShell-level right panel (inspector) tabs

The sidebar.tabs and header.actions slots were removed when the web app retired the sidebar tab strip. For a contextual side panel use right-panel; for a dashboard card use dashboard.sections.

Extensions receive an ExtensionAPI object with methods for:

  • registerComponent(slot, id, component, options?) — place React component in a slot
  • registerCommand(id, label, callback, options?) — add command palette item
  • registerDialog(id, component) — register a modal dialog, closed until the returned open(); mounted only while open, closes via onOpenChange(false)
  • registerSettingsTab(id, label, component) — add settings tab
  • getState() / subscribe(selector, callback) — read and watch host state (cwd, activeSession, agent)
  • loadData<T>() / saveData<T>(data) — scoped persistent storage
  • notify(message, options?) — show toast notifications
  • navigate(path) — client-side navigation
  • executeCommand(command) — execute UI commands
  • openCanvas(content) — open canvas with content

Declare extension IDs in the manifest: "extensions": ["my-extension-id"]

Anti-Patterns

Don'tDo Instead
Put DorkOS fields in marketplace.json plugin entriesUse dorkos.json sidecar
Use "source": "code-reviewer" (relative to pluginRoot)Use "source": "./plugins/code-reviewer" (explicit path)
Skip .claude-plugin/plugin.json for non-agent typesAlways create it — validation will fail without it
Use uppercase or underscores in package namesUse kebab-case: my-cool-plugin
Leave SKILL.md without frontmatterAlways include name, description, kind in --- block
Set version to non-semver stringsUse X.Y.Z format (e.g., 0.1.0, 1.0.0)
Forget to add both registry entriesAlways update both marketplace.json AND dorkos.json

Canonical Examples

Minimal Agent Package

my-agent/
├── .dork/
│   └── manifest.json    → type: "agent", agentDefaults: { persona: "..." }
├── .claude/
│   └── skills/
│       └── my-skill/
│           └── SKILL.md
├── .dork/
│   └── tasks/
└── README.md

Minimal Plugin Package

my-plugin/
├── .dork/
│   └── manifest.json    → type: "plugin", extensions: ["my-widget"]
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── helper-skill/
│       └── SKILL.md
├── hooks/
├── commands/
└── README.md

Minimal Skill-Pack

my-skills/
├── .dork/
│   └── manifest.json    → type: "skill-pack"
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   ├── skill-one/
│   │   └── SKILL.md
│   └── skill-two/
│       └── SKILL.md
└── README.md

Minimal Adapter

my-adapter/
├── .dork/
│   └── manifest.json    → type: "adapter", adapterType: "discord"
├── .claude-plugin/
│   └── plugin.json
├── .dork/
│   └── adapters/
└── README.md

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.