agentleFS
kratoczkratocz/skills/AGENTS.md

skills

AGENTS.md1 starsChanged 50 days agoMITView on GitHub

Guidance for agents (and humans) maintaining this repository. A collection of portable Agent Skills — one directory per skill under skills/<name>/ with a SKILL.md entry point — installable into 70+ agent harnesses via npx skills add kratocz/skills. Claude-Code-specific plugins (lifecycle hooks, statusline) live separately in kratocz/claude-plugins; do not add hook-dependent skills here. Before replacing anything under ~/.agents/skills/, confirm each target is this repo's — its SKILL.md exists and its frontmatter name equals the directory name — and leave everything else…

  • Deletes or force-pushes

The file

Files
AGENTS.md

AGENTS.md

Guidance for agents (and humans) maintaining this repository.

What this is

A collection of portable Agent Skills — one directory per skill under skills/<name>/ with a SKILL.md entry point — installable into 70+ agent harnesses via npx skills add kratocz/skills. Claude-Code-specific plugins (lifecycle hooks, statusline) live separately in kratocz/claude-plugins; do not add hook-dependent skills here.

Distribution model (verified 2026-08-01)

  • npx skills add installs a physical copy of each skill into ~/.agents/skills/ (the "universal" directory) and creates per-agent symlinks to it (e.g. ~/.claude/skills/<name> → ../../.agents/skills/<name>). Local-path installs are not tracked by skills update — refresh them by re-running the add.
  • Directory reality on tested harnesses: ~/.agents/skills/ is read by Codex, Copilot CLI, opencode, Antigravity CLI (interactive sessions), and Claude Code (with a delayed index). ~/.claude/skills/ is picked up by Claude Code instantly, including hot-reload into running sessions. Gemini CLI stood in this list until 2026-10-31 and is gone: Google discontinued it on 2026-06-18 in favour of Antigravity CLI, it is no longer installed on the maintainer's machine, and its last local session there dates from 2026-07-14, before the verification this section is dated by.
  • Antigravity's agy -p (non-interactive print mode) does not load skills at all — never use it to test skill visibility; test in an interactive session.
  • Known upstream gap in the skills CLI: -g -a antigravity-cli installs only into ~/.agents/skills/ and never into ~/.gemini/antigravity-cli/skills/, despite the CLI's own agent map listing that global path. It works in practice only because Antigravity reads ~/.agents/skills/. Do not open an upstream issue for it — that is a deliberate decision, not an oversight.
  • The maintainer's machines use live symlinks from ~/.agents/skills/<name> straight into a working clone, so edits apply without reinstalling (~/.claude/skills/<name> is the CLI's own symlink to ~/.agents/skills/<name> and resolves through). The skills CLI does not create these — npx skills add always writes physical copies, so a plain add silently reverts the setup, and it has to be re-established afterwards:
    CLONE=$(pwd)   # a working clone
    for n in $(ls "$CLONE/skills"); do
      [ -f "$CLONE/skills/$n/SKILL.md" ] || continue
      rm -rf ~/.agents/skills/"$n" && ln -s "$CLONE/skills/$n" ~/.agents/skills/"$n"
    done
    Before replacing anything under ~/.agents/skills/, confirm each target is this repo's — its SKILL.md exists and its frontmatter name equals the directory name — and leave everything else alone; that directory also holds skills from other sources. Verified 2026-08-26: this claim had drifted from reality, all 27 skills sat as copies from the previous day, and a /work-reconcile run made to test a fix silently executed the old version instead. Trusting an installed skill to match the clone is the failure mode; check version: on both sides when a test result looks like the edit never happened. When a copy differs from the clone, decide whether it holds an in-place edit by comparing it with the commit it was copied from as well as with today's HEAD: a line missing from HEAD is usually text the repo has since rewritten, not an edit. Seen 2026-10-02: a HEAD-only diff flagged six of 38 copies as edited in place; checked against the commit the copies came from, none was.
  • -s selects one skill per flag. npx skills add <repo> -s a,b,c reads the whole comma list as a single skill name, installs nothing, and prints No matching skills found for: a,b,c followed by every skill the repo offers — output whose tail is indistinguishable from a successful listing, so reading only the end of it reads as success. Repeat the flag instead (-s a -s b -s c), and confirm from ~/.agents/skills/<name> and the CLI's ~/.agents/.skill-lock.json rather than from the command's own output.

Authoring rules

  • Not every rule wants to be a skill. A skill is reached through its description, so it fires only when something in the request matches it; an agent's instructions file (AGENTS.md, CLAUDE.md) is in context unconditionally. The test is whether the thing has a moment of invocation: a procedure with a trigger ("sync this film to the NAS", "install these skills") belongs here as a skill, while a passive norm that has to hold while doing something else — formatting conventions, secrets handling, house style for prose — has no trigger to fire on and belongs in the instructions file. Moving a norm into a skill silently stops it applying, and demotes it besides: frameworks that state a precedence, superpowers among them, rank user instructions above skills. Verified 2026-08-26 while trimming a 143-line user CLAUDE.md to 67 — two of its nine sections had a trigger and became skills, the other seven had none and stayed put. Those two bins are not exhaustive. A long discipline that has to hold during other work fits neither: too big to pay for on every turn of every project, and as a skill it never fires. kodex is the worked example of the third case — body in a skill, one always-on pointer line in the instructions file — so the permanent cost is one line instead of eighty and the norm keeps its trigger. Reach for the pointer whenever a norm runs longer than a few lines and does not apply to literally every task. Corollary, learned 2026-09-04: this test sorts your own rules, but it is too blunt to reject someone else's skill. Karpathy's guidelines were skipped here as "a passive norm with no trigger" when their own description names one ("when writing, reviewing, or refactoring code"); the honest reason was redundancy against kodex. What decides a third-party skill is what it adds to the inventory, not the shape of the thing.
  • Stay harness-neutral. Describe actions, not tools ("read the file", not "use the Read tool"), and never assume one specific harness is the runtime — harnesses may appear as examples. This covers interactive prompts too: write "ask the user to choose: A / B / C" rather than naming a harness's question tool. The wording carries the intent either way, and a harness that has a structured picker will still reach for it. Frontmatter extras (allowed-tools, argument-hint, version) are Claude-specific; keeping them is fine.
  • argument-hint must be a quoted string. It is the one frontmatter extra that is not harmlessly ignored elsewhere: the skills CLI parses the YAML, so a bare [--since X] [--until Y] is read as a flow sequence. Four skills in this collection failed to parse at all and were silently skipped by npx skills add — never installable via the CLI — while Claude Code tolerated every variant, which is why nothing looked broken locally. Quote it, and check the value survives npx skills add . --list.
  • Splitting a SKILL.md on ^# cuts through fenced code blocks too. Skill bodies routinely demonstrate Markdown inside fenced examples, and to a line-anchored regex a heading inside a fence is indistinguishable from a real section heading. re.split(r'(?m)^(?=# )', text), used on 2026-08-26 to drop whole sections from a Markdown file, split at a heading inside an example and left twenty orphaned lines behind — and the damage was easy to miss, because every section heading that remained was one that belonged there. Locate a section by explicit search for its own start and its successor's start, or track fence state; then diff the result against a backup before trusting it.
  • Diagnostic thresholds are measured, not reasoned about. When a skill tells an agent "value X means the system is broken", run the query against a machine known to be healthy before writing X down, and check what the query actually counts. A threshold added here on 2026-08-10 compared mdfind -count -onlyin /Applications "kMDItemFSSize > 0" against find -maxdepth 4 | wc -l and declared a working Spotlight index dead — the predicate skips directories, so it never counted a single .app bundle, and the two numbers were never comparable in the first place.
  • Destructive steps delete only what the skill owns. When a skill tells an agent to remove files, symlinks or cache entries as cleanup, it has to establish ownership first — resolve a symlink with readlink and confirm the target points inside the tree the skill itself created (including that tree's former names) — and report anything else as left untouched: <link> -> <target> instead of deleting it. A broken link is usually temporary (a renamed repo, an unmounted disk) and the link is itself the record of where it pointed. This governs cleanup only; it does not apply where removal is the documented repair, as in launchpad-fix recreating the Spotlight store.
  • Paths. Session transcripts and project memory live under <harness-home>/projects/<slug>/, where <harness-home> is ~/.claude (Claude Code) or ~/.gemini/antigravity-cli (Antigravity CLI) — use the first that exists. Skill state/config deliberately stays under ~/.claude/plugins/<name>/ (historical location; it is just a path, readable from any harness — no migration).
  • Names must be unique across the flat collection and the directory name must equal the frontmatter name. Suites use prefixes (tracker-*, work-*).
  • Trigger phrases must discriminate, not just describe. A description competes with every other description in the collection, so a phrase that reads naturally for two skills routes to whichever the model picks first — silently, and the user sees only the wrong result. This bites hardest between suites that share a domain: until 2026-08-11 tracker-stop advertised "end session", "I'm done" and "finished working", every one of which also means "the working day is over" (work-end), and tracker-backfill and work-reconcile both offered to fill in missing Toggl time with nothing saying which one covers the current session and which a past period. When two skills touch the same domain, give each description its own scope in its own words plus one clause naming its counterpart ("Not the end-of-day summary — that is work-end"). Drop any phrase you cannot assign to exactly one skill; an agent that has to ask beats one that guesses.
  • A mistyped command name cannot be fixed from a description. Harnesses that expose skills as slash commands resolve the name locally: an unknown /foo is rejected before the turn starts and never reaches the model, so listing "/foo" among another skill's trigger phrases does nothing at all. Verified 2026-08-11 — a command the user reported typing by mistake "every now and then" appears in no session transcript. Fix a habitual typo where the name is resolved, in a personal command alias in the user's own config, never by adding an alias skill to this collection: every skill here costs description context in every session, for every user. And first establish which skill the user actually meant — an alias pointing at the plausible-but-wrong one converts a visible error into a silent wrong action.
  • Czech strings are functional, not accidental. Trigger phrases in descriptions and user-facing message templates exist because the primary user works in Czech; skills phrase runtime output in the configured language. Do not "translate them away". Documentation prose, on the other hand, is English. Three rules keep that from stranding an English user, all three added 2026-08-26 after an audit found the whole work-* suite failing them:
    • Say once that the quotes are examples. Right where the skill reads config.language, state that every quoted user-facing string below is an example written in cs. Without that sentence a table of labels reads as a canonical string spec and gets emitted verbatim — the risk is highest exactly where the strings are most table-like (work-reconcile's origin labels, its approval menu). Where an option is referred to again later, refer to it by its function (all, skip), never by its Czech string, or the reference re-canonises it.
    • Anything that fires before the config is read carries both languages inline, as "<czech>" / "<english>". A missing-config or missing-snapshot error has no configured language to fall back on, so "phrase it in the configured language" is unactionable there and the literal wins. This is the one place bilingual text is correct rather than lazy.
    • A setup skill asks the language before any other question, and defaults to en when nothing is detectable. work-setup asked it in step 6 while talking to the user from step 1, so a fresh English user got five Czech steps first.
  • Config defaults must not be localized. Message templates are rendered per user; default values are not. work-reconcile shipped calendar.exclude_keywords=["oběd","lunch","dovolená"], so an English user's Holiday/PTO blocks were reconstructed as billable work and written to their timesheet. A localized default is a data bug, not a cosmetic one — cover every language the skill claims to support, and remember the match is a plain substring test, where a short token (pto, off) eats unrelated events.
  • A skill is verified by running it, and not by its author. Reading a skill proves only that it reads well. Five /work-reconcile runs on 2026-08-26 each surfaced defects the previous ones had not, and the two most damaging — a coverage diff broken hours earlier, and a matching rule that contradicted its own worked example — were found only by a run in a clean context. Two things follow, and neither is optional for a skill that writes anywhere:
    • Run it outside your own context. An author re-reading their own text supplies the intent the text is missing. Dispatch a fresh-context agent, give it a neutral task rather than a hypothesis to confirm, and ask for verbatim output. Treat what comes back as claims to check, not findings to act on — one such report named a broken awk line that was in fact correct in the file.
    • Extract every embedded snippet and execute it against real data. Prose can be reviewed; code cannot. d.get('content') for a field actually named aiTitle, and date -u -j -f silently parsing local wall-clock as UTC, both read as obviously right and were both wrong — one blanked every row's description, the other shifted the window by the zone offset.
  • Removing a default is a change to every consumer downstream. Dropping work-reconcile's project fallback made project=null the normal case, and step 7 — which bucketed its busy map by (project, day) — then compared those blocks against an empty bucket, so nothing could ever mask them and a window already holding 33.3 h proposed 61.6 h more. Before removing a default, find every step that reads the field and check what it does with the empty value. The converse is the reason to remove it anyway: a skill that writes into a system of record must not invent attribution. No match means ask; a configured id meant for starting a timer is not an answer to where reconstructed time belongs.
  • A subagent near a writable system loses the credential path, not just the permission. Telling an agent "do not write" is a request; removing what it would need in order to write is a property. When dispatching one at a skill that posts to a tracker, deny it the file holding the API key rather than only forbidding the call — and confirm afterwards from the target's own state (entry count and highest id before and after) instead of trusting the report that says nothing happened.
  • Parallelize or delegate a step only where it pays, and name the subagent's model by tier. Three forms, cheapest first. Independent calls in one message cost nothing extra, so a step whose fetches or reads do not depend on each other says to send them together. One subagent fits a large read-only sweep whose raw material the main thread does not need, only its conclusion, or a step where a fresh context is the point (a refutation pass, a dry run by a non-author). Several subagents at once fit only when every branch is large on its own. Measured 2026-10-01 over 30 days and 339 spawns: a subagent starts with ~44k tokens of base context, came out 1.5–3× cheaper than inline work when the task was large and the main thread already heavy, and lost money on small tasks (~8 requests, ~9k tokens of output); a fan-out pays the base once per branch. Name the model by role with vendor examples, never by version: cheap for search, reading and extraction (e.g. Claude Haiku, OpenAI Luna), mid for analysis and synthesis (Claude Sonnet, OpenAI Terra), strongest for refutation and judgment that decides (Claude Opus, OpenAI Astra). Verified 2026-10-31: only Claude Code and Codex choose a model per spawn, and Codex drops the requested one when the call also names an agent_type whose role file sets none (openai/codex#22250). opencode, Copilot CLI and Antigravity CLI take a model only from a predefined agent or not at all, so there the subagent runs on the parent's model and the sentence costs nothing. Do not ship harness-specific agent definitions alongside a skill to close that gap; they live in a different place and format in every harness. Brief every subagent to return its verdict, its counts and what needs a decision, with the rest in a file.
  • A session transcript may go to a same-machine subagent, never to another service. Transcripts hold personal content, keys pasted into prompts and other people's messages, so what matters is whether that content leaves the provider the session already talks to. A subagent the harness spawns sends its context to that same provider, just as the main thread does. It may therefore read transcripts when its brief makes it read-only, gives it no web, network or other-provider tool, asks for structured fields (session id, times, project, a one-line description) instead of quotations, and keeps anything it writes on the machine. Pasting a transcript into a different model's CLI (as second-opinion does with its prompt), a web tool or a tracker comment is the external case and stays forbidden. A harness can run a subagent on another provider than its parent (opencode agent definitions may name any configured model); there, do the read inline. Decided 2026-10-31, when session-recall forbade any subagent while skillify deep already sent one over the last ten transcripts.
  • The repository is public; evidence from private work keeps its lesson, not its specifics. Rules here earn their place with a dated real case, and many of those cases happen in client repositories. Keep what makes the case checkable and the lesson transferable — the failure mode, the date, the counts — and leave out what identifies or exposes the client: repository and PR numbers, internal module, ticket and feature names, and above all the content of a security or cost finding, which in a public repo reads as a map of the client's weak spot. Seen 2026-09-27: a code-review rule written by a session reviewing a client PR arrived carrying the finding itself; the auto-mode classifier refused the commit as excess sensitive detail, and the generalized wording lost nothing the rule needed. The same holds for work landed on another session's behalf, and there the specifics hide in places a reviewer does not read as content: a trigger phrase naming the real colleague the skill was first used on, a client's ticket prefix in an anti-pattern example, and the authoring session's title in the commit body. Seen 2026-10-02 in one new skill and one commit message. Read every added line before landing it, and identify the authoring session by its id alone. A skill verified by a dry run on client data inherits the client's shape in quieter ways still: its worked example copied the client's real meeting schedule and dates and the phrase "both lists" from the client's two-list tracker, and the commit body of a follow-up fix quoted a fragment of the client tracker id that had prompted it. Seen 2026-10-13. A grep for names caught neither, and the commit message was read only after the push, so removing the fragment took an amend and a force-push. Read the numbers, dates and ids in a new example by eye, and read the commit message before pushing as well.
  • kodex is a regular skill with an always-on pointer: one line in the user's instructions file makes agents load it before non-trivial work; rules/kodex.md is that line for Antigravity's rules mechanism, with the Czech wording of the same line in rules/kodex-cs.md (README offers both). The English text in SKILL.md is canonical; the Czech original lives in references/kodex-cs.md. That is four copies of the same instruction — the two pointer lines and the two codex bodies — and they have to move together.
  • Bundled assets (scripts/, references/, templates) belong inside the skill's directory and are referenced by paths relative to it.

Dev loop

Edit in a working clone. Symlinked installs (above) see changes immediately; copy installs refresh with npx skills add . -g -y --all — which also flattens any symlinks back into copies, so re-run the symlink loop after it. Verify discovery with npx skills add . --list (every skill must appear). bin/check-skill-drift.py reports deployed skills under ~/.agents/skills/ that have drifted from this clone, and, on a machine that otherwise runs live symlinks, those deployed as identical copies (silent when nothing differs), so run it when an installed skill may be a stale copy. When adding a skill, also add a row to the README table.

Changelog. CHANGELOG.md is date-grouped and scope-prefixed (skill name, or repo for collection-wide changes). Every feat/fix commit — and any other change that alters an installed skill's behavior or config contract — adds a line under today's date in the same push; typo/refactor/chore noise stays out. There are no repo-level versions or tags; the complete per-skill history remains git log -- skills/<name>/.

CHANGELOG.md and the README skill table are cross-session contention points. Every skill add appends to both, and with many sessions running against one clone at once they routinely hold another session's uncommitted rows and entries — so commit your own skill work by staging only your own hunks (git apply --cached a hand-built patch, or git add -p), never git add CHANGELOG.md/README.md wholesale, or the commit sweeps up work another session has not finished. Seen 2026-09-03: landing one skill's docs meant patch-staging around three other skills' pending rows in the same two files.

Sessions from other projects edit this clone, and some cannot commit here. A retro or a skill fix running in another project writes straight into the source in this clone — the live symlinks make the edit effective at once — but a worktree isolation guard can refuse git outside that session's own worktree, so the session hands the commit to the user and moves on. Seen 2026-09-27: edits to four files from three such sessions had sat uncommitted for two days, each session having deferred the commit, and none carried its CHANGELOG line or version bump. Before committing someone else's hunk, find its author: search the transcripts for the path (grep -rl --include='*.jsonl' '<clone>/<file>' <harness-home>/projects/, which also reaches subagent transcripts), keep the files where it is the file_path of a write or edit, and read that session's closing message for what it intended. Search the installed path as well (~/.agents/skills/<name>/…, ~/.claude/skills/<name>/…): the live symlinks let a session edit the clone through either, and its transcript then records only that path. Seen 2026-10-10: a pending task-delivery hunk had been written through ~/.agents/skills/task-delivery/SKILL.md, and the clone-path search returned nothing for it. A path search misses edits made through a script or a heredoc, so also search for a distinctive phrase from the hunk itself in the inputs of the write, edit and shell tool calls. Seen 2026-10-02: four of eleven pending hunks had been written by a patch script, a heredoc, or a copy edited outside the clone, and only the phrase search found their authors. Then land each originating change as its own commit, adding the CHANGELOG line and version bump it skipped, with a line in the body saying whose work it was.

Landing from a worktree leaves the main checkout holding a duplicate. A session isolated to its own worktree can land those hunks there and push to main, but the main checkout still carries the same content as uncommitted changes, and git pull refuses to overwrite them. Do not commit them a second time; that duplicates every README row and CHANGELOG line. Instead, confirm that every line the checkout adds relative to its own HEAD already exists on origin/main. Then restore the changed files to HEAD, remove untracked directories that were landed, and pull. Two things block that last step from inside the isolated session. Git aimed at the shared checkout, even with -C, is refused while the same command against another repository goes through. And the user's own ! commands run under the same guard, failing with a bare "detail withheld" instead of git's message, so the pull belongs in a plain terminal. One more blocker seen 2026-10-02: a session had recovered a commit with git cherry-pick after a stray reset, and the leftover CHERRY_PICK_HEAD made pull refuse. With HEAD already on that commit and the tree clean, clear it with git cherry-pick --quit. Never use --abort, which moves HEAD back and can take the recovered commit with it.

Skill versions. Some skills carry a frontmatter version, inherited from their Claude-plugin origin; it is optional, ignored outside Claude Code, and never added to a skill that lacks it. When a skill that has one changes behavior, bump it — patch for a fix, minor for a feature — and name the resulting version in parentheses at the end of its CHANGELOG line (… (v1.6.1)). Skills without the field get an unversioned line.

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.