Skip to content

Agent skills for useful HTML artifacts, wireframes, interactive prototypes, plans, and diagrams.

Position the repository as reference first (#20)

Michael Ramosb869152f3509
diff --git a/README.md b/README.md
index d5fe4af..bd91b30 100644
--- a/README.md
+++ b/README.md
@@ -4,8 +4,22 @@
# Effective HTML
-Six skills for creating useful, self-contained HTML artifacts, from creative direction and low-fidelity wireframes to working interactive prototypes.
+Effective HTML is a field guide and reference collection for creating useful,
+self-contained HTML artifacts with agents.
+## Fat artifacts + fat context
+
+A **fat artifact** carries the working detail: structure, visuals, states,
+interactions, annotations, and evidence. **Fat context** gives the agent the
+source material it needs to understand the real problem: the brief, code,
+constraints, examples, and accepted decisions. The prompt and skills can stay
+thin because the context and the artifact do the work.
+
+> [!NOTE]
+> You can use this repo without installing anything. Treat it as a reference
+> first and an installable skill collection second. Read the patterns, borrow
+> what fits, and ask your agent for the artifact directly. Install a skill only
+> when you want a recurring workflow or shared defaults.
https://github.com/user-attachments/assets/24306977-7f30-44c9-9bff-55f901d557b0
@@ -18,10 +32,9 @@ https://github.com/user-attachments/assets/24306977-7f30-44c9-9bff-55f901d557b0
Render and annotate local HTML with <a href="https://github.com/backnotprop/plannotator">Plannotator</a>.
</p>
-## Choose a skill
-
-HTML skills for pragmatic visual artifacts.
+## Skill references
+The repo includes six optional skills for pragmatic visual artifacts.
| Skill | Use it for |
| --- | --- |
@@ -37,7 +50,8 @@ Visit: <a href="https://www.effectivehtml.com/">Effective HTML Website/Guide</a>
## Install
-Install the collection:
+Install the collection when you want these references available to your agent as
+reusable workflows:
```bash
npx skills add plannotator/effective-html
diff --git a/site/content/docs/index.mdx b/site/content/docs/index.mdx
index b5d9f85..993a5d9 100644
--- a/site/content/docs/index.mdx
+++ b/site/content/docs/index.mdx
@@ -13,11 +13,12 @@ You do not need to install a skill to use these patterns. Ask an agent to make
an HTML artifact, provide the source context and the decision it needs to
support, then review the result.
-The working bias is **fat artifacts and source context; thin prompts and
-skills**. Put the detail in the artifact: realistic content, constraints,
-annotations, states, and interactions. Use a skill when a pattern recurs or a
-team needs shared defaults. Once the pattern is familiar, the skill may stop
-adding value.
+The working bias is **fat artifacts + fat context**. Give the agent the real
+brief, source material, constraints, examples, and accepted decisions. Let the
+artifact carry the working detail through realistic content, annotations,
+states, and interactions. The prompt and skills can stay thin. Use a skill when
+a pattern recurs or a team needs shared defaults; once the pattern is familiar,
+the skill may stop adding value.
HTML is useful with agents because it can combine structure, visual form, and
interaction in one inspectable thing.