Writing Effective Project Instructions for the "Format as html" Claude Project
A behavioral contract, short, XML-tagged, positively framed: that
encodes the project's editorial thesis as a recognition-driven default,
not a mandate. Plus the paste-ready draft itself.
Prepared for: the project ownerSources: Anthropic help-center · Thariq (html-effectiveness) · Mnimiy (CLAUDE.md) · J.D. Hodges · M. Onwuka
Bottom line
Anthropic's own help-center guidance says project instructions should be
short, focused, and reserved for general project context, key
guidelines, and Claude's role: with task-specific stuff left
for the chat. For your "Format as html" project, that means a tightly
written behavioral contract (~300 to 500 words) that (1) tells Claude this
is a curated essay collection about HTML-as-AI-output-format, (2) sets
a default to produce self-contained .html artifacts with an
explicit carve-out for cases where markdown is right, (3) names the
editorial/visual style of the existing essays, and (4) tells Claude when
to lean on project knowledge versus answer directly. The pasteable draft
is in Deliverable B below.
See § Details · B for the draft. See § Caveats
for what the X post you cited actually says (it's about Claude Code
output format, not Projects guidance).
§ 01 / TL;DR
Three takeaways, before the long version
01 / Length
Keep instructions short and behavioral
Anthropic's docs explicitly recommend project instructions for
"general context around your project, key guidelines, and Claude's
role" and reserve task-specific instructions for the chat itself.
Aim for ~300 to 500 words; longer instructions consume tokens in every
chat and rules buried at the end tend to get lost.
02 / Thesis
Encode the thesis as a default, not a mandate
Following Thariq's own warning against "a /html skill that
mechanically converts every prompt," the right pattern is: default
to a self-contained HTML artifact when the output benefits from spatial
layout, color, diagrams, interactivity, or round-trip editing, and
explicitly carve out short conversational replies, code-only snippets,
and terminal-style answers.
03 / Style
Let project knowledge be the style guide
Your existing essays (the html-effectiveness companion, the CLAUDE.md
12-rules piece) are themselves the style reference. The instructions
should say "match the visual and editorial register of the essays
in project knowledge" and let RAG do the heavy lifting rather than
describing the style in prose.
§ 02 / Key findings
Seven things that matter for this project's instructions
01SOURCE · DOCS
What Anthropic actually says about project instructions
Two help-center articles are authoritative. Understanding Claude's
personalization features says project instructions "help Claude
understand the specific context and requirements for a particular
project. These instructions only apply to chats within that
project," and lists four uses: provide project-specific context;
set guidelines for a particular workflow; establish requirements for
a specific set of tasks; define roles or perspectives Claude should
adopt within the project.
How can I create and manage projects? (updated March 16, 2026)
adds: "Claude will use these instructions for all the chats within
the project. Note: Context is not shared across chats within a project
unless the information is added into the project knowledge base."
That last sentence matters: anything you want Claude to remember
across chats must be in project knowledge, not just
in the instructions.
02SOURCE · COMMUNITY
No published character limit, but tokens still cost
Anthropic does not document a character cap for project instructions.
J.D. Hodges' Claude Project Instructions: Examples & Templates
(2026) states verbatim: "Anthropic does not appear to publish
a project instructions character limit in the help docs as of March
2026." However, Anthropic's own Usage limit best practices
article tells you to "shorten project instructions"
and notes that Claude performs best when you use them for general
context, key guidelines, and Claude's role, reserving task-specific
instructions for the chat. Practical guidance from community guides
converges on ~300 to 500 words.
03METHOD · PROMPT-ENG
Prompt-engineering techniques that transfer to project instructions
Anthropic's prompt-engineering docs flag a small set that matter for
persistent instructions: (a) be clear and
direct: "if a human would be confused, Claude will be too";
(b) give Claude a role in a system-prompt-style
opening sentence ("You are X working on Y");
(c) use XML tags to separate sections (<role>,
<defaults>, <style>,
<knowledge_use>), Claude was trained with XML in
its training data and parses tagged structure more reliably than
markdown headings;
(d) prefer positive framing over negation: Anthropic's best practices explicitly say "Tell Claude what to do
instead of what not to do."
"A good alternative to negative instructions is to reframe negative
instructions as positive, explicit commands. Instead of telling the
model what to avoid, tell it what you want it to do.": Zhu Liang, "The Pink Elephant Problem" (Aug 2025)
And (e) explain the intent behind a rule,
not just the rule, because that constrains how Claude generalizes to
cases you didn't anticipate.
04SOURCE · COMMUNITY
Community consensus on Projects-specific mistakes
J.D. Hodges' Claude Project Instructions guide (March 26,
2026) and Melissa Onwuka's Claude Projects: Complete Guide
(December 24, 2025) name the four recurring anti-patterns:
(i) duplicating profile-level preferences in every
project; (ii) writing essays instead of rules
("Use TypeScript strict mode" beats a paragraph of
rationale); (iii) vague directives: Onwuka's
specific warning: "Avoid vague directives like 'be helpful.'
Instead, provide specific guidance on tone, format, and behavior.";
(iv) stale instructions, both guides recommend
reviewing every couple of weeks. The fix: front-load context, use
short directives, upload supporting docs to knowledge instead of
stuffing them into instructions, and iterate after 3 to 5 conversations.
05CROSS-SURFACE
The CLAUDE.md ↔ project-instructions relationship
These are separate systems for separate surfaces. CLAUDE.md is read
by Claude Code (the terminal agent) from a project root at session
start; project instructions are read by claude.ai for chats inside a
Project. They don't load together unless you're using Claude Code
inside a directory while also having a claude.ai Project open, even
then they're independent contexts.
What does transfer is the philosophy: a behavioral contract
that closes specific failure modes. The 12-rule CLAUDE.md spec in
your claude-md.html essay by Mnimiy is exactly this
pattern applied to a coding agent, each rule names a failure mode
("silent assumptions," "scope creep," "fail loud") and the
contract that closes it. The same shape works for project
instructions, scaled down: pick the 4 to 6 failure modes that matter
for your project and write rules that close them.
Anthropic's Claude Code best-practices doc reinforces this:
"treat CLAUDE.md like code: review it when things go wrong, prune
it regularly, and test changes by observing whether Claude's behavior
actually shifts."
06SOURCE · PRIMARY
Thariq's actual position on HTML, and why it doesn't translate to "always output HTML"
The Thariq essay you flagged is not Projects guidance; it's an
argument about agent output format. The thesis, verbatim from the
essay's opening (reproduced in the dogum/html-artifacts README):
"Markdown has become the dominant file format used by agents to
communicate with us. It's simple, portable, has some rich text
capability and is easy for you to edit. But as agents have become
more and more powerful, I have felt that markdown has become a
restricting format."
The crucial caveat, also verbatim:
"I'm a little bit afraid that people will read this article and
turn it into a /html skill or something. While there might be some
value in that, I want to emphasize that you don't need to do much
to get Claude to do this."
The companion site at thariqs.github.io/html-effectiveness
groups the cases where HTML beats markdown into nine categories, Exploration & Planning, Code Review, Design, Prototyping,
Diagrams, Decks, Research & Learning, Reports, Custom Editors, and that taxonomy is exactly what the project instructions should
encode as the "when to default to HTML" heuristic. The
carve-out matters too: "Markdown is fine for chat-flavored
replies, code snippets, and quick summaries."
07VISUAL · STYLE
The design-system-from-codebase trick, and the slop you're avoiding
A standing risk in HTML output from Claude is what the
dogum/html-artifacts README calls the "default-AI aesthetic."
The skill's README states the failure mode verbatim:
"A skill that mechanically converts every prompt into HTML would
be worse than no skill, it would obscure cases where markdown is
the right answer, and it would calcify into a default-AI aesthetic of
'every artifact is a card with a gradient.'"
Concretely the README lists patterns to actively avoid:
"gradients, four shades of indigo, emoji-decorated headers,
'glass morphism'." Thariq's essay shows a different register, typographically dense, magazine-style HTML with real hierarchy and
SVG. The proven workaround is the design-system-from-codebase
pattern: have Claude read your repo (or in this case, the
existing essays in project knowledge) and produce a tokens reference,
then use that reference as the style basis for new artifacts. For
your project, the equivalent is "match the visual register of
the essays in project knowledge": a short, concrete style
directive that points Claude at the right reference material rather
than trying to describe the style in prose.
§ 03 / Details · A
Best-practices guide for writing Claude project instructions
Structure (in order)
Role and project scope. One or two sentences framing what the project is and what Claude's role inside it is. Anthropic's docs explicitly list "Define roles or perspectives Claude should adopt" as a use case. Start with the noun ("This project is a curated library of essays on…") because Claude uses the opening lines to frame everything that follows.
Defaults. The 2 to 5 behaviors that should apply to every response in this project. Phrase them as positive directives ("Default to producing a single self-contained .html artifact when…") rather than prohibitions.
Carve-outs. Explicit cases where the default does not apply. This is the move that separates a working instruction set from a heavy-handed one, Thariq's own essay makes the carve-out central, and the dogum/html-artifacts skill author calls the absence of carve-outs the failure mode of a naive /html rule.
Style register. One or two sentences that anchor visual and editorial style, pointing at the project knowledge base rather than trying to describe a design system in prose.
Knowledge-base usage. How and when to lean on the uploaded essays. The help docs are explicit that project knowledge is the only thing carried across chats; instructions should tell Claude when to consult it.
Failure-mode rules. A short list (3 to 6) of specific behaviors to enforce, phrased the way the CLAUDE.md 12-rule spec does: name the failure mode, state the rule, optionally state the why.
Mechanics
Use XML tags (<role>, <defaults>, <carve_outs>, <style>, <knowledge_use>, <rules>). Anthropic's prompt-engineering docs say XML tags help Claude parse multi-component prompts more reliably than markdown headings; the same applies to persistent instructions. Tag names are not reserved, pick descriptive ones and be consistent.
Positive framing. Anthropic's best practices explicitly recommend "Tell Claude what to do instead of what not to do." Replace "don't produce generic gradient-card layouts" with "match the typographic, magazine-style register of the essays in project knowledge."
Explain intent for non-obvious rules. J.D. Hodges' guide and the Anthropic Claude Code best-practices doc agree: a rule with a one-clause "why" generalizes better than a bare imperative.
Aim for ~300 to 500 words. No documented hard limit, but every word costs tokens on every chat, and rules buried at the end of long instructions get lost. Anthropic's Usage limit best practices is explicit: "Shorten project instructions. Keep your project instructions concise and focused on essential information."
Iterate by friction. Aimaker's "The Ultimate Guide to Claude's Project Memory" makes the useful point that "the key to building useful project memory isn't knowing what to store upfront. It's paying attention to friction." When Claude does something off, that's the data point. Don't try to write the perfect instruction set up front; write a minimum viable one and let friction tell you what to add.
Anti-patterns to avoid
Anti-pattern
Fix
"Be helpful and professional."
Replace with specific behaviors (e.g. "default to self-contained HTML for outputs longer than ~10 lines").
Duplicating profile-level preferences.
Project instructions stack on top of profile preferences, only put what's specific to this project in the project instructions.
Writing essays instead of rules.
Short, scannable directives. Claude responds better to "Use Inter for body, JetBrains Mono for code" than to a paragraph of rationale.
Stuffing reference docs into instructions.
Upload them to project knowledge instead. Instructions describe behavior; knowledge stores content.
Pure negation ("don't do X").
Reframe as positive ("do Y"). LLMs continue patterns; "don't think of a pink elephant" is famously counterproductive.
Set-and-forget.
Review every couple of weeks. Each time Claude does the wrong thing twice in a row, add or amend a rule.
How the philosophy from CLAUDE.md transfers (and where it doesn't)
The 12-rule CLAUDE.md spec in claude-md.html (Mnimiy, May
2026) is a behavioral contract for a coding agent operating on a
codebase: rules like "Read before you write," "Tests verify
intent," "Surface conflicts," and "Fail loud" are about the
failure modes of code-editing autonomy. Project instructions for a
content/library project are a different domain, there's no codebase to
edit, no tests to run, no commit boundary, so most of the 12 rules
don't transfer directly. What does transfer is the
structure of a CLAUDE.md: each rule names a specific
failure mode and the contract that closes it.
Adapted to "Format as html," the failure modes that matter are
different: default-AI gradient slop instead of dense typography;
markdown when HTML would land harder; HTML when a one-liner would do;
over-explanation when the user is already an HTML maximalist. The draft
below encodes those.
§ 04 / Details · B
Draft project instructions: ready to paste
Sized for the project as described (curated HTML essays on AI-coding
output formats, CLAUDE.md, AI coding craft, with Thariq's
html-effectiveness essays and the Mnimiy CLAUDE.md piece in project
knowledge). ~430 words.
project-instructions.xml
33 lines · ~430 words · paste into "Set project instructions"
<role>You are assisting inside "Format as html," a curated library of essays aboutworking with AI coding agents (Claude Code, Kimi) and producing artifactsin HTML rather than markdown. The project's editorial thesis is that HTMLis often a better output format than markdown for AI-generated artifactsthat benefit from spatial layout, color, real diagrams, interactivity, orround-trip editing. Treat me as an experienced practitioner who is alreadysold on this thesis: do not re-argue it.</role><defaults>- When producing any output longer than a short conversational reply, default to a single self-contained.html file (an artifact, when running in claude.ai). One file, inline CSS, inline SVG where useful, vanilla JS where interactivity helps.- Lean on the essays in project knowledge as the editorial and visual reference. Match their typographic register: dense, magazine-style, real hierarchy, restrained color, generous whitespace, system or serif body type with a monospace for code.- When asked to plan, compare, review, explain, prototype, diagram, present, or build a small editor: produce HTML. These are Thariq's nine categories from html-effectiveness; treat them as the default surfaces.</defaults><carve_outs>Do not produce HTML for:- Short conversational replies, clarifications, or yes/no questions.- Code-only outputs (just give me the code block).- Terminal-style answers, command snippets, or anything I'd paste into a shell.- Content that is genuinely just a few sentences.For these, plain text or markdown is correct.</carve_outs><style>- Match the visual register of the essays already in project knowledge. Before producing a styled artifact for the first time in a chat, scan one or two of those essays to absorb the type scale, color palette, and spacing they use.- Actively avoid the default-AI aesthetic: no purple/indigo gradients, no glass morphism, no card-with-shadow-and-gradient-border, no emoji in headers, no four-shades-of-blue-on-white dashboards.- When unsure, copy the visual conventions of the html-effectiveness companion site over generic Tailwind defaults.</style><knowledge_use>- Cite essays by title and author when you draw on them directly.- If a user request maps onto a pattern an essay in project knowledge already covers (e.g. "annotated PR review HTML"), surface the relevant essay and build on its conventions rather than reinventing.- Project knowledge is the only state that carries across chats, do not rely on remembering earlier conversations.</knowledge_use><rules>- Surface format choice. Before producing a long artifact, state in one sentence why HTML (or why markdown, if you're carving out): this lets me redirect cheaply.- No silent scope expansion. If a request is ambiguous, ask one focused question rather than producing three speculative artifacts.- Fail loud on missing context. If you would need to invent project conventions to answer, say so and ask, rather than confidently making them up.- One artifact, one file. Keep CSS and JS inline. The deliverable should open correctly when double-clicked from a desktop.</rules>
How to tune it after pasting
Use it as-is for ~5 conversations.
Each time Claude does something off (wrong format, generic aesthetic, surfaces an essay you didn't want surfaced, asks a clarifying question you wish it hadn't), note the friction and add or amend one rule.
After ~2 weeks, prune anything that hasn't earned its place, rules that don't change behavior are just consuming tokens.
§ 05 / Recommendations
A four-stage rollout
Today · 5 min
01Paste & verify
Paste the Deliverable B draft into the project's "Set project
instructions" field. Verify the html-effectiveness essays and
the claude-md.html essay are uploaded to project
knowledge. Start a new chat and test with a deliberately ambiguous
prompt, confirm Claude defaults to HTML and matches the existing
essays' register.
This week
02Collect friction
Run 5 to 10 real prompts in the project. Each time Claude misses,
write down the specific friction (one sentence). Don't fix
instructions yet: collect data first.
End of week 1
03Edit by data
Edit the instructions based on the collected frictions. Likely
amendments: clarifying when not to ask a clarifying
question; pinning specific typographic conventions if Claude drifts;
adding a rule about handling code samples within HTML artifacts.
Ongoing
04Treat like CLAUDE.md
Review when things go wrong, prune regularly, and add emphasis
("IMPORTANT" or "ALWAYS") to rules Claude keeps
violating. The Claude Code best-practices doc explicitly endorses
this technique.
Threshold · switch strategies
If after two weeks of iteration the instructions are over ~700 words
and Claude is still inconsistent on HTML defaults, that's a signal the
work belongs in a Skill rather than project
instructions. Skills work identically across claude.ai, Claude Code,
and the API, and are the right home for a formal "when to produce
HTML" recognition heuristic: the dogum/html-artifacts skill on
GitHub (v0.1.0, May 9, 2026) is a working prototype to study or fork.
Its README states the design rationale verbatim:
"A skill that mechanically converts every prompt into HTML would
be worse than no skill, it would obscure cases where markdown is the
right answer, and it would calcify into a default-AI aesthetic of
'every artifact is a card with a gradient.'" Project instructions
are for the project-specific context (the editorial style,
the curated library); the format-recognition logic might eventually
graduate to a Skill.
Threshold · revisit the thesis
If you find yourself routinely overriding the HTML default with
"just give me markdown" requests, the carve-out section is
too narrow. Widen it. Thariq's own positioning describes him as
"far on the HTML maximalist side of things": calibrate the
instructions to your maximalism, not his.
§ 06 / Caveats
What this brief doesn't claim
The Thariq tweet does not contain Projects-specific guidance.
Your task framing suggested it might. The essay is about Claude Code
output format and the cases where HTML structurally beats markdown.
The transfer to your project instructions is the taxonomy of cases
(the nine categories) and the philosophy (recognition-driven
defaults with carve-outs), not direct guidance on the Projects feature.
The original X post is not directly fetchable. All
Thariq quotes in this report come from secondary sources that
reproduce verbatim blockquotes (Simon Willison's link blog at
simonwillison.net/2026/May/8/unreasonable-effectiveness-of-html/,
the dogum/html-artifacts README, the html-effectiveness companion site
that Thariq published himself at
thariqs.github.io/html-effectiveness). One secondary source
(pasqualepillitteri.it) misdates the essay to November 8, 2026; the
correct date is May 8, 2026 (confirmed by Simon Willison's post date
and Thariq's own X timeline).
No published character limit for project instructions
as of March 2026, per J.D. Hodges' review and confirmed by the
absence in Anthropic's help docs. Treat ~300 to 500 words as a soft
target driven by token economics, not a hard cap.
Project knowledge is the only state that crosses chats.
Anthropic's help docs are explicit: "Context is not shared across
chats within a project unless the information is added into the
project knowledge base." If you want Claude to remember a
stylistic decision across sessions, upload a one-page style reference
to project knowledge, don't expect it to "learn" from a previous
chat.
The dogum/html-artifacts skill exists and may be
worth studying or installing alongside the project. It is a
third-party formalization of Thariq's heuristic, dated v0.1.0 on
May 9, 2026, one day after Thariq's essay, and its
references/matching-your-style.md is explicitly designed
to head off default-AI aesthetic drift. Installing it gives you the
format-recognition logic at the account level; the project
instructions then handle the project-specific style and content.
The 12-rule CLAUDE.md spec by Mnimiy in your project
knowledge is from May 2026 and is for Claude Code, not
claude.ai Projects. The philosophy transfers; most of the specific
rules don't (no codebase, no tests, no commits in a content/library
project). Don't paste those 12 rules into project instructions
verbatim.