agentleFS
Sign inStart free
teispaceteispace/teitunnel/.claude/skills/writing-docs/SKILL.md

writing-docs

Skill2 starsChanged 48 days agoMITView on GitHub

Writes and updates Teitunnel's documentation, both the user docs on the website (apps/web/content/docs, Fumadocs MDX) and the contributor docs in docs/, including page structure, navigation, components, generated reference pages, screenshots, sourcing third-party facts and the link check. Use when a change affects what users or contributors need to know, or when asked to write a guide, tutorial or reference page.

22 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use pr-description, implement and 6 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • MicrosoftSkill

    pr-description

    Draft Nacelle PR titles, pull request descriptions, commit titles, commit descriptions, and squash commit messages. Use when asked for PR or commit wording, a branch summary, or a PR description that can be used in a commit. Omit validation sections from commit bodies and remove filler.

    Also in 3 projects that use this

  • Hugging FaceSkill

    implement

    Make tests pass. Invoke after /write-tests produces failing tests.

    Also in 5 projects that use this

  • Google CloudSkill

    triage

    Gather context on a change or bug and plan the implementation.

    Also in 3 projects that use this

  • GoogleSkill

    prototype

    Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.

    Also in 3 projects that use this

  • GoogleSkill

    grilling

    Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.

    Also in 3 projects that use this

  • MicrosoftSkill

    release

    Use ONLY when the user explicitly asks to cut/publish a Huabu desktop release or tag a version. Performs an outward action — bumps the version in apps/desktop/package.json, commits + annotated-tags vX.Y.Z, and pushes the branch + tag. That tag push auto-builds the macOS/Windows installers and publishes a GitHub Release. Provides `status`, `bump`, `tag-push`, and a one-command `run` (bump → tag-push).

    Also in 4 projects that use this

  • +1 more from microsoft
  • +1 more from google

The file

We split this skill into the rules it gives an agent

1 rule. 0 are common, 1 is distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 21 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Write for someone in the middle of a task: short sentences, the outcome first, exact error messages as they appear.

    line 55

“Common” is measured: kept by at least 6 in 10 of the 21 edited versions of this file we could read. “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

Writing docs

Two audiences, two places:

AudienceWherePublished
People using Teitunnelapps/web/content/docs/ (MDX)teitunnel.teispace.com/docs
People changing Teitunneldocs/ (Markdown)GitHub

A pull request that changes behaviour updates the docs it affects in the same pull request.

User docs

Sections, each a folder with a meta.json that orders its pages:

FolderFor
getting-started/Install, first share, first route, what's new
tutorials/Use cases end to end ("Test webhooks on localhost")
concepts/How things work (tunnels, changes, DNS ownership)
guides/One feature each, complete: app, CLI, limits, troubleshooting
compare/Teitunnel next to other tools
reference/CLI, permissions, limits, troubleshooting, glossary

A page:

---
title: Stripe webhooks on localhost
description: One sentence that says what the reader gets, used for search and social cards.
searchDescription: "70–160 characters for search results, when description is longer."
---

Intro: what this page helps with, in two or three sentences.

## 1. A step or a topic
  • Components: <Callout> (type="warn" for risks), <Steps>/<Step>, <Tabs>/<Tab> (per platform or per provider), <Accordions>/<Accordion>, <Cards>/<Card> for "Related".
  • Show both ways: the app (bold UI names, ▸ between menu levels) and the terminal (teitunnel …). Example hostnames are on yourhost.com (app.yourhost.com), and a Quick Share's is quiet-river-lamp-orbit.trycloudflare.com; screenshots and their alt text keep the mock data's teispace.com names.
  • Link other pages with absolute paths (/docs/guides/inspector, with #heading anchors). The website test fails on any link or anchor that doesn't exist.
  • Facts about Cloudflare or other products come from their own documentation: link it, and add a "Checked <date>" note where limits or prices may change. Never guess a number.
  • Write for someone in the middle of a task: short sentences, the outcome first, exact error messages as they appear.

Generated pages are never edited by hand: apps/web/content/docs/reference/cli.mdx (from the CLI's clap definitions) and apps/web/content/docs/reference/permissions.mdx (from crates/core/src/accounts). Regenerate:

UPDATE_DOCS=1 cargo test -p teitunnel-cli --bin teitunnel-cli docs
UPDATE_DOCS=1 cargo test -p teitunnel-core --test permissions_doc

Screenshots for the website come from the real UI on mocked data, in light and dark. apps/desktop/scripts/shoot-site.ts renders the set in apps/web/public/screens/ as WebP (add a shot to its list; needs cwebp); run it from apps/desktop with node scripts/shoot-site.ts [name…]. For a one-off, pnpm --filter @teitunnel/desktop shoot with ?clean on the route hides the developer section. Show one with <Screenshot name="routes" alt="…" />; its alt says what's on screen (it's what image search and screen readers read), and the sitemap and the page's structured data list it automatically (apps/web/lib/page-facts.ts), as they date the page from git.

Contributor docs

  • ARCHITECTURE.md: update when a module boundary, data flow or invariant changes.
  • DESIGN.md: update when a token, component, pattern or UI rule changes.
  • CONVENTIONS.md: update when a coding or testing convention changes.
  • SECURITY_MODEL.md: update when anything about secrets, processes, DNS ownership, network exposure or the supply chain changes.

Describe how things are, not their history; the reasoning belongs in the issue or pull request that made the change.

Check

pnpm --filter @teitunnel/web test      # links and anchors
pnpm --filter @teitunnel/web build     # every page compiles
pnpm --filter @teitunnel/web dev       # read it in 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