Skip to content
Docs

Writing your own intelligence

Writing your own intelligence means editing the Markdown files that govern how Denote reasons. Every slash command, every skill, every agent, every knowledge file is a plain Markdown document you can open and change. Denote's intelligence system is not a black box. It is a directory of editable text files, and your edits are picked up the next time Claude Code runs.

The four surfaces

You can edit four layers of the intelligence system, from the smallest to the most foundational.

1. Slash commands, .claude/commands/<name>.md

The short invocation wrappers. Each slash command is a Markdown file that tells Claude Code what to do when you type /<name> in the terminal.

A command file typically contains:

  • A one-line purpose at the top.
  • A Context section framing the designer's state and the skill's role.
  • A Voice section governing how the skill talks to a designer.
  • The files to read and write, the knowledge files to load, and a step-ordered procedure.

One important caveat: the five commands Denote owns (vision.md, ontology.md, architecture.md, screens.md, spec.md) are overwritten on every project open so they always match your app version. Edits to those five don't survive. Commands you add under your own names persist — and to change how the five reason, edit the knowledge files they read (below), which are yours.

2. Skills, intelligence/skills/<name>/SKILL.md

Deeper reasoning modules. Each skill has its own directory with a SKILL.md describing a full methodology plus any supporting files (examples, rubrics, catalogs).

The default reasoning skills on disk are: object-model, flow-mapping, ia-audit, product-spec, critique, visual-critique, design-system-audit. The five layer commands don't invoke these directly — they read the knowledge files instead — but the modules ship with every project as reference methodology you can wire into commands of your own. A custom /ia-review command that loads ia-audit and runs it against your architecture file is a natural extension.

Edit or add these when you want a reusable methodology your own commands can share.

3. Agents, intelligence/agents/<name>.md

Longer-form roles that coordinate multiple skills and knowledge files for a specific kind of work. The default agents are design-builder, design-critic, craft-lead, product-strategist, ux-architect.

An agent file defines:

  • The role (what the agent is for).
  • When to activate the agent.
  • Primary knowledge files the agent must read.
  • Secondary knowledge files the agent draws on.
  • The methodology the agent follows.

Edit these when you want to change how an agent approaches a whole class of work. Tune the Design Builder's fidelity spectrum. Adjust the Design Critic's tolerance for craft failures. Replace the Craft Lead's violation list.

4. Knowledge, intelligence/knowledge/<category>/<topic>.md

The reference knowledge that skills and agents read before they act. Thirty-four files organized into seven categories.

  • design-systems/ (token architecture, governance, navigation shells, surface patterns, visual cue library, and more)
  • interaction-design/ (patterns library, design tool patterns, progressive disclosure, information architecture, workflow mapping)
  • object-oriented-ux/ (entity analysis, relationship modeling, object mapping, state machines, design ontology)
  • philosophy/ (design philosophy)
  • product-strategy/ (opportunity mapping, competitive analysis, success metrics, systems thinking)
  • user-understanding/ (jobs-to-be-done, mental models, research methods)
  • visual-design/ (visual hierarchy, typography systems, spatial systems, color theory, component anatomy)

Each file is a focused treatment of one topic. Typography systems. Visual hierarchy. Mental models. Entity analysis. These are the atomic units of the intelligence system. Every skill and agent declares which knowledge files it reads.

Edit these when you want to change the foundations. Rewrite the typography scale. Add a new design-systems pattern. Tune the mental-models vocabulary for your domain.

How to add a new slash command

Drop a new Markdown file at .claude/commands/<name>.md. The next time you type /<name> in the embedded terminal, Claude Code will find it.

Minimal structure:

One-line purpose at the top.

## Context

What state the designer is in when they run this command.

## Instructions

Step-ordered procedure. Reference which files to read, which to write,
which knowledge files to load.

You can reference existing skills and agents by path. For example, a new command that runs a craft audit on a specific directory might spawn the Craft Lead agent by reading intelligence/agents/craft-lead.md and scoping the scan.

How to add a new skill

Create a directory at intelligence/skills/<name>/ and put a SKILL.md inside. Include the purpose, when to use it, required input, and the methodology. Add supporting files (examples, catalogs, rubrics) in the same directory if helpful.

Reference the new skill from a slash command by name or by path. The command is the invocation surface; the skill is the reasoning.

How to add a knowledge file

Drop a Markdown file under the right category in intelligence/knowledge/<category>/. Use an existing category if one fits. Add a new category (a new subdirectory) when you need one for a domain Denote does not cover out of the box.

Name knowledge files after the topic, not the command that consumes them. entity-analysis.md, not extract-input.md. Knowledge files are reference material; multiple skills can read the same file.

System-level versus project-level edits

Every project is seeded from Denote's current intelligence system, but the sync rules differ by tier:

  • Knowledge, reasoning skills, and agents (intelligence/**/*.md) are copied only if missing. Your edits are project-level, travel with the folder, and survive every open. They do not leak back into Denote's defaults.
  • The five owned commands (.claude/commands/) and the generated catalogs (intelligence/catalog/*.json) are refreshed from Denote on every project open. They encode app behavior, not designer intent.

This is the same two-tier model as the governance schema. Start from a shared opinionated baseline; override when the project needs it.

Good and bad reasons to edit

Edit when you disagree. If the Design Critic approves work that is wrong for your product, change the rubric. If the pattern catalog omits a pattern your domain depends on, add it.

Edit when you specialize. A finance product, a developer tool, and a consumer utility have overlapping but different vocabularies. Add project-specific knowledge files for your domain so the skills reason in your terms.

Edit when you have learned. You will notice the same conversation happening over and over during skill runs. When you notice a pattern, lift it into the file. The skill stops re-asking.

Do not edit to remove opinions. An intelligence system without opinions is a prompt. The point of the system is that it takes a stance. Your edits should refine the stance, not erase it.

Do not edit to shorten. The knowledge files are dense on purpose. They give the skills enough text to reason from. Trimming a knowledge file to half its length because it feels long is usually a regression.

What good edits look like

  • Concrete. "Status badges use semantic colors, not brand colors" is better than "be thoughtful about status colors."
  • Opinionated. "Use card grids for image-heavy entities, not tables" is better than "consider the visual weight of images when choosing a pattern."
  • Referenced. When a rule depends on context, say what context. "For consumer-facing list views with fewer than fifty items," not "usually."
  • Editable. Date-stamp major changes in the file if the change is significant. The commit history is authoritative, but a note inside the file helps when someone reads it cold.

Where to next