> make me a portfolio, my name is Julio

That's the whole brief. The agent works as creative director, designer and creative developer
in one, then hands back a site it has already checked in a real browser.

Quick start

npx skills add wheresryan22/anatomy -g   # optional: interactive isometric explainer figures
npx skills add juliobsz/skills -g

Open a new agent session, then type /awwwards or just ask for a website.

Demo

https://github.com/user-attachments/assets/0ac28c25-9796-4bce-8fa6-4dcc6df55b8b

Install

Install with the skills CLI. It runs through npx, so
there's nothing to install first, and it detects your agents (Claude Code, Codex, Cursor,
Gemini CLI, OpenCode, Copilot and more) and lets you pick.

npx skills add juliobsz/skills -g

Command	Result
npx skills add juliobsz/skills -g -a claude-code	Claude Code only (use codex, cursor… for others)
npx skills add juliobsz/skills	This project only, instead of your user folder
npx skills add juliobsz/skills -g --copy	Copy the files instead of linking them
npx skills update -g	Update to the latest version
npx skills remove awwwards -g	Uninstall

The CLI collects anonymous usage data. Set DISABLE_TELEMETRY=1 or DO_NOT_TRACK=1 to turn
it off.

Claude Code plugin

If you prefer Claude Code's plugin system, which updates the skill for you:

/plugin install awwwards --marketplace juliobsz/skills

On Claude Code before 2.1.275, run /plugin marketplace add juliobsz/skills and then
/plugin install awwwards@juliobsz. The skill then runs as /awwwards:awwwards. Use the
plugin or the skills CLI, not both, or the skill shows up twice.

Manual install

Copy the awwwards/ folder into your agent's skills directory, for example
~/.claude/skills/awwwards. Any agent that reads SKILL.md skills can use it.

Works with /anatomy

/anatomy by wheresryan22 is an open-source skill
for detailed, interactive isometric figures that explain an idea as a real physical object.
Install it next to /awwwards and the site can get one "how it works" section built as a real
explainer figure, styled to the site's palette and grid.

npx skills add wheresryan22/anatomy -g

It's optional. Without it, /awwwards builds that section another way, and tells you at the
end when a figure would have helped.

Requirements

• Node 22.20+ for the skills CLI. The helper scripts need Node 20+.
• Playwright in the site's project for screenshots and the OG image. The skill installs it
  as a dev dependency when it needs it, and uses a Chromium you already have when it can.
• A model that can read images, so the QA loop can look at its own screenshots.
• A Vercel, Netlify or Cloudflare account only if you want it to deploy.

Troubleshooting

• /awwwards isn't found. Start a new session; agents read their skills folder at startup.
  Then run npx skills list -g to see where it was installed.
• It shows up twice. You installed it two ways (for example the skills CLI and the plugin).
  Remove one with npx skills remove awwwards -g or /plugin uninstall awwwards@juliobsz.
• Installed into the wrong agent. Name the target with -a, for example -a codex.
• Screenshots fail with "Playwright not found". Run npm i -D playwright in the site's
  project. If it reports no Chromium, run npx playwright install chromium once.

Why

Ask an agent for "a portfolio" and you get the same site everyone gets: purple gradient, three
cards, "elevate your brand". This skill replaces that default with a process.

• A concept that belongs to you. Three ideas from different territories (your name, your
  craft, your place), scored on originality and fit.
• A real design system. Palette by role, curated free fonts, grid and motion language,
  written to DESIGN.md and tested against a "genericness check".
• Motion with intent. GSAP, Lenis and WebGL (OGL) where they earn their place, with one
  signature moment and everything else quiet.
• Real copy. No lorem ipsum, fake awards or invented metrics. Anything made up is marked
  as a placeholder and listed at the end.
• Verified, not assumed. A production build, a crawling audit and real-browser screenshots
  on desktop, mobile and reduced motion, scored against a rubric until every category hits 8/10.

Its quality bar is the work that wins Awwwards Site of the Day. The
site doesn't need to be submitted anywhere; it just has to be that good.

Usage

Ask in one line and let the agent decide. It writes its assumptions down instead of running a
questionnaire.

make me a portfolio, my name is Ana
a site for my architecture studio in Lisbon, we do small houses
launch page for a mechanical keyboard called Kestrel, it should feel insane
redesign this landing page so it could win site of the day

Better input gives a better site. Your real name, what you do, where you are and two or three
real projects let the concept come from your story instead of a placeholder.

How it works

Phase	What happens
Brief	Infers who it's for, the audience and the site's job. Missing facts become written assumptions
Concept	Three concepts from different territories (your name, your craft's materials, your place, how you work, a formal system), scored on originality and fit. The winner becomes a one-line idea with a signature moment
Art direction	Palette by role, type pairing from a curated free-font library, grid, rhythm and motion language, all written to DESIGN.md. Then a "genericness test" kills anything an average model would have produced
Build	Semantic HTML that looks finished with motion off. Then reveals, page transitions, a loader that tracks real loading, and the signature moment
QA loop	Production build, a crawling audit (SEO, metadata, accessibility, weight, placeholder copy, AI-copy tells) and real-browser screenshots on desktop, mobile, reduced motion and mid-transition. The agent reads every frame, scores itself against the rubric and fixes things until every category hits 8/10
Ship	OG image, favicon, sitemap, robots, then deploy to Vercel, Netlify or Cloudflare (only after you confirm)

Stack

• Next.js (App Router) by default, and for anything with app features.
• Astro for content-only showcases where motion is the product: about 75 KB of JS against
  about 250 KB.
• Your stack when you run it inside an existing project.

All three use GSAP (every plugin is free now), Lenis
for smooth scroll and OGL for WebGL. The motion engine is
framework-agnostic TypeScript, shipped as documented code instead of a template: it runs on
one clock, reverts every effect on navigation, runs transitions in parallel with the next page
loading, and keeps content visible without JavaScript or with reduced motion.

Principles it won't break

• One idea, one signature moment, everything else quiet.
• Every frame works as a still poster before any motion is added.
• The native cursor stays. Reduced motion gets a complete, calm site. Phones get a composed
  layout, not a shrunken one.
• No fake awards, logos or metrics. No lorem ipsum. No em dashes or "elevate your brand" copy.
• No purple gradients, glassmorphism or three-card grids unless the concept truly calls for
  them.

Limits

• It takes a while. A full run is concept, design system, build and several rounds of
  screenshots and fixes. Expect a long session and heavy token use, not a quick snippet.
• Results depend on the model. It was built and tested with Claude Code and Codex. The
  concept and the visual QA are only as good as the model doing them.
• Content is yours to finish. Without real projects, photos and copy, the site ships with
  clearly marked placeholders that you replace.
• 8/10 is its own score. The rubric keeps it honest, but you're the final judge.

Standalone scripts

The helpers in awwwards/scripts/ work on any site, so you can use them on their own:

node ~/.claude/skills/awwwards/scripts/audit.mjs https://your-site.com/
node ~/.claude/skills/awwwards/scripts/shoot.mjs https://your-site.com/ --nav

Script	Does
audit.mjs	Crawl a build: SEO, a11y, weight, placeholders, AI-copy tells
shoot.mjs	Playwright screenshots, FPS, overflow, tap targets, transitions (needs Playwright)
og.mjs	Render the OG image from the live hero (needs Playwright)
font.mjs	Self-host Fontshare / Google fonts (CSS or next/font output)
photos.mjs	Contact sheets of free photos for marked placeholders
serve.mjs	Static server for build output

Repository layout

awwwards/
  SKILL.md            the workflow and the hard rules
  references/
    quality-bar.md    scoring weights, real winner scores, self-score rubric
    concepts.md       finding an idea that can't be moved to someone else
    art-direction.md  patterns from recent winners, archetypes, AI defaults to avoid
    typography.md     curated free fonts with sources, scales, setting display type
    layout.md         grids, section families, heroes, mobile composition
    motion.md         choreography and recipes (loader handoff, iris, shared element, index preview…)
    webgl.md          DOM-synced image planes, fullscreen shaders, performance rules
    patterns.md       proven structures from test builds (driver module, sticky stage…)
    content.md        voice, honest placeholders, case-study structure
    quality.md        accessibility, performance budgets, bugs found in real builds
    engine.md         framework-agnostic motion engine
    nextjs.md         Next.js adapter, layout, metadata, fonts
    astro.md          Astro adapter and layout
    ship.md           final checks and deploy
  scripts/            Node helpers, no dependencies except Playwright for screenshots
.claude-plugin/       Claude Code plugin marketplace
.github/              CI workflow, issue and PR templates

Security

A skill is instructions your agent follows, and this one has it run builds and scripts on your
machine. Read awwwards/SKILL.md before installing, as you would any code you run. Nothing is
deployed without your confirmation.

Contributing

Issues and pull requests are welcome, especially for bugs found in real builds and new
patterns in awwwards/references/.

1. Fork the repo and create a branch.
2. Make the change. A skill is a folder with a SKILL.md; the skills CLI finds any top-level
   folder that has one. For the Claude Code plugin, also add an entry to
   .claude-plugin/marketplace.json.
3. Test it: npx skills add . -g -a claude-code, then run the skill in an agent.
4. Open a pull request. The template asks what changed and what you built to check it; CI
   checks script syntax, SKILL.md frontmatter, the plugin marketplace and that the skills
   CLI finds every skill, on Linux, macOS and Windows.

Support

Found a bug or have an idea? Open an issue.

License

MIT © juliobsz