Skip to content
Skills Library
Programming · Learning & explanation

devharness-contributing

/devharness-contributing

Conventions for writing code in the devharness repo itself (as opposed to using its tools to debug some other app) - how tool failures propagate, why behaviour must read _meta rather than rendered text, where each kind of documentation lives, and the release rules an agent gets wrong. Use when editing files under src/, adding or changing an MCP tool, cutting a release, or debugging why a rebuild didn't take effect in a live session.

Repository
devharness ↗
Licence
MIT
Last repository change
21.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 21.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Conventions for writing code in the devharness repo itself (as opposed to using its tools to debug some other app) - how tool failures propagate, why behaviour must read _meta rather than rendered text, where each kind of documentation lives, and the release rules an agent gets wrong. Use when editing files under src/, adding or changing an MCP tool, cutting a release, or debugging why a rebuild didn't take effect in a live session.

Original author description

Conventions for writing code in the devharness repo itself (as opposed to using its tools to debug some other app) - how tool failures propagate, why behaviour must read _meta rather than rendered text, where each kind of documentation lives, and the release rules an agent gets wrong. Use when editing files under src/, adding or changing an MCP tool, cutting a release, or debugging why a rebuild didn't take effect in a live session.

How it works

  1. Releasing: what an agent gets wrong
  2. Tool failures are THROWN, not returned
  3. Read meta, never rendered text
  4. Which file takes the prose
  5. Config philosophy
Original SKILL.md headings · 49 lines, 746 words
SKILL.md preview
---
name: devharness-contributing
description: Conventions for writing code in the devharness repo itself (as opposed to using its tools to debug some other app) - how tool failures propagate, why behaviour must read _meta rather than rendered text, where each kind of documentation lives, and the release rules an agent gets wrong. Use when editing files under src/, adding or changing an MCP tool, cutting a release, or debugging why a rebuild didn't take effect in a live session.
---

# Contributing to devharness

**Read `CONTRIBUTING.md` first.** It owns the mechanics — build and test commands, running your build as `devharness-dev`, hot-reload and how to tell whether it took, `stress:suspend`, the release sequence, and the doc-sync list. It is the single source for all of that; this skill does not repeat it.

What follows is what `CONTRIBUTING.md` does not say: the code conventions, and the release habits an agent specifically gets wrong.

## Releasing: what an agent gets wrong

The sequence is in `CONTRIBUTING.md`. Three things about it change how you should behave, not just what you type:

- **`npm run build:verify` before bumping, always.** Skipping it once put out a tag whose publish failed on a stale `plugin/.mcp.json` pin, while `notify-marketplace` had already opened a PR pinning a version npm never received. After the tag, it is too late.
- **`postversion` pushes the branch and the tag with no confirmation.** Every local commit on `main` ships. Nothing is "committed but held back locally" once someone bumps — never describe a commit that way, and make `main` exactly what should ship before bumping.
- **Don't offer to push afterwards, and don't say a release "wasn't published".** Both already happened. Check rather than guess: `gh run list --workflow=publish.yml`, `npm view devharness version`.

Never run `npm publish` by hand — a second unverified path to the registry that collides with the run the tag already started.

## Tool failures are THROWN, not returned

`executeToolCall` (`src/index.ts`) converts any `isError` response into a thrown `ToolError` (`src/tool-error.ts`) carrying that response. **Downstream code branching on `result.isError` is dead**, and a fake `executeToolCall` that *returns* isError responses covers that dead branch while the live path goes untested. That mismatch shipped absent-element conditions failing whole runs, `LAUNCH_FAILED` never reaching the user, and a leaked verification tab.

- **Wrap every fake `executeToolCall` in `productionShaped()`** (`src/test-support/fake-execute-tool-call.ts`). Import the real `ToolError` rather than re-declaring its shape.
- **Classify failures by `_errorId`, not message text.** `createErrorResponse` attaches it and `ToolError` carries the response, so `err.response._errorId` is available in-process. `isElementNotFoundFailure()` in `messages.ts` is the worked example.
- **Build fixtures with the real helpers** (`createErrorResponse`, `getErrorMessage`, `formatCodeBlock`, `webStorageMeta`). Hand-written text drifts: fixtures asserted `Element not found: ...` for a year while `MessageManager` emitted `Error: Element not found: ...`.

## Read `_meta`, never rendered text

Structured results live in `_meta` (`src/tool-response.ts`). Anything deciding *behaviour* must read that — rendered text mixes our formatting with page-controlled data. Every instance of grepping the markdown was a bug: a localStorage `"null"` read as absent, a URL containing a comma compared truncated, `**error**` counted inside a logged message, `\d{3}` matching any three digits as an HTTP status.

If the data isn't in `_meta`, add it there rather than parsing the string. **No text fallback "just in case"** — production has one shape, and a fallback no path reaches is untestable and hides drift. The one exception is a raw library exception with no `_errorId`.

## Which file takes the prose

- `src/tools/*.ts` — one file per tool family, action-based schemas.
- `docs/mcp-instructions.md` — sent on every MCP connection, injected unconditionally. Keep it tiny.
- `docs/instructions.md` — full tool reference for clients without Agent Skills support.
- `plugin/skills/devharness/` — the Agent Skill shipped to consumers; loads only on activation.
- `docs/messages.md` — source of truth for response text (`## MESSAGE_ID` sections), parsed at runtime by `messages.ts`. Costs tokens only when that call happens, so detail is fine here.

**Keep tool schema descriptions terse** (`.describe()` and `createTool()`'s first argument). They go to every session at `listTools` time whether or not the tool is ever called — a fixed cost, not a progressive-disclosure surface. Put why/when/what-happens in the shipped skill or its `references/`.

**Skill and reference prose is a token budget, not a page count.** Say it once, in the fewest words that survive being wrong. Cut restatement and any sentence that only reassures. If a paragraph and a table say the same thing, keep the table.

**Comments are not journals.** What the code does, or why the non-obvious choice was made, in one line where possible. No narrating history ("this used to..."), no arguing with a previous author, no restating the line below. Git holds history; the comment holds the constraint.

## Config philosophy

Per `docs/working_with_llm_notes.md`: LLMs editing this server's own behavior are optimistic and sometimes wrong. Any LLM-driven config change needs a manual override path the user can reach without going through the LLM — don't add a setting only reachable through an agent's tool calls.

Versions

The database has no other skills named devharness-contributing.

Database snapshot: 13.11.2026 · package version a303623b49f7 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100devharness
    Drive and debug a running app via the devharness MCP server - launch or attach to Chrome and Node.js, set breakpoints and logpoints, inspect call stacks and variables, watch console and network, manage dev servers, replay any earlier tool call by its history index, and record…
  • 90instructing-sessions
    Where each fact devharness sends a session belongs, and how a session is moved off a worse path. Use when adding or changing any text a session receives from devharness - server instructions, the SessionStart hook, a tool or parameter description, reply or error text in…
  • 100documentation-structure
    Documentation architecture for this repository. Use when creating, updating, or reviewing README.md, CONTRIBUTING.md, or docs/ files. Covers separation of concerns, vendor documentation standards, cross-references, and validation.
  • 100contributing-guide-creator
    Create contributing guide creator operations. Auto-activating skill for Technical Documentation. Triggers on: contributing guide creator, contributing guide creator Part of the Technical Documentation skill category. Use when working with contributing guide creator…
  • 100contributing
    Use when contributing to the Butterbase codebase, adding new MCP tools, creating API routes, writing migrations, or understanding the monorepo architecture
  • 95agents-contributing-setup-repo
    Set up a repository to receive help from AI agents under the AGENTS-CONTRIBUTING spec. Use when a repository owner asks to accept agent contributions, add AGENTS-CONTRIBUTING.md, or open their repo to donated AI capacity.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.