Skip to content
NeuroDock

Write a skill

After this page you will have written a working NeuroDock skill, replayed it under CI test harness, and opened a draft PR.

Estimated time: 15 minutes.

Prerequisites: comfortable with git, comfortable editing YAML frontmatter. No language runtime required to write the skill itself; tests are markdown invocations replayed by the CI harness.

1. Clone and install

Section titled “1. Clone and install”
Terminal window
git clone https://github.com/tlennon-ie/neurodock.git
cd neurodock
pnpm install
uv sync

2. Copy an existing skill as your template

Section titled “2. Copy an existing skill as your template”

The canonical copy-from skill is packages/skills/adhd-daily-planner/ — it is v0.1.0, status: stable, and exercises every piece of the contract (frontmatter, triggers, MCP dependencies, profile dependencies, body, tests).

Terminal window
cp -R packages/skills/adhd-daily-planner packages/skills/<your-skill-name>

Then rewrite SKILL.md for your skill: change name, description, neurotypes, triggers, mcp_dependencies, profile_dependencies, and the body itself. Replace the contents of tests/ with at least three of your own test invocations. There is no _template directory — every shipped skill is a working example and any of them is a valid starting point. If you want a different shape (a guardrail-hooked skill, a content-only skill, a passive-formatter skill), pick the closest shipped skill from packages/skills/ and copy that one instead.

3. Edit SKILL.md

Section titled “3. Edit SKILL.md”

The frontmatter:

---
name: my-skill
description: One-sentence statement of what the skill does and for whom.
version: 0.0.1
neurotypes: ["adhd"]
status: draft
triggers:
  slash_commands:
    - "/my-skill"
  semantic_matches:
    - "phrase a user might say"
mcp_dependencies:
  - mcp-cognitive-graph
profile_dependencies:
  - preferences.output_format
  - preferences.max_chunk_size
---

The body is the instructions the client follows when the skill activates. Keep it short. Name the inputs you read, the MCP tools you call, the output shape you produce.

4. Add at least three test invocations

Section titled “4. Add at least three test invocations”

In tests/, add markdown files like:

# Test: morning brief on a fresh install


## Input
/morning-brief


## Expected
- A statement that the cognitive graph is empty.
- The current time and energy zone.
- No fabricated decisions.

CI replays these against a reference MCP client and checks the output shape matches expectations. Three is the floor; more is welcome.

5. Accessibility check

Section titled “5. Accessibility check”

Run the ND-readability pass locally:

Terminal window
pnpm --filter @neurodock/skills test:a11y -- --skill <your-skill-name>

This catches: max-chunk-size violations, animation references, gradient references, and patronising voice patterns. (Per the accessibility-auditor agent spec.)

6. Open a draft PR

Section titled “6. Open a draft PR”
Terminal window
git checkout -b feat/skills/<your-skill-name>
git add packages/skills/<your-skill-name>
git commit -m "feat: add <your-skill-name> skill"
git push -u origin feat/skills/<your-skill-name>
gh pr create --draft --title "feat: add <your-skill-name> skill"

Two reviewers will be auto-requested via CODEOWNERS: one core maintainer plus one with the lived experience tagged in your frontmatter neurotypes:.

What’s next

Section titled “What’s next”