From 247bf2caafc9dd709f6e93bc91baab4b17e91d00 Mon Sep 17 00:00:00 2001 From: Paul Bakaus Date: Sun, 15 Mar 2026 18:27:44 -0700 Subject: [PATCH] refactor: extract shared Context Gathering Protocol for all design skills MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Centralizes the duplicated ~15-line MANDATORY PREPARATION blocks from 10 skills into a single shared reference file in frontend-design. Since all skills already depend on frontend-design, the protocol is automatically available without build system changes. Key changes: - New reference: frontend-design/reference/context-gathering.md with 3-tier gathering: check instructions → check .impeccable.md → auto- invoke teach-impeccable - teach-impeccable now writes to .impeccable.md (provider-agnostic), optionally also to the provider config file - 8 existing MANDATORY PREPARATION blocks replaced with 1-line pointers - 4 skills that lacked context gathering now have it (adapt, clarify, polish, normalize) Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude/skills/adapt/SKILL.md | 6 ++++ .claude/skills/animate/SKILL.md | 15 +-------- .claude/skills/bolder/SKILL.md | 15 +-------- .claude/skills/clarify/SKILL.md | 6 ++++ .claude/skills/colorize/SKILL.md | 15 +-------- .claude/skills/critique/SKILL.md | 8 +++-- .claude/skills/delight/SKILL.md | 31 ++++++------------- .claude/skills/distill/SKILL.md | 15 +-------- .claude/skills/frontend-design/SKILL.md | 2 ++ .../reference/context-gathering.md | 25 +++++++++++++++ .claude/skills/normalize/SKILL.md | 6 ++++ .claude/skills/onboard/SKILL.md | 6 ++++ .claude/skills/polish/SKILL.md | 6 +++- .claude/skills/quieter/SKILL.md | 15 +-------- .claude/skills/teach-impeccable/SKILL.md | 4 ++- source/skills/adapt/SKILL.md | 6 ++++ source/skills/animate/SKILL.md | 15 +-------- source/skills/bolder/SKILL.md | 15 +-------- source/skills/clarify/SKILL.md | 6 ++++ source/skills/colorize/SKILL.md | 15 +-------- source/skills/critique/SKILL.md | 15 +-------- source/skills/delight/SKILL.md | 15 +-------- source/skills/distill/SKILL.md | 15 +-------- source/skills/frontend-design/SKILL.md | 2 ++ .../reference/context-gathering.md | 25 +++++++++++++++ source/skills/normalize/SKILL.md | 6 ++++ source/skills/onboard/SKILL.md | 15 +-------- source/skills/polish/SKILL.md | 6 +++- source/skills/quieter/SKILL.md | 15 +-------- source/skills/teach-impeccable/SKILL.md | 4 ++- 30 files changed, 141 insertions(+), 209 deletions(-) create mode 100644 .claude/skills/frontend-design/reference/context-gathering.md create mode 100644 source/skills/frontend-design/reference/context-gathering.md diff --git a/.claude/skills/adapt/SKILL.md b/.claude/skills/adapt/SKILL.md index 7e11509f7..e2fc9f5ed 100644 --- a/.claude/skills/adapt/SKILL.md +++ b/.claude/skills/adapt/SKILL.md @@ -13,6 +13,12 @@ args: Adapt existing designs to work effectively across different contexts - different screen sizes, devices, platforms, or use cases. +## MANDATORY PREPARATION + +Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. Additionally gather: target platforms/devices and usage contexts. + +--- + ## Assess Adaptation Challenge Understand what needs adaptation and why: diff --git a/.claude/skills/animate/SKILL.md b/.claude/skills/animate/SKILL.md index 5abd7435f..bd49c3267 100644 --- a/.claude/skills/animate/SKILL.md +++ b/.claude/skills/animate/SKILL.md @@ -12,20 +12,7 @@ Analyze a feature and strategically add animations and micro-interactions that e ## MANDATORY PREPARATION -### Context Gathering (Do This First) - -You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), brand personality/tone (playful vs serious, energetic vs calm), and performance constraints. - -Attempt to gather these from the current thread or codebase. - -1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and STOP and call the AskUserQuestionTool to clarify. whether you got it right. -2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST STOP and call the AskUserQuestionTool to clarify. clarifying questions first to complete your context. - -Do NOT proceed until you have answers. Guessing leads to inappropriate or excessive animation. - -### Use frontend-design skill - -Use the frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts. +Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. Additionally gather: performance constraints. --- diff --git a/.claude/skills/bolder/SKILL.md b/.claude/skills/bolder/SKILL.md index a13aa1bc6..503041372 100644 --- a/.claude/skills/bolder/SKILL.md +++ b/.claude/skills/bolder/SKILL.md @@ -12,20 +12,7 @@ Increase visual impact and personality in designs that are too safe, generic, or ## MANDATORY PREPARATION -### Context Gathering (Do This First) - -You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), brand personality/tone, and everything else that a great human designer would need as well. - -Attempt to gather these from the current thread or codebase. - -1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and STOP and call the AskUserQuestionTool to clarify. whether you got it right. -2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST STOP and call the AskUserQuestionTool to clarify. clarifying questions first to complete your context. - -Do NOT proceed until you have answers. Guessing leads to generic AI slop. - -### Use frontend-design skill - -Use the frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts. +Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. --- diff --git a/.claude/skills/clarify/SKILL.md b/.claude/skills/clarify/SKILL.md index 4592a08de..69f18b2e8 100644 --- a/.claude/skills/clarify/SKILL.md +++ b/.claude/skills/clarify/SKILL.md @@ -10,6 +10,12 @@ args: Identify and improve unclear, confusing, or poorly written interface text to make the product easier to understand and use. +## MANDATORY PREPARATION + +Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. Additionally gather: audience technical level and users' mental state in context. + +--- + ## Assess Current Copy Identify what makes the text unclear or ineffective: diff --git a/.claude/skills/colorize/SKILL.md b/.claude/skills/colorize/SKILL.md index 05b15813a..55d9914d8 100644 --- a/.claude/skills/colorize/SKILL.md +++ b/.claude/skills/colorize/SKILL.md @@ -12,20 +12,7 @@ Strategically introduce color to designs that are too monochromatic, gray, or la ## MANDATORY PREPARATION -### Context Gathering (Do This First) - -You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), brand personality/tone, and especially existing brand colors. - -Attempt to gather these from the current thread or codebase. - -1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and STOP and call the AskUserQuestionTool to clarify. whether you got it right. -2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST STOP and call the AskUserQuestionTool to clarify. clarifying questions first to complete your context. - -Do NOT proceed until you have answers. Guessing leads to generic AI slop colors. - -### Use frontend-design skill - -Use the frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts. +Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. Additionally gather: existing brand colors. --- diff --git a/.claude/skills/critique/SKILL.md b/.claude/skills/critique/SKILL.md index 7d3aefad4..8f1a795df 100644 --- a/.claude/skills/critique/SKILL.md +++ b/.claude/skills/critique/SKILL.md @@ -8,9 +8,13 @@ args: required: false --- -Conduct a holistic design critique, evaluating whether the interface actually works—not just technically, but as a designed experience. Think like a design director giving feedback. +## MANDATORY PREPARATION -**First**: Use the frontend-design skill for design principles and anti-patterns. +Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. Additionally gather: what the interface is trying to accomplish. + +--- + +Conduct a holistic design critique, evaluating whether the interface actually works—not just technically, but as a designed experience. Think like a design director giving feedback. ## Design Critique diff --git a/.claude/skills/delight/SKILL.md b/.claude/skills/delight/SKILL.md index 6106d4d71..75e731268 100644 --- a/.claude/skills/delight/SKILL.md +++ b/.claude/skills/delight/SKILL.md @@ -12,20 +12,7 @@ Identify opportunities to add moments of joy, personality, and unexpected polish ## MANDATORY PREPARATION -### Context Gathering (Do This First) - -You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), brand personality (playful vs professional vs quirky vs elegant), and what's appropriate for the domain. - -Attempt to gather these from the current thread or codebase. - -1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and STOP and call the AskUserQuestionTool to clarify. whether you got it right. -2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST STOP and call the AskUserQuestionTool to clarify. clarifying questions first to complete your context. - -Do NOT proceed until you have answers. Delight that's wrong for the context is worse than no delight at all. - -### Use frontend-design skill - -Use the frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts. +Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. Additionally gather: what's appropriate for the domain (playful vs professional vs quirky vs elegant). --- @@ -113,7 +100,7 @@ Add personality and joy through these methods: **Loading delight**: - Playful loading animations (not just spinners) -- Personality in loading messages ("Herding pixels..." "Teaching robots to dance...") +- Personality in loading messages (write product-specific ones, not generic AI filler) - Progress indication with encouraging messages - Skeleton screens with subtle animations @@ -203,7 +190,7 @@ Add personality and joy through these methods: **Form interactions**: - Input fields that animate on focus -- Checkboxes that bounce when checked +- Checkboxes with a satisfying scale pulse when checked - Success state that celebrates valid input - Auto-grow textareas @@ -253,13 +240,15 @@ Add personality and joy through these methods: - Countdown with encouraging messages ``` -Loading messages rotation: -- "Waking up the servers..." -- "Teaching robots to dance..." -- "Consulting the magic 8-ball..." -- "Counting backwards from infinity..." +Loading messages — write ones specific to your product, not generic AI filler: +- "Crunching your latest numbers..." +- "Syncing with your team's changes..." +- "Preparing your dashboard..." +- "Checking for updates since yesterday..." ``` +**WARNING**: Avoid cliched loading messages like "Herding pixels", "Teaching robots to dance", "Consulting the magic 8-ball", "Counting backwards from infinity". These are AI-slop copy — instantly recognizable as machine-generated. Write messages that are specific to what your product actually does. + ### Celebration Moments **Success celebrations**: diff --git a/.claude/skills/distill/SKILL.md b/.claude/skills/distill/SKILL.md index b9f0ddf28..5f4ecce0e 100644 --- a/.claude/skills/distill/SKILL.md +++ b/.claude/skills/distill/SKILL.md @@ -12,20 +12,7 @@ Remove unnecessary complexity from designs, revealing the essential elements and ## MANDATORY PREPARATION -### Context Gathering (Do This First) - -You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), and understanding what's truly essential vs nice-to-have for this product. - -Attempt to gather these from the current thread or codebase. - -1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and STOP and call the AskUserQuestionTool to clarify. whether you got it right. -2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST STOP and call the AskUserQuestionTool to clarify. clarifying questions first to complete your context. - -Do NOT proceed until you have answers. Simplifying the wrong things destroys usability. - -### Use frontend-design skill - -Use the frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts. +Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. Additionally gather: what's truly essential vs nice-to-have for this product. --- diff --git a/.claude/skills/frontend-design/SKILL.md b/.claude/skills/frontend-design/SKILL.md index c78cca7e0..aae260b01 100644 --- a/.claude/skills/frontend-design/SKILL.md +++ b/.claude/skills/frontend-design/SKILL.md @@ -6,6 +6,8 @@ license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md f This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. +→ *Before starting, follow the [context gathering protocol](reference/context-gathering.md) to ensure you have project context.* + ## Design Direction Commit to a BOLD aesthetic direction: diff --git a/.claude/skills/frontend-design/reference/context-gathering.md b/.claude/skills/frontend-design/reference/context-gathering.md new file mode 100644 index 000000000..8f39429e5 --- /dev/null +++ b/.claude/skills/frontend-design/reference/context-gathering.md @@ -0,0 +1,25 @@ +# Context Gathering Protocol + +Design skills produce generic output without project context. Follow this protocol to gather what you need before proceeding. + +## Required context + +Every design skill needs at minimum: +- **Target audience**: Who uses this product and in what context? +- **Use cases**: What jobs are they trying to get done? +- **Brand personality/tone**: How should the interface feel? + +Individual skills may require additional context — check the skill's preparation section for specifics. + +## Gathering order + +### 1. Check current instructions (instant) +If your loaded instructions already contain a **Design Context** section with the required information, you have what you need — proceed immediately. + +### 2. Check .impeccable.md (fast) +If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed. + +### 3. Run teach-impeccable (cold start) +If neither source has context, run the teach-impeccable skill before continuing. It will gather context interactively and persist it to `.impeccable.md` for all future sessions. + +Do NOT proceed with design work until you have confirmed context. diff --git a/.claude/skills/normalize/SKILL.md b/.claude/skills/normalize/SKILL.md index e1a986b6e..f6537b863 100644 --- a/.claude/skills/normalize/SKILL.md +++ b/.claude/skills/normalize/SKILL.md @@ -10,6 +10,12 @@ args: Analyze and redesign the feature to perfectly match our design system standards, aesthetics, and established patterns. +## MANDATORY PREPARATION + +Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. Additionally gather: design system documentation and tokens. + +--- + ## Plan Before making changes, deeply understand the context: diff --git a/.claude/skills/onboard/SKILL.md b/.claude/skills/onboard/SKILL.md index 120f74357..bba8dfadb 100644 --- a/.claude/skills/onboard/SKILL.md +++ b/.claude/skills/onboard/SKILL.md @@ -8,6 +8,12 @@ args: required: false --- +## MANDATORY PREPARATION + +Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. Additionally gather: the "aha moment" you want users to reach, and users' experience level. + +--- + Create or improve onboarding experiences that help users understand, adopt, and succeed with the product quickly. ## Assess Onboarding Needs diff --git a/.claude/skills/polish/SKILL.md b/.claude/skills/polish/SKILL.md index 50c8fb499..98d8b6250 100644 --- a/.claude/skills/polish/SKILL.md +++ b/.claude/skills/polish/SKILL.md @@ -8,7 +8,11 @@ args: required: false --- -**First**: Use the frontend-design skill for design principles and anti-patterns. +## MANDATORY PREPARATION + +Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. Additionally gather: quality bar (MVP vs flagship) and shipping timeline. + +--- Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished. diff --git a/.claude/skills/quieter/SKILL.md b/.claude/skills/quieter/SKILL.md index def796a4f..3e890074e 100644 --- a/.claude/skills/quieter/SKILL.md +++ b/.claude/skills/quieter/SKILL.md @@ -12,20 +12,7 @@ Reduce visual intensity in designs that are too bold, aggressive, or overstimula ## MANDATORY PREPARATION -### Context Gathering (Do This First) - -You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), brand personality/tone, and everything else that a great human designer would need as well. - -Attempt to gather these from the current thread or codebase. - -1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and STOP and call the AskUserQuestionTool to clarify. whether you got it right. -2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST STOP and call the AskUserQuestionTool to clarify. clarifying questions first to complete your context. - -Do NOT proceed until you have answers. Guessing leads to generic design. - -### Use frontend-design skill - -Use the frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts. +Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. --- diff --git a/.claude/skills/teach-impeccable/SKILL.md b/.claude/skills/teach-impeccable/SKILL.md index 2ac070a53..214c0041c 100644 --- a/.claude/skills/teach-impeccable/SKILL.md +++ b/.claude/skills/teach-impeccable/SKILL.md @@ -64,6 +64,8 @@ Synthesize your findings and the user's answers into a `## Design Context` secti [3-5 principles derived from the conversation that should guide all design decisions] ``` -Write this section to CLAUDE.md in the project root. If the file exists, append or update the Design Context section. +Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place. + +Then STOP and call the AskUserQuestionTool to clarify. whether they'd also like the Design Context appended to CLAUDE.md. If yes, append or update the section there as well. Confirm completion and summarize the key design principles that will now guide all future work. \ No newline at end of file diff --git a/source/skills/adapt/SKILL.md b/source/skills/adapt/SKILL.md index 9bbea89d0..5091a47be 100644 --- a/source/skills/adapt/SKILL.md +++ b/source/skills/adapt/SKILL.md @@ -13,6 +13,12 @@ user-invokable: true Adapt existing designs to work effectively across different contexts - different screen sizes, devices, platforms, or use cases. +## MANDATORY PREPARATION + +Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. Additionally gather: target platforms/devices and usage contexts. + +--- + ## Assess Adaptation Challenge Understand what needs adaptation and why: diff --git a/source/skills/animate/SKILL.md b/source/skills/animate/SKILL.md index c6563c15e..275bcb300 100644 --- a/source/skills/animate/SKILL.md +++ b/source/skills/animate/SKILL.md @@ -12,20 +12,7 @@ Analyze a feature and strategically add animations and micro-interactions that e ## MANDATORY PREPARATION -### Context Gathering (Do This First) - -You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), brand personality/tone (playful vs serious, energetic vs calm), and performance constraints. - -Attempt to gather these from the current thread or codebase. - -1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and {{ask_instruction}} whether you got it right. -2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST {{ask_instruction}} clarifying questions first to complete your context. - -Do NOT proceed until you have answers. Guessing leads to inappropriate or excessive animation. - -### Use frontend-design skill - -Use the frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts. +Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. Additionally gather: performance constraints. --- diff --git a/source/skills/bolder/SKILL.md b/source/skills/bolder/SKILL.md index 4ae1d73c3..2f7e1196b 100644 --- a/source/skills/bolder/SKILL.md +++ b/source/skills/bolder/SKILL.md @@ -12,20 +12,7 @@ Increase visual impact and personality in designs that are too safe, generic, or ## MANDATORY PREPARATION -### Context Gathering (Do This First) - -You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), brand personality/tone, and everything else that a great human designer would need as well. - -Attempt to gather these from the current thread or codebase. - -1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and {{ask_instruction}} whether you got it right. -2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST {{ask_instruction}} clarifying questions first to complete your context. - -Do NOT proceed until you have answers. Guessing leads to generic AI slop. - -### Use frontend-design skill - -Use the frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts. +Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. --- diff --git a/source/skills/clarify/SKILL.md b/source/skills/clarify/SKILL.md index c39e4f73f..82964bd4a 100644 --- a/source/skills/clarify/SKILL.md +++ b/source/skills/clarify/SKILL.md @@ -10,6 +10,12 @@ user-invokable: true Identify and improve unclear, confusing, or poorly written interface text to make the product easier to understand and use. +## MANDATORY PREPARATION + +Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. Additionally gather: audience technical level and users' mental state in context. + +--- + ## Assess Current Copy Identify what makes the text unclear or ineffective: diff --git a/source/skills/colorize/SKILL.md b/source/skills/colorize/SKILL.md index 905782fb5..aeed419a5 100644 --- a/source/skills/colorize/SKILL.md +++ b/source/skills/colorize/SKILL.md @@ -12,20 +12,7 @@ Strategically introduce color to designs that are too monochromatic, gray, or la ## MANDATORY PREPARATION -### Context Gathering (Do This First) - -You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), brand personality/tone, and especially existing brand colors. - -Attempt to gather these from the current thread or codebase. - -1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and {{ask_instruction}} whether you got it right. -2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST {{ask_instruction}} clarifying questions first to complete your context. - -Do NOT proceed until you have answers. Guessing leads to generic AI slop colors. - -### Use frontend-design skill - -Use the frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts. +Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. Additionally gather: existing brand colors. --- diff --git a/source/skills/critique/SKILL.md b/source/skills/critique/SKILL.md index 26c07f591..270488cb5 100644 --- a/source/skills/critique/SKILL.md +++ b/source/skills/critique/SKILL.md @@ -10,20 +10,7 @@ user-invokable: true ## MANDATORY PREPARATION -### Context Gathering (Do This First) - -You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), brand personality/tone, and what the interface is trying to accomplish. - -Attempt to gather these from the current thread or codebase. - -1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and {{ask_instruction}} whether you got it right. -2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST {{ask_instruction}} clarifying questions first to complete your context. - -Do NOT proceed until you have answers. Critique without context produces generic feedback. - -### Use frontend-design skill - -Use the frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts. +Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. Additionally gather: what the interface is trying to accomplish. --- diff --git a/source/skills/delight/SKILL.md b/source/skills/delight/SKILL.md index efc2d87ec..8f9c77220 100644 --- a/source/skills/delight/SKILL.md +++ b/source/skills/delight/SKILL.md @@ -12,20 +12,7 @@ Identify opportunities to add moments of joy, personality, and unexpected polish ## MANDATORY PREPARATION -### Context Gathering (Do This First) - -You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), brand personality (playful vs professional vs quirky vs elegant), and what's appropriate for the domain. - -Attempt to gather these from the current thread or codebase. - -1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and {{ask_instruction}} whether you got it right. -2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST {{ask_instruction}} clarifying questions first to complete your context. - -Do NOT proceed until you have answers. Delight that's wrong for the context is worse than no delight at all. - -### Use frontend-design skill - -Use the frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts. +Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. Additionally gather: what's appropriate for the domain (playful vs professional vs quirky vs elegant). --- diff --git a/source/skills/distill/SKILL.md b/source/skills/distill/SKILL.md index 6ff81ad0e..bd954c9fc 100644 --- a/source/skills/distill/SKILL.md +++ b/source/skills/distill/SKILL.md @@ -12,20 +12,7 @@ Remove unnecessary complexity from designs, revealing the essential elements and ## MANDATORY PREPARATION -### Context Gathering (Do This First) - -You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), and understanding what's truly essential vs nice-to-have for this product. - -Attempt to gather these from the current thread or codebase. - -1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and {{ask_instruction}} whether you got it right. -2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST {{ask_instruction}} clarifying questions first to complete your context. - -Do NOT proceed until you have answers. Simplifying the wrong things destroys usability. - -### Use frontend-design skill - -Use the frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts. +Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. Additionally gather: what's truly essential vs nice-to-have for this product. --- diff --git a/source/skills/frontend-design/SKILL.md b/source/skills/frontend-design/SKILL.md index d0c1173ca..c1a6d4115 100644 --- a/source/skills/frontend-design/SKILL.md +++ b/source/skills/frontend-design/SKILL.md @@ -6,6 +6,8 @@ license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md f This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. +→ *Before starting, follow the [context gathering protocol](reference/context-gathering.md) to ensure you have project context.* + ## Design Direction Commit to a BOLD aesthetic direction: diff --git a/source/skills/frontend-design/reference/context-gathering.md b/source/skills/frontend-design/reference/context-gathering.md new file mode 100644 index 000000000..8f39429e5 --- /dev/null +++ b/source/skills/frontend-design/reference/context-gathering.md @@ -0,0 +1,25 @@ +# Context Gathering Protocol + +Design skills produce generic output without project context. Follow this protocol to gather what you need before proceeding. + +## Required context + +Every design skill needs at minimum: +- **Target audience**: Who uses this product and in what context? +- **Use cases**: What jobs are they trying to get done? +- **Brand personality/tone**: How should the interface feel? + +Individual skills may require additional context — check the skill's preparation section for specifics. + +## Gathering order + +### 1. Check current instructions (instant) +If your loaded instructions already contain a **Design Context** section with the required information, you have what you need — proceed immediately. + +### 2. Check .impeccable.md (fast) +If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed. + +### 3. Run teach-impeccable (cold start) +If neither source has context, run the teach-impeccable skill before continuing. It will gather context interactively and persist it to `.impeccable.md` for all future sessions. + +Do NOT proceed with design work until you have confirmed context. diff --git a/source/skills/normalize/SKILL.md b/source/skills/normalize/SKILL.md index b818d8603..464ba23f7 100644 --- a/source/skills/normalize/SKILL.md +++ b/source/skills/normalize/SKILL.md @@ -10,6 +10,12 @@ user-invokable: true Analyze and redesign the feature to perfectly match our design system standards, aesthetics, and established patterns. +## MANDATORY PREPARATION + +Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. Additionally gather: design system documentation and tokens. + +--- + ## Plan Before making changes, deeply understand the context: diff --git a/source/skills/onboard/SKILL.md b/source/skills/onboard/SKILL.md index f11e88d4f..9517d59dd 100644 --- a/source/skills/onboard/SKILL.md +++ b/source/skills/onboard/SKILL.md @@ -10,20 +10,7 @@ user-invokable: true ## MANDATORY PREPARATION -### Context Gathering (Do This First) - -You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), the "aha moment" you want users to reach, and what users' experience level and motivation looks like. - -Attempt to gather these from the current thread or codebase. - -1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and {{ask_instruction}} whether you got it right. -2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST {{ask_instruction}} clarifying questions first to complete your context. - -Do NOT proceed until you have answers. Onboarding designed for the wrong audience wastes everyone's time. - -### Use frontend-design skill - -Use the frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts. +Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. Additionally gather: the "aha moment" you want users to reach, and users' experience level. --- diff --git a/source/skills/polish/SKILL.md b/source/skills/polish/SKILL.md index ff4aa5312..33ea34487 100644 --- a/source/skills/polish/SKILL.md +++ b/source/skills/polish/SKILL.md @@ -8,7 +8,11 @@ args: user-invokable: true --- -**First**: Use the frontend-design skill for design principles and anti-patterns. +## MANDATORY PREPARATION + +Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. Additionally gather: quality bar (MVP vs flagship). + +--- Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished. diff --git a/source/skills/quieter/SKILL.md b/source/skills/quieter/SKILL.md index aa59a9671..c2e028628 100644 --- a/source/skills/quieter/SKILL.md +++ b/source/skills/quieter/SKILL.md @@ -12,20 +12,7 @@ Reduce visual intensity in designs that are too bold, aggressive, or overstimula ## MANDATORY PREPARATION -### Context Gathering (Do This First) - -You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), brand personality/tone, and everything else that a great human designer would need as well. - -Attempt to gather these from the current thread or codebase. - -1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and {{ask_instruction}} whether you got it right. -2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST {{ask_instruction}} clarifying questions first to complete your context. - -Do NOT proceed until you have answers. Guessing leads to generic design. - -### Use frontend-design skill - -Use the frontend-design skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts. +Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding. --- diff --git a/source/skills/teach-impeccable/SKILL.md b/source/skills/teach-impeccable/SKILL.md index 18f5479f5..64a7a1b73 100644 --- a/source/skills/teach-impeccable/SKILL.md +++ b/source/skills/teach-impeccable/SKILL.md @@ -64,6 +64,8 @@ Synthesize your findings and the user's answers into a `## Design Context` secti [3-5 principles derived from the conversation that should guide all design decisions] ``` -Write this section to {{config_file}} in the project root. If the file exists, append or update the Design Context section. +Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place. + +Then {{ask_instruction}} whether they'd also like the Design Context appended to {{config_file}}. If yes, append or update the section there as well. Confirm completion and summarize the key design principles that will now guide all future work.