Guide · Agent skill
How to use the Directions Lab Scaffolder agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The directions-lab skill is an agent skill for the paperclip repo. Once it is installed, you can ask your coding agent to build a 'directions lab': a separate page that shows the shipped UI (called Today) next to two or three alternative design directions for one feature. This guide explains what the skill does, how to install it, what it needs, how to ask for a lab in plain language, and what to check before you trust the generated files.
Directions Lab Scaffolderpaperclipai/paperclip · MIT Download the skill Quick start
- 1Download and install the ZIP. Download the skill ZIP from this page. Unzip it into ~/.claude/skills/ for personal use, into a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 2Prepare the paperclip checkout. Open a git checkout of the paperclip repo and create a branch from origin/master. Make sure ui/node_modules exists, and run pnpm install --frozen-lockfile if it does not.
- 3Ask for a directions lab. Describe the feature, its screens and the number of directions you want. Answer the agent's questions about directions and surfaces if it asks.
- 4Dry run the scaffold. Ask the agent to run scaffold.mjs new with --dry-run first. Read the planned paths, ports, cells and story entry before allowing any writes.
- 5Run the scaffold and review. Run the scaffold without the dry-run flag. Check the generated files, the story entry and the test and build results before you commit anything.
- 6Check the lab in the browser. Start the dev entry the generator added, open the landing page and a direction, and confirm the hover motion and the animation toggle behave as described.
What an agent skill is and what this one makes the agent do
An agent skill is a folder of instructions, templates and scripts that an AI coding agent can load when a task matches the skill's description. This one is named directions-lab and is described as scaffolding a directions lab that shows shipped UI (Today) beside 2-3 design directions.
The lab is one page for one feature. It has a toolbar with numbered direction buttons and a Today button, theme and animation toggles, and surface tabs for each screen the feature appears on. The lab is also registered in the design-proposals Storybook, so it has a story entry from its first commit.
- A page at ui/<slug>-directions.html with its source in ui/src/<slug>-directions/
- Today, always mounted on the lab's fixtures, used as the baseline every direction is judged against
- Two or three numbered directions, each with its own scoped tokens.css
- The V1 MVP hover motion, included in every direction and covered by a test
- One story file under ui/storybook/stories/design-proposals/
Install the directions-lab skill
Download the ZIP for the skill from this page. You can install it in one of three ways, depending on how you use your agent.
For a personal setup, unzip the download into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
- Personal: unzip into ~/.claude/skills/
- Project only: unzip into the project's .claude/skills/ folder
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Check the prerequisites before the first run
The skill runs a Node scaffold script and Node's test runner, and it builds with Vite. Your checkout must be ready for that. The skill is built for the paperclip repo only, because its templates and paths assume the ui/ layout and the repo's gates.
Before scaffolding, confirm the following. The skill's own pre-flight step checks for the Vite binary and tells you to install dependencies if it is missing.
- Node.js, used to run scaffold.mjs and node --test
- pnpm, plus installed ui/node_modules (the Vite binary); if missing, run pnpm install --frozen-lockfile
- A git checkout of the paperclip repo, on a branch of your own created from origin/master
pnpm install --frozen-lockfileTrigger the skill with a natural request
You do not need a special command to use the skill. Describe the lab you want in plain words, and mention the feature and, if you have them, the number of directions and the places the feature appears. The agent will match your request to the skill's description.
The skill may ask up to two questions in a single prompt: how many directions you want (2 or 3), and which surfaces to include. It skips a question if your request already answers it. It does not ask about theme, animation, Today, ports, slug or the landing view, because those are fixed.
- Set up a directions page for the task thread, with three directions and the right panel as a second surface.
- Make a directions lab for the composer feature and compare it with the shipped UI.
- Explore design directions next to production for the artifact list.
Review the generated files and the safety notes
The skill writes files, edits shared config and runs scripts in the repo. Its generator refuses to overwrite existing paths. It then checks the Storybook catalog, runs the lab's own Vitest files and a Vite build. If any check fails, it deletes what it wrote and restores the two shared files. The skill does not use the network.
Read the generated code before you commit. The skill's own rules say not to add code comments, not to add a package.json script, not to change the lockfile, and not to commit screenshots or generated catalog files. A lab file of 600 lines or more makes the check fail.
- Runs scripts: yes (scaffold.mjs and node --test)
- Uses network: no
- Edits shared files: ui/vitest.config.ts and ui/tsconfig.json are updated by the generator's rollback logic, so review the diff
- Use --dry-run first to see the planned paths, ports and story before any file is written
node .agents/skills/directions-lab/scripts/scaffold.mjs new --slug composer --title "Composer" --surfaces thread:Task-thread:960@tasks,panel:Right-panel:434@tasks --directions 3 --dry-runTips for better results
Give the agent the feature name and the places it appears, so it can find the components and the feature-map capabilities. Ask it to state the derived slug, surfaces, directions and API paths before it scaffolds. A wrong value is cheap to fix at that stage.
After scaffolding, start the dev entry the generator added and check the landing page and a direction in the browser. Hover a motion specimen, toggle animation off and confirm that only the fill changes.
- Name the feature and its screens in the request
- Ask for the plan first, then run the dry run, then the real scaffold
- Keep the lab on its own branch so it is easy to review or discard
What people use it for
- Compare two or three alternative layouts for a task thread against the shipped Today view
- Explore new tokens and spacing for a right-hand panel while keeping the same structure
- Build a shared link that shows the same controls and surfaces to reviewers for a design critique
- Register a design exploration in the design-proposals Storybook from its first commit
Frequently asked questions
How do I install the directions-lab agent skill?
Download the ZIP from this page. Unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.
What does the directions-lab skill require?
It requires Node.js, pnpm, installed ui/node_modules including the Vite binary, and a git checkout of the paperclip repo on a branch from origin/master. It runs scripts but does not use the network.
Is the directions-lab skill free to use?
The skill is published under the MIT licence. This page does not list any price, so check the licence text in the repo for the terms.
Can I use this skill outside the paperclip repo?
No. The templates and paths assume the paperclip ui/ layout and its gates, so files generated in another project would not fit. The skill is intended for the paperclip repo only.
Why did the skill delete files it created?
If any check fails after scaffolding, such as the Storybook catalog check, the lab's tests or the Vite build, the generator removes what it wrote and restores its two shared files. This stops a half-written lab from breaking the whole repo. You can pass --keep-on-failure to inspect a failed run.
Should I run the skill without reviewing the code?
No. The skill writes files, edits shared config and runs scripts in the repo. Review the generated code and the diff before you commit, and use the dry run to see the plan first.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you are a front-end designer or a paperclip UI developer who wants to explore alternatives to a shipped feature inside the paperclip repo, with a consistent lab structure. Pick something else if your project is outside the paperclip repo, or if you want to run it without reading the generated code, since it writes files, edits shared config and runs scripts.
Download the skill