prot-skills
AGENTS.md7 starsChanged 5 months agoMITView on GitHub
@.agents/rules/branching.md @.agents/rules/coding.md @.agents/rules/coding-style.md @.agents/rules/commits.md @.agents/harness/index.md Order of operations: This repository uses .agents/harness/index.md as the shared cross-tool agent harness. Read it after this file for non-trivial tasks, especially work that affects agent behavior, repository guidance, reusable workflows, tool entrypoints, or safety-sensitive boundaries. .agents/harness/index.md is the canonical shared agent protocol. This local AGENTS.md acts as a tool-specific entrypoint and points back to the shared repository guidance instead of duplicating it. Keep root entrypoints such as AGENTS.md and CLAUDE.md tracked and thin; update…
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 repository7 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- release-publishSkill
- release-tagSkill
- release-versionSkill
- self-checkSkill
- submit-prSkill
- sync-agent-skillsSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
20 rules. About 0 are common, 15 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈15
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
- Distinctive: line 15
If on main, create a working branch first (see branching rules).
- Distinctive: line 16
Read coding rules before implementing or refactoring.
- Distinctive: line 17
Read coding style rules before changing code, tests, or shared contracts.
- Distinctive: line 18
Commit following the commit rules.
- Very specific: line 19
Never include Co-Authored-By:, Signed-off-by:, or similar attribution trailers in commit messages.
- Very specific: line 45
When a request triggers a skill, read the full SKILL.md and follow its workflow phases exactly.
- Very specific: line 109
When a skill is migrated: the source folder is copied into ~/.prot-skills/skills/<id>, recorded in SQLite, and the original folder is …
- Distinctive: line 132
Don't assume. Don't hide confusion.
- Distinctive: line 135
If multiple interpretations exist, present them — don't pick silently.
- Distinctive: line 136
If a simpler approach exists, say so.
- Distinctive: line 137
If something is unclear, stop.
- Distinctive: line 143
No features beyond what was asked.
- Distinctive: line 144
No abstractions for single-use code.
- Distinctive: line 146
No error handling for impossible scenarios.
- Distinctive: line 147
If 200 lines could be 50, rewrite it.
- Distinctive: line 153
Don't "improve" adjacent code, comments, or formatting.
- Distinctive: line 154
Don't refactor things that aren't broken.
- Very specific: line 156
Remove imports/variables/functions your changes made unused — don't remove pre-existing dead code.
- Distinctive: line 157
Every changed line should trace directly to the user's request.
- Very specific: line 166
Use pnpm test, pnpm build, pnpm lint as verification steps.
≈ “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
AGENTS.md
This file provides guidance to AI coding agents when working with code in this repository.
Agent Rules
@.agents/rules/branching.md @.agents/rules/coding.md @.agents/rules/coding-style.md @.agents/rules/commits.md @.agents/harness/index.md
Order of operations:
- If on
main, create a working branch first (see branching rules). - Read coding rules before implementing or refactoring.
- Read coding style rules before changing code, tests, or shared contracts.
- Commit following the commit rules.
- Never include
Co-Authored-By:,Signed-off-by:, or similar attribution trailers in commit messages.
Agent Harness
This repository uses .agents/harness/index.md as the shared cross-tool agent
harness. Read it after this file for non-trivial tasks, especially work that
affects agent behavior, repository guidance, reusable workflows, tool entrypoints,
or safety-sensitive boundaries.
.agents/harness/index.md is the canonical shared agent protocol. This local
AGENTS.md acts as a tool-specific entrypoint and points back to the shared
repository guidance instead of duplicating it. Keep root entrypoints such as
AGENTS.md and CLAUDE.md tracked and thin; update .agents/rules/,
.agents/harness/, or .agents/skills/ for shared policy changes.
Agent Skills
This repo includes agent skills in .agents/skills/. Read the relevant SKILL.md when a user request matches one of these:
- release-version — prepare a release branch: bump version, write release notes. Triggered by "准备发版", "bump version", "写 release notes".
- release-publish — publish a release: push branch, create auto-merge PR, push tag, monitor CI. Triggered by "发布", "publish release".
- release-tag — direct release from main: bump, verify, push, tag. Triggered by "直接发版", "push tag", "release on main".
- submit-pr — submit a PR to main with auto-merge: scan diff, assess risk, creates the PR, enables auto-merge when safe, and reports any blockers. Triggered by "提交PR", "create a PR", "submit PR".
- self-check — run local production/PR self-checks before pushing or submitting a PR. Triggered by "自检", "生产门禁自检", "PR checks", "pre-push check".
- sync-agent-skills — maintain repository agent skills across Codex and Claude. Triggered when adding, removing, renaming, or editing skills under
.agents/skills, or when Claude skill symlinks need to be generated or checked.
When a request triggers a skill, read the full SKILL.md and follow its workflow phases exactly.
.agents/skills/ is the source of truth for repository skills. Run
pnpm skills:sync after adding, removing, or renaming a skill so Claude can
load the generated .claude/skills/ symlinks.
Commands
pnpm dev # Vite dev server (port 1420, strict)
pnpm tauri:dev # Desktop app in dev mode
pnpm build # app:sync → tsc → vite build
pnpm test # Vitest single run (jsdom, @/ alias, globals)
pnpm test:watch # Vitest watch mode
pnpm test:tokens # Validate design token CSS output
pnpm skills:sync # Generate local Claude skill symlinks from .agents/skills
pnpm skills:check # Check that Claude skill symlinks are in sync
pnpm lint # oxlint (correctness=error, suspicious/perf=warn, no ESLint)
pnpm lint:fix # oxlint --fix
pnpm format # oxfmt (no Prettier)
pnpm format:check # oxfmt --check
cd src-tauri && cargo test # Rust testsSingle test file: pnpm vitest run src/tests/lib/theme.test.ts
The build and tauri:build scripts run app:sync first, which syncs productName/version from package.json into tauri.conf.json and Cargo.toml.
Architecture
This is a Tauri 2 desktop app (React 18 frontend + Rust backend) for managing AI coding tool Skills. Managed skills live in ~/.prot-skills/skills, metadata in ~/.prot-skills/metadata.db (SQLite via rusqlite).
Frontend (src/)
src/main.tsx→src/App.tsx→AppProviderswrapsAppShell- No router —
AppShellusesuseState<PageId>for page switching. Four pages:my-skills,tools,migrate,settings. Keyboard shortcuts⌘1–⌘4. - Provider hierarchy:
ThemeProvider→LanguageProvider→ToastProvider→CommandBarProvider src/api/index.ts— typed wrappers around@tauri-apps/api/coreinvoke. Guards against browser context where Tauri isn't available.src/shell/— layout, nav, providers, command bar (cmdk-powered⌘Kpalette)src/components/primitives/— generic UI components (Button, Select, Switch, Badge, etc.)src/components/patterns/— domain-level UI (EmptyState, Toast, FilterPills, StatsStrip)src/components/command/— CommandBar built on cmdksrc/lib/— pure utilities: theme resolution, i18n (en/zh-CN), breakpoints, toast queue, motionsrc/hooks/—useTheme(with View Transition API circle reveal animation),useBreakpoint,useKeyboardShortcuts,useToast,useReducedMotionsrc/design/—tokens.json(source of truth) andtokens.css(generated CSS custom properties)src/types/index.ts— shared TS types:Skill,AITool,SkillLink,LocalSkill,SyncSkillTargetsResult- Path alias:
@/maps tosrc/
Backend (src-tauri/src/)
lib.rs— app entry. Initializes DB at~/.prot-skills/metadata.db, runsToolService::detect_tools, registers all Tauri commandsdb/connection.rs—Databasestruct wrappingrusqlite::Connection. Schema:skills,ai_tools,skill_links,skill_sources. Includes a migration forsort_orderon existing DBs.commands/— Tauri command handlers (skill_commands.rs,tool_commands.rs) — thin layer that calls services and serializes resultsservices/— business logic:ToolService— CRUD, detection, enable/disable, reorderSkillService— install, toggle, uninstall, prune stale entries, register pre-existing foldersDiscoveryService— scans tool skill directories forSKILL.mdfolders, auto-replaces managed skills with symlinksLinkService— manages per-skill-per-tool symlinks
models/— Rust structs matching DB rows, with serde derivesutils/path_utils.rs— symlink detection, manager-dir checks, skills-dir resolutionerror.rs— unifiedAppErrorenum (Db/Io/NotFound/Path/Other) withAppResult<T>alias
Symlink model
When a skill is migrated: the source folder is copied into ~/.prot-skills/skills/<id>, recorded in SQLite, and the original folder is replaced with a symlink pointing to the managed copy. DiscoveryService::scan_directory detects this and skips already-correct symlinks.
Design tokens
Tailwind is configured entirely through CSS custom properties defined in src/design/tokens.css (generated from tokens.json). Colors, spacing, radii, shadows, durations, and font sizes all reference var(--color-*) etc. The tailwind.config.js maps Tailwind utility classes to these variables. scripts/check-tokens.ts validates the output.
Build tooling
- oxlint (not ESLint) with react/import/unicorn/typescript plugins
- oxfmt (not Prettier)
- husky + lint-staged for pre-commit: oxlint on
*.{js,ts,jsx,tsx}, oxfmt on everything - commitlint with conventional config
Security-sensitive areas
The app creates symlinks and modifies local files. Review changes to Tauri capabilities (src-tauri/capabilities/default.json), filesystem commands, path utilities, and symlink logic carefully.
Behavioral Guidelines
Derived from andrej-karpathy-skills. These bias toward caution over speed — for trivial tasks, use judgment.
1. Think Before Coding
Don't assume. Don't hide confusion. Surface tradeoffs.
- State assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them — don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.
2. Simplicity First
Minimum code that solves the problem. Nothing speculative.
- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- If 200 lines could be 50, rewrite it.
3. Surgical Changes
Touch only what you must. Clean up only your own mess.
- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.
- Remove imports/variables/functions your changes made unused — don't remove pre-existing dead code.
- Every changed line should trace directly to the user's request.
4. Goal-Driven Execution
Define success criteria. Loop until verified.
- "Add validation" → "Write tests for invalid inputs, then make them pass"
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
- For multi-step tasks, state a brief plan with verification checkpoints.
- Use
pnpm test,pnpm build,pnpm lintas verification steps.
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.

