Writing Markdoc with AI Agents

DeveloperHub pages are authored in Markdoc, a superset of Markdown with a set of typed custom tags. When you edit pages with an AI coding agent (in your IDE, a GitHub-synced repository, or a docs-as-code pipeline), the agent needs to emit DeveloperHub's exact Markdoc dialect. Emit a non-canonical shape and the edit churns on the first save, or silently drops content.

@developerhub/dh-skills is an open-source set of Agent Skills that teach your agent that dialect and the repository structure DeveloperHub expects, so the pages it writes round-trip cleanly.

What it is

The package ships two skills:

• write-markdoc documents every DeveloperHub block and inline tag with its exact syntax, attributes, defaults, allowed values, and the round-trip rules that keep an edit lossless.

• organize-docs-repo covers the repository layout: where each file goes, the navigation and settings files, images, and API references, and how to add, move, nest, group, reorder, or hide pages without breaking the sync.

They use the portable Agent Skills format (Markdown with YAML frontmatter), so they work across Claude Code, Cursor, Codex, and other compatible agents.

When to use it

Reach for it whenever an agent, rather than the editor, is writing your pages:

• Editing pages in a GitHub Sync repository or any docs-as-code workflow.

• Any task where you want the agent to produce correct, lossless Markdoc the first time.

The in-product editor already knows the format, so this skill is for agents working on your pages from outside DeveloperHub.

Installing the skill

The quickest way is the skills CLI, which adds the skill to your agent's skills directory:

Alternatively, copy the skills/write-markdoc and skills/organize-docs-repo folders from the repository into your agent's skills directory yourself (.claude/skills/, .cursor/skills/, and so on).

The package is also on npm, for anyone who prefers to vendor the files as a dependency:

Using it

Once installed, your agent picks the skills up automatically when a task involves your DeveloperHub docs: writing a callout, code block, table, image, or tabs; or changing structure, such as adding, moving, or reordering pages. They give the agent the canonical shape for each tag and the correct file layout, so its changes import cleanly and do not churn or drop content on the next save.

For the reference write-markdoc is built on, see Markdoc Format, which lists every block with an example.

Feedback

Spotted an error, or want a block documented differently? Open an issue on the repository.