artifacts
CLAUDE.md2 starsChanged 29 days agoMITView on GitHub
This repository contains interactive HTML artifacts built with AI tools and hosted on GitHub Pages. pyproject.toml defines the canonical site URL under [tool.artifacts]. AGENTS.md is a symlink to this file, so agents share one set of repository instructions. Each artifact has an apps/<slug>/index.html entry point. Metadata lives beside it in name.txt, description.txt, tags.txt, and tools.txt. The root index.html is the gallery, with searchable thumbnails, filters, theme persistence, and detail overlays. The main directories are: Workspace structure owns the full layout…
In this repositoryOne other file it gives its agents.
- copilot-review-loopSkill
The file
Show its rules and text
We split this CLAUDE.md into the rules it gives an agent
17 rules. About 0 are common, 8 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 7
Use make <target> for workspace tools and GitHub actions.
- Very specific: line 8
If a target is missing, add it before using the tool.
- Distinctive: line 9
Read the Makefile and existing code before proposing changes.
- Distinctive: line 10
Keep each tool's scope in its owning configuration file.
- Very specific: line 11
Run auto-fix commands only when the user asks.
- Distinctive: line 12
Commit, push, open PRs, or merge PRs only when the user asks.
- Distinctive: line 13
Before adding or modifying an artifact, verify its behavior or calculations at least once.
- Distinctive: line 32
Use one of the two scaffold inputs:
- Distinctive: line 43
After the scaffold, complete these steps:
- Distinctive: line 46
Verify its behavior or calculations.
- Very specific: line 47
Run make validate and the relevant checks in Operations.
- Very specific: line 69
Use the make pr-*, make issue-*, and Git targets.
- Very specific: line 132
Use kebab-case artifact directory names and index.html entry points.
- Very specific: line 135
Use the tokens in css/src/01-tokens.css and the themed colors in css/src/01-theme-light.css and css/src/01-theme-dark.css, plus the …
- Very specific: line 136
Keep app behavior in apps/<slug>/js/app.js and app-local modules.
- Very specific: line 137
Use the shared bookmark-note palette.
- Distinctive: line 138
Keep Markdown paragraphs on one line.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md 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
CLAUDE.md
This repository contains interactive HTML artifacts built with AI tools and hosted on GitHub Pages. pyproject.toml defines the canonical site URL under [tool.artifacts]. AGENTS.md is a symlink to this file, so agents share one set of repository instructions.
Required workflow
- Use
make <target>for workspace tools and GitHub actions. Do not run.venv/bin/*,pytest,ruff,mypy,npm run,npx,tsc,playwright,gh, orgitdirectly.make gitlists Git targets. Runmake helpto find command groups, thenmake help-<group>to list a group's targets. - If a target is missing, add it before using the tool. Put it in the
mk/*.mkfile for itsmake helpgroup, and add## descriptionafter the target name so generated help includes it. - Read the Makefile and existing code before proposing changes. Reuse existing behavior and helpers.
- Keep each tool's scope in its owning configuration file. Use roots, globs, and exclusions so new files are discovered automatically. Do not duplicate source-file lists in targets, workflows, and configuration files. Configuration-file path references are allowed.
- Run auto-fix commands only when the user asks. These include
make align-tables,make fmt,make format, andmake fix. - Commit, push, open PRs, or merge PRs only when the user asks. Otherwise, make and verify changes in the working tree. Keep small tooling and documentation changes on the current branch unless the user requests a separate branch or worktree.
- Before adding or modifying an artifact, verify its behavior or calculations at least once.
Repository structure
Each artifact has an apps/<slug>/index.html entry point. Metadata lives beside it in name.txt, description.txt, tags.txt, and tools.txt. The root index.html is the gallery, with searchable thumbnails, filters, theme persistence, and detail overlays.
The main directories are:
apps/: artifact implementations, metadata, and app documentation.scripts/: Python tooling grouped underbuild,ci,gh,lib,lint, andsetup. Tests enforce 100% line and branch coverage.tests/: matching Python groups, Playwright suites underbrowser, and Node suites underjs.js/andcss/: gallery code, shared app modules, and styles.config/: tool configuration, gallery metadata, the artifact contract, and audit policy.docs/: workspace documentation and architecture decision records.
Workspace structure owns the full layout and file-ownership reference.
Add an artifact
Use one of the two scaffold inputs:
- For a new placeholder, run
make new name=my-artifact. - For an existing HTML file, run
make new name=my-artifact src=path/to/file.htmlinstead.
Both inputs create metadata files, css/app.css, js/app.js, a README, architecture and verification docs, decision notes, and tests/js/apps/<slug>/app.test.js.
The placeholder includes the shared stylesheets, app shell, and self-only CSP. It passes validation, lint, dead-code, type, and JS test-import checks without manual edits.
The import preserves supplied HTML. It adds the CSP and shared stylesheet links when absent and reports off-origin script or style references. Vendor or remove those references before the CSP check. Shared app-shell wiring is optional for a self-contained import. Keep the generated js/app.js and its test, or replace them with your own module and test.
After the scaffold, complete these steps:
- Build the artifact and fill in its metadata.
- Verify its behavior or calculations.
- Run
make validateand the relevant checks in Operations.
For user-provided artifacts, prefer the src= import and metadata edits. Avoid unrelated refactors. CI generates thumbnails, so missing local thumbnails do not block the contribution. Push only when authorized.
Local commands
The Makefile generates help from target descriptions and section headers. make help-json exposes the same groups and commands as JSON.
The main entry points are:
make setup: install Python and Node dependencies without Chromium. Setup requiresuvon PATH.make setup-all: also install Chromium. Use it when browser work is required.make setup-playwright-local: prepare Chromium and local libraries on Debian or Ubuntu without sudo.make setup-playwright-webkit-localadds WebKit. Browser targets use the prepared libraries withlocal_libs=1.make ci: run the complete non-browser local gate.make ci-fast: run parallel non-browser checks, followed by generated-file checks. This target omits per-file JS coverage floors. Runmake coverage-js-floorsafterward to check those floors.make check: run the full local gate, including browsers, thumbnails, index generation, and site assembly.make check-webruns the browser and thumbnail checks.make status: inspect Git state, dependencies, lockfiles, generated files, and the PR summary.
Operations describes command selection, CI behavior, browser setup, and recovery.
GitHub commands
Use the make pr-*, make issue-*, and Git targets. The PR number defaults to the current branch's PR. Override it with pr_num=N. Do not pass raw CLI flags such as --jq to Make targets.
make pr-review-comments prints thread=PRRT_... identifiers. Pass the identifier to the reply or resolution target.
The commands with less obvious argument patterns are:
| Task | Command |
| List review threads | make pr-review-comments [pr_num=N] |
| Reply to a thread | make pr-reply thread=PRRT_... < reply.md |
| Reply and resolve | make pr-address thread=PRRT_... < reply.md |
| Resolve a thread | make pr-resolve thread=PRRT_... |
| Comment on a PR | make pr-comment [pr_num=N] < comment.md |
| Comment on an issue | make issue-comment issue=N < comment.md |
| Create an issue branch | make issue-develop issue=N |
| Create a stacked branch | make branch name=my-feature base=current-branch |
| Create a worktree | make worktree name=my-feature [base=branch] |
| Remove a worktree | make worktree-remove name=my-feature |
| Commit staged work | make commit < message.txt |
Supply multiline messages on stdin through a heredoc or file redirect. Do not pass prose as Make arguments. For short fields, use environment variables such as TITLE='...', SEARCH='...', or COMMENT='...' with the relevant target.
Tool configuration
Each tool has one configuration file that owns its scope. The Makefile calls the tools.
| Tool | Configuration | Scope |
| ruff | pyproject.toml | Python lint and format rules |
| pytest | pyproject.toml | Test paths and 100% coverage for scripts/ |
| ESLint | config/eslint.config.js | JS patterns, ignores, and rules |
| stylelint | config/stylelint.config.js | CSS rules and ignores |
| yamllint | .yamllint.yml | YAML rules and ignores |
| JS coverage | package.json | Thresholds and exclusions |
| TypeScript | config/jsconfig.json | Strict checks for authored JS |
| mypy | pyproject.toml | Strict checks for scripts/ |
| Prettier | config/prettierrc.json | Metadata, workflows, and tooling format |
| Knip | config/knip.json | Unused JS files, exports, and dependencies |
| vulture | pyproject.toml | Unused Python code |
| EditorConfig | .editorconfig | Settings by file type |
| pre-commit | .pre-commit-config.yaml | Hook checks |
| esbuild | package.json | CSS and JS minification during site assembly |
Python declarations and workspace metadata live in pyproject.toml. uv.lock and package-lock.json record the frozen dependency graphs. Change lint, test, and type scope in the owning tool configuration.
Generated files
Change the inputs or generator for these outputs. Do not edit the outputs by hand:
js/data.jsandjs/gallery-config.js, generated byscripts/build/generate_index.py.css/style.css, generated fromcss/src/byscripts/build/generate_styles.py.apps/*/thumbnail.webp, generated byscripts/build/generate_thumbnails.py._site/, assembled byscripts/build/prepare_site.py.- Auto-managed marker sections in
README.md.
Deployment
Pushes to main trigger the GitHub Actions deployment to GitHub Pages. Trusted PRs (same repository, excluding Dependabot) receive previews under gh-pages/pr-preview/pr-<number>/ and a preview-link comment on each push.
CI manages gh-pages. Do not edit it manually. Deployments use GitHub App tokens and verified GraphQL commits. Architecture describes the pipeline, token roles, and deployment records.
App conventions
- Use kebab-case artifact directory names and
index.htmlentry points. - Load
css/style.cssin the gallery. In mature apps, load../../css/style.cssbefore./css/app.css. - Reuse
js/app-theme.js,js/modules/app-shell.js, and the other shared modules injs/modules/, such asformatting.js,segmented.js,section-nav.js, andchart-theme.js. - Use the tokens in
css/src/01-tokens.cssand the themed colors incss/src/01-theme-light.cssandcss/src/01-theme-dark.css, plus the components incss/src/04-artifact-components.cssbefore adding app-local CSS. Shared families include.control-field,.stat,.chip,.segmented,.meter,.app-callout,.section-kicker, and.section-nav. - Keep app behavior in
apps/<slug>/js/app.jsand app-local modules. Keep app-specific layout inapps/<slug>/css/app.css. - Use the shared bookmark-note palette. Derive app CSS colors from tokens through
var()orcolor-mix(). Raw color values belong in the shared token definitions.make lint-app-css-tokensalso checks radius, font-size, and letter-spacing values. Style guide documents allowed values and exceptions. - Keep Markdown paragraphs on one line. Use sentence case headings and direct instructions. Do not use em dashes or en dashes.
Documentation ownership
Workspace documentation links to the owning document for each concern: structure, architecture, frontend behavior, operations, maintenance, style, and architecture decisions. Link to those sources instead of repeating their policies.
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.

