skills-browser
AGENTS.md1 starsChanged 6 months agoMITView on GitHub
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repositoryOne other file it gives its agents.
- do-itSkill
The file
We split this AGENTS.md into the rules it gives an agent
6 rules. About 0 are common, 2 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 4
Keep npx skills as the source of truth.
- Very specific: line 21
Run a focused test with bun test src/server/<name>.test.ts.
- Very specific: line 22
Before committing: bun run lint → bun run typecheck → bun run test.
- Distinctive: line 53
Do not commit generated CSS.
- Very specific: line 57
Use cn() from src/web/lib/utils.ts for class merging.
- Distinctive: line 64
Avoid comments unless they explain non-obvious behavior.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.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
Product Context
- Local web UI for developers managing AI agent skills from
skills.shthrough the upstreamskillsCLI. - Keep
npx skillsas the source of truth; do not read canonical skill directories directly for installed state. - Visual language is shadcn/ui-style developer tooling: neutral oklch palette, Inter Variable, generous whitespace, light and dark modes, no playful/consumer decoration.
- Theme is controlled by the
skills-browser-themelocalStorage key and adarkclass on<html>; dark is the default when no saved theme exists.
Commands
bun install # setup; Bun linker is isolated in bunfig.toml
bun run dev # embed:skills + build CSS + portless server + CSS watch, localhost:1996
bun run start # embed:skills + build CSS + NODE_ENV=production bun run src/cli.ts start
bun run build # embed:skills + build CSS + bun build --compile, outputs ./dist/skills-browser
bun run lint # oxlint src
bun run typecheck # embed:skills + tsgo --noEmit
bun run test # bun test
bun run format # oxfmt- Run a focused test with
bun test src/server/<name>.test.ts. - Before committing:
bun run lint→bun run typecheck→bun run test. - Lefthook enforces pre-commit (lint, format, typecheck) and pre-push (test).
- GitHub Actions CI runs lint → typecheck → test on push/PR to main.
- Release workflow runs CI, bumps version, updates changelog date, builds binaries, publishes npm, and creates a GitHub Release.
- The compiled binary runs as
./dist/skills-browser start; CLI options are--host <host>,--port <number>, and--auto. HOSTandPORTenvironment variables set CLI defaults when flags are omitted.
Architecture
- Single-package Bun app, not a monorepo. Package manager is
bun@1.3.13. src/cli.tsis the only runtime entrypoint. It validates host/port, saves the launch cwd inSKILLS_BROWSER_LAUNCH_CWD, and serves the app withBun.serve.src/server/hono-app.tsowns API routes:/api/health,/api/dashboard,/api/dashboard/refresh,/api/dashboard/remove,/api/dashboard/install,/api/dashboard/update,/api/search,/api/skill-details,/api/skill-readme.src/server/skills-command-adapter.tsis the narrow server-side boundary fornpx skills; never pass raw browser-provided shell strings through it.- Installed state comes from
skills list --json; lock files only enrich state with managed metadata. src/server/skill-readme-state.tsreads an installed skillSKILL.mdonly after resolving the skill from current CLI-derived installed state.src/features/skills/contains shared types, schemas, and state shapes used by both server and web.src/web/is a client-rendered React 19 SPA. HTML entry issrc/web/index.html; JS entry issrc/web/main.tsx.- TanStack Router routes are declared manually in
src/web/router.tsx; there is no generated route tree or SSR. - Current SPA routes are
/and/skill/$skillId.
Generated Files
scripts/embed-skills.tsbundles theskillsandyamlpackages intosrc/server/.generated/skills-bundle.ts(auto-generated, do not edit).scripts/build-styles.tsbuilds Tailwind CSS intosrc/web/.generated/globals.cssand copies the Inter Variable font asset intosrc/web/assets/.embed:skillsruns before dev, start, build, typecheck, and prepack.- Generated directories under
src/server/.generated/andsrc/web/.generated/are ignored and must not be committed.
Styling And UI
- Tailwind v4 source lives in
src/web/styles/globals.css; the browser loads generated CSS fromsrc/web/.generated/globals.css. bunfig.tomlalso keepsbun-plugin-tailwindconfigured for Bun static serving.- Do not commit generated CSS.
globals.cssuses@source "../**/*.{ts,tsx}"and@source "../../features/**/*.{ts,tsx}"; classes in shared feature code can affect Tailwind output.- shadcn config is
components.jsonwithstyle: "base-nova",rsc: false, Tailwind CSS atsrc/web/styles/globals.css, lucide icons, and aliases under@/web/.... - Existing shadcn UI components in
src/web/components/ui/use@base-ui/reactprimitives, not Radix. - Use
cn()fromsrc/web/lib/utils.tsfor class merging.
Code Style
- oxfmt, not Prettier: single quotes, semicolons, 100-column width, trailing commas where valid in ES5, LF endings.
.oxfmtrc.jsonsorts Tailwind classes incn()andcva()calls usingsrc/web/styles/globals.cssas the Tailwind v4 stylesheet.- TypeScript is strict with
noUnusedLocalsandnoUnusedParameters; keep test doubles and imports minimal. - Avoid comments unless they explain non-obvious behavior.
Tips
- To resolve conflicts with
codedb.snapshot, regenerate it usingcodedb snapshot. - Prioritize codedb tools for navigating and understanding the codebase.
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.

