agentleFS
Sign inStart free
maxi3777maxi3777/claritykit/skills/clarity-preview/SKILL.md

clarity-preview

Skill0 starsChanged 3 months agoMITView on GitHub

Start, stop, or check the ClarityKit preview server for the CURRENT project (serves the project's diagram/prototype site over http://localhost, survives reboots of the conversation). INVOKE ONLY WHEN THE USER EXPLICITLY ASKS to start/stop/restart the preview server (e.g. "start the preview server", "open the preview"). Never start a server on your own initiative.

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 1 is distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    After a machine reboot, just start again.

    line 26
  2. Very specific:

    If clarity is not found: run export PATH="$HOME/.local/bin:$PATH" and retry ONCE.

    line 33
  3. Very specific:

    If it is still missing, STOP and tell the user the ClarityKit CLI is not installed/on PATH (see README Install).

    line 34
  4. Distinctive:

    Only serve the current project: Run the commands from inside the project the user is working in — the derivation does the rest.

    line 38
  5. Very specific:

    Verify before reporting: Only tell the user the URL after the tool confirms HTTP 200 — clarity server start does this itself.

    line 40
  6. Very specific:

    If the user says "the preview is gone / can't open", run status first, then start.

    line 43

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

clarity-preview — preview server lifecycle (manual only)

One server per project. The server is detached (survives conversation/process-group termination), registered, and verified. All mechanics live in the clarity server command — never hand-roll nohup/setsid commands.

The server takes no directory argument. Its root is derived, not chosen: it always serves <projectRoot>/docs/clarity where the project root is the nearest ancestor containing .git (fallback: the current directory). You cannot point it at the wrong directory because you never pass one. Just make sure you run it from somewhere inside the user's project.

Commands

clarity server start    # build site, start detached, verify HTTP 200, print URL
clarity server status   # list all registered servers with liveness
clarity server stop     # stop this project's server, free the port
  • start is idempotent: already-running → rebuilds the site and re-reports the URL. After a machine reboot, just start again.
  • Port allocation is deterministic per project root (hash-based, 8400–8799, collision-probed) so different projects never collide.
  • The registry lives at ~/.claritykit/servers.json — one entry per project staging dir.

Rules

  • If clarity is not found: run export PATH="$HOME/.local/bin:$PATH" and retry ONCE. If it is still missing, STOP and tell the user the ClarityKit CLI is not installed/on PATH (see README Install). Never improvise alternatives — no nohup, no setsid, no hand-rolled node server.mjs serve, no relative tool paths. A missing CLI is an install problem for the user to fix, not a problem to work around.
  • Only serve the current project. Run the commands from inside the project the user is working in — the derivation does the rest.
  • Verify before reporting. Only tell the user the URL after the tool confirms HTTP 200 — clarity server start does this itself; if it reports failure, read the printed log path and debug from there.
  • If the user says "the preview is gone / can't open", run status first, then start.
  • Artifact updates (clarity publish runs by other skills) are picked up live — no restart needed; the user just refreshes the browser.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.

Check your setup, free