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 Before You Start section with preconditions (files to read, arguments to check).
  • A How to Behave section with behavioral rules.
  • A detailed procedure, step-ordered.

Edit these when you want to change a skill's default behavior. Tighten a preamble. Add a pre-check. Restrict output length. Rewrite the conversational register.

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

The deeper reasoning modules that commands invoke. Each skill has its own directory with a SKILL.md describing the full methodology plus any supporting files (examples, rubrics, pattern catalogs).

The default reasoning skills on disk are: object-model, flow-mapping, ia-audit, product-spec, critique, visual-critique, design-system-audit. Layer commands in .claude/commands/ read these skills for shared methodology (for example, /extract reads object-model for the entity-analysis approach; /structure reads ia-audit for the hierarchy rubric).

Edit these when you want to change the reasoning the commands ride on. Revise an evaluation rubric. Add a new pattern to the pattern catalog. Adjust the four-question filter for entity extraction.

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, component anatomy, governance, 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 copies the current intelligence system into its .claude/commands/ and intelligence/ directories at create time. After that moment, the copy is yours.

  • Project-level edits affect only the project whose directory you edited. They travel with the project folder (they live inside it). They do not leak back into Denote's defaults.
  • System-level edits (the defaults Denote ships with) only affect projects created in the future. Existing projects keep the copy they were seeded with unless you manually sync.

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