showing-work
Skill2 starsChanged 11 days agoMITView on GitHub
Use whenever a page, post, outline, slide or tile has to present a piece of design work someone made, in any language and any words - "write up my redesign as a case study", "make a project or launch page for the component I built", "how do I show these interactions to reviewers", "my portfolio entry is boring", "does this case-study outline work". Covers what the first screen shows, the spine of sections, the rhythm of claims and proof, figures and captions, how to show motion and before and after, and how to end, and gives a lean answer when the format is only a tile or one slide. Not for a customer story told to sell a product (landing-page-copy), the structure of a talk or deck (presentation-design), faux product interfaces inside demos, or page grids and emphasis on their own (layout-structure, visual-hierarchy).
In this repository25 other files it gives its agents.
- agent-interface-designSkill
- brand-identitySkill
- chart-designSkill
- color-paletteSkill
- data-tablesSkill
- design-critiqueSkill
- design-system-builderSkill
- form-designSkill
- generated-ui-restyleSkill
- interface-behaviorSkill
- journey-and-service-mappingSkill
- layout-structureSkill
- practice-and-assessmentSkill
- presentation-designSkill
- pricing-and-packagingSkill
- responsive-layoutSkill
- sales-conversationsSkill
- spacing-and-groupingSkill
- teaching-interfacesSkill
- typeface-selectionSkill
- typesettingSkill
- ui-motionSkill
- ui-polish-passSkill
- user-research-basicsSkill
- visual-hierarchySkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 7 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 60
Metrics: Default: put a supplied result next to the decision it came from, with how it was measured.
- Distinctive: line 61
Process: Default: keep it inside the decision it explains.
- Distinctive: line 62
Length: Default: one section per decision.
- Distinctive: line 63
Demo or still: Default: a running demo when the work is interactive and can run in the page.
- Very specific: line 64
Credits: Default: name the people the person lists, with what each did.
- Distinctive: line 65
Voice: Default: first person and plain, candid about limits, which reads as more credible than polish.
- Distinctive: line 77
Read only the section titles: does each one state a decision?
- Distinctive: line 79
Every clip can be replayed and slowed, and none autoplays under reduced motion.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Showing work
A page about a piece of work does its job when a stranger sees the work in the first screen, learns the two or three decisions that made it good, and believes each one because it is shown. Left alone, write-ups follow the project's calendar: overview, research, personas, wireframes, final screens, thanks. They open on backstory, hide the work below the fold, and stack screenshots that prove nothing in particular.
Do not produce
- A first screen made of backstory, a role-and-timeline table, a mission statement or a banner with no work in it.
- Section titles named after process phases (Research, Ideation, Testing) when the reader came for the decisions.
- Walls of text, or runs of images with no claim attached to them.
- Captions that repeat the paragraph above them or only name the picture ("Screenshot of the home screen").
- Motion offered as one fast autoplaying clip with no way to replay or slow it.
- An outcome, metric, quote, testimonial, award or credit the person did not supply. Where the page needs one, leave a clearly bracketed placeholder such as
[result: how it was measured, and the number]and say what to fill in. Example figures in suggested copy are bracketed too, never plausible numbers. - The full page structure on something that is not a page: a grid tile, a thumbnail or a single slide.
When to use
- A case study, project page, launch post, component page or "how we built it" write-up for work someone designed or built.
- A portfolio entry, or an outline, rewrite or critique of any of these.
- A question about how to show motion, interactions or a redesign so that reviewers can see what changed.
- One tile, card or slide that stands in for such work (use the lean form below).
When not to use
- A customer's story told to sell a product: landing-page-copy, if installed.
- A talk or deck as a whole, its order and its timing: presentation-design, if installed. A single slide that presents design work is covered here in its lean form.
- Faux product interfaces built inside a demo are out of scope here.
- Page grids and reading measure: layout-structure. Which element is loudest: visual-hierarchy. Headline wording alone: headlines-and-leads. Each skill if installed.
- A one-line change ("add a caption to this figure") gets that change and nothing else.
- Explicit user instructions, an existing site template and a stated house style win. Apply what fits inside them.
Size the job first
| Asked for | Give |
| A page, post or full outline | Everything under Method. |
| A grid tile or card | The work (or its strongest still), a title, and one line saying what it is. No sections, no narrative. |
| One slide | One message as the title, the work as the visual, at most one supporting line. The talk's order belongs to presentation-design. |
| A tool, library or component page | A definition with its facts, the working demo, install, options, limits. Follow the demo-first part of step 1 and skip the decision spine unless the person asks for a story. |
| A critique of an existing write-up | Judge it against Method, name what already works, and give the rebuilt spine. |
Method
- First screen: the work. Name, then one plain sentence saying what it is with two to four concrete facts (what it does, for whom, on what platform, at what scale or under which constraint), then the work itself: a live demo, a clip or the single strongest image. Why it was made comes next, in one short paragraph. If the work cannot run in the page, the strongest still goes where the demo would.
- Spine: decisions, not phases. Find the two to four decisions or principles the work stands on and state them early. Give each its own section, titled with the decision and its means ("Fewer steps by editing in place"). Research and process appear inside a section only where they explain a decision.
- Claim, then proof. Each short paragraph, roughly 15 to 60 words, makes one claim, and the figure that proves it follows directly. Two figures in a row only when they are a deliberate pair. A figure that proves nothing is cut.
- Figures. One frame style and one column. Span the text column, or go clearly wider; never a little wider. Leave more space below a captioned figure than above it, and reserve each figure's box before it loads so the page does not jump.
- Captions. One sentence in the present tense that says what happens, or what the image cannot show: the condition, the number, the platform. When the paragraph already says it, there is no caption.
- Motion as content. A clip plays while in view and pauses out of view. It has replay and a slow-motion control, and the still shown before play is the result, not a mid-transition frame. To claim motion helps, show the same flow with it and without it. Under reduced motion, show the still with a play control and do not autoplay. When a page holds many such pieces, run only the ones near the viewport.
- Before and after. Quote the brief or the problem first. Show both versions at the same width, label each side, and pin each fault to the spot on the old version with a few words, so the reader does not have to hunt for the difference.
- The end. What did not work or is still limited, credits (only names supplied), and the one action the page wants, repeated from the top: try it, install it, read the code, get in touch. Asides go to footnotes or margin notes, and nothing the reader needs is only in an aside.
- A long page gets an on-this-page list beside the text on wide screens, which becomes an inline list on narrow ones (never nothing), and a way back to the index.
Judgment calls
- Metrics. Default: put a supplied result next to the decision it came from, with how it was measured. Change when none was supplied: describe what was observed or what the person can verify, and leave a bracketed placeholder for the number.
- Process. Default: keep it inside the decision it explains. Change when the process is the work (a research study): then the spine is the questions asked and what each answer changed.
- Length. Default: one section per decision. A small piece with one decision is one section; do not invent a second to fill the template.
- Demo or still. Default: a running demo when the work is interactive and can run in the page. Change to a still, or a clip with a poster frame, when it cannot, or when a live one would need setup the reader will not do.
- Credits. Default: name the people the person lists, with what each did. Change when no one is named: write
[credits: names and roles]and do not guess who worked on it. - Voice. Default: first person and plain, candid about limits, which reads as more credible than polish. Change to the house voice when the person has one.
Output
- A page request returns the page or the full outline, not advice about one. A build comes back as one self-contained file, the work visible in the first viewport.
- An outline lists section titles as decisions, and under each the claim, the proof it needs and the caption, so the person can collect the right material.
- A critique opens with what works, then the findings in the order they cost the reader, each with a concrete fix, then the rebuilt spine.
- Missing material is named in a short list at the end: each bracketed placeholder and what would fill it.
Quick checks
- Cover everything below the first screen: can a stranger say what the work is and see it?
- Read only the section titles: does each one state a decision?
- Each figure has a claim just before it, and each caption adds a fact the paragraph lacks.
- Every clip can be replayed and slowed, and none autoplays under reduced motion.
- The page ends with limits, credits and one action, and every number, quote and name came from the person or sits in brackets.
- A tile or slide stayed a tile or slide.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

