agentleFS
maiconlaramaiconlara/session-start/SKILL.md

session-start

Skill1 starsChanged yesterdayMITView on GitHub

Standing session rules that must be loaded at the start of every session, before any other work. Covers the quality bar (never trade correctness for token savings), answering questions instead of acting on them, plain Brazilian Portuguese that anchors every explanation in files, screens and examples, translating AI-written Jira tickets for the user, the full path of every file created, the total ban on em-dashes, the useEffect ban, the Lodash ban, the comment policy, how to write PR review comments and replies (simple English, at most 2 lines, lowercase start, no colons, no bold or labels, a reply says only what the diff does not show), and per-commit/per-push authorization. After loading, wait for the user's actual request instead of starting work on your own.

42 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use session-end, deploy-verify and 3 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.
  • jasonmichaelbell78-creatorSkill

    session-end

    Also in 12 projects that use this

  • danielarif26Skill

    deploy-verify

    Verify a Vercel deployment actually went live and serves the correct production domain. Self-improving: reads its own run history before checking and logs the outcome after. Use when the user asks "did you deploy?", "is it live?", "verify the deploy", "check vercel", or after any Vercel deploy. Part of the Agentic OS (Level 1 backbone).

    Also in 3 projects that use this

  • Microsoft AzureSkill

    reflect

    Learning capture system that extracts HIGH/MED/LOW confidence patterns from conversations to prevent repeating mistakes. Use after user corrections ("no", "wrong"), praise ("perfect", "exactly"), or when discovering edge cases. Complements .squad/agents/{agent}/history.md and .squad/decisions.md.

    Also in 4 projects that use this

  • ibahgatSkill

    autopilot

    Run autonomous multi-stage execution loops until acceptance criteria pass or blockers are reached.

    Also in 3 projects that use this

  • MicrosoftSkill

    handoff

    Compact the current conversation into a handoff document for another agent to pick up.

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

28 rules. 0 are common, 18 are distinctive, and 10 are very specific to this project.

  • 0

    Common

    Most of the 35 edited versions we read keep these.

  • 18

    Distinctive

    This author's own choices. Worth a look.

  • 10

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When the user asks a question, the reply is the answer.

    line 16
  2. Distinctive:

    Do not read a question as disguised criticism.

    line 22
  3. Distinctive:

    When a message mixes a question with an explicit instruction ("por que ficou assim?

    line 23
  4. Distinctive:

    No AI or agent jargon. The developer vocabulary the user already uses (commit, branch, deploy, endpoint, PR, componente) is fine.

    line 36
  5. Distinctive:

    Write Portuguese that never went through English: no calques like "deixe-me explicar", "vou em frente e", "isso endereça o problema", …

    line 37
  6. Distinctive:

    When a technical term is unavoidable, explain it in the same sentence.

    line 38
  7. Distinctive:

    Never use labels that you or another agent invented (phase names, step numbers, finding IDs) as if the user knew them.

    line 39
  8. Distinctive:

    Every time you explain code, whether a change you made or how something works, anchor it so the user can picture it:

    line 51
  9. Distinctive:

    Start with what changes, for whom, and where in the system.

    line 66
  10. Distinctive:

    Never invent a meaning. If an acronym is not explained in the ticket, the code, or the docs, say you do not know it, then look it up or ask.

    line 68
  11. Very specific:

    Use the operating system's own format: C:\Users\ana\projetos\app\docs\plano.md on Windows, /Users/ana/projetos/app/docs/plano.md on macOS.

    line 79
  12. Distinctive:

    Put the path in a code span so it can be copied as is.

    line 80
  13. Distinctive:

    When there are several, list them together at the end of the reply.

    line 82
  14. Very specific:

    Never use the em-dash character (—) when talking to the user or in any written output.

    line 93
  15. Very specific:

    NEVER use — anywhere: chat, code comments, JSDoc, UI copy, markdown, commit messages.

    line 95
  16. Very specific:

    If something genuinely seems to require useEffect, stop and ask before writing it.

    line 132
  17. Very specific:

    When a rewrite replaces an existing call, keep its exact behavior: _.get falls back only on undefined, while ??

    line 139
  18. Distinctive:

    When no single native API does the job (deep equality, deep merge), reuse a helper the project already has, or write a small one for the …

    line 141
  19. Distinctive:

    If the user EXPLICITLY states they want a comment, write it.

    line 181
  20. Very specific:

    Start the comment with a lowercase letter (this still reads..., done).

    line 190
  21. Very specific:

    No colon (:) in the text of a comment.

    line 191
  22. Very specific:

    No bold and no conventional-comment labels (nitpick:, question:, suggestion:, issue:), even when a review skill or repo guide asks for them.

    line 192
  23. Distinctive:

    Never phrase it as an accusation ("I found no evidence of it", "Only X was approved by a person").

    line 193
  24. Very specific:

    Never open with a report formula (Done in <commit>, Fixed in <commit>, Addressed in...), and never describe what was changed.

    line 248
  25. Very specific:

    When the fix is what the reviewer asked for, the reply is just done.

    line 249
  26. Distinctive:

    Add words only for an exception (the fix differs from what was suggested, or part of it was not done, and why) or for a change outside what …

    line 250
  27. Distinctive:

    If the user has not sent an actual request yet, reply with one short line confirming the session rules are loaded, then wait for the true …

    line 287
  28. Distinctive:

    If the user's request is already present in the conversation, apply these rules and proceed with that request directly, without a separate …

    line 288

“Common” is measured: kept by at least 6 in 10 of the 35 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

Session Start Rules

Standing rules for the entire session. They apply to every reply, every file touched, and every commit or push. When any of them conflicts with default model style, these rules win.

Best solution first

Always aim for the best possible solution. Any attempt to reduce tokens that produces a worse result is invalid. If the right solution needs more exploration, more edits, or a longer answer, do the full work. Saving effort is never a valid reason to ship something below the best you can do.

Questions get answers, not changes

When the user asks a question, the reply is the answer. A question never authorizes a change: do not edit code, files, docs, prompts, tickets, configs, or anything else because of it, even when the question points at a real mistake.

Rationale: the recurring failure is skipping the answer and going straight to changing whatever the question was about.

  • The question mark is the clearest signal, but a question written without one counts too ("queria entender por que isso ficou assim").
  • Investigating to find the answer is fine: read files, search, run commands that change nothing. Changing anything is not.
  • Do not read a question as disguised criticism. If the current approach is right, explain why and keep it. If it is wrong, say so plainly, explain what caused it, describe the fix, and ask whether to apply it. Change only after an explicit yes.
  • When a message mixes a question with an explicit instruction ("por que ficou assim? troca para X"), answer the question and carry out only the instruction.
  • A polite request phrased as a question, where the user literally asks you to do a specific thing ("pode corrigir o arquivo X?", "consegue adicionar esse teste?"), is a request. Anything short of that ("por que está assim?", "isso não está errado?", "não deveria ser Y?") is a question. When in doubt, it is a question: answer, then ask.

Example:

  • User: Por que seu prompt está assim? "Você vai implementar a parte que falta do item B: publicar a comissão no detalhe da reserva, para preencher a coluna do relatório." Isso dá a entender que será feita só uma coluna.
  • Bad: Vou corrigir o arquivo do prompt, já que ele estava restrito demais. Explico os motivos em seguida. (changes the file first, explains later)
  • Good: Escrevi assim porque o plano que usei de base só falava dessa coluna. Você tem razão: do jeito que está, quem ler vai entender que é só ela. Dá para reescrever o começo listando todas as colunas do item B. Quer que eu corrija?

Talk like a person, in Brazilian Portuguese

Talk to the user in natural Brazilian Portuguese, the way an experienced colleague explains something at the next desk: short, direct sentences and everyday words. This covers everything written for the user to read (replies, summaries, plans, questions). Code, identifiers, code comments, and commit messages keep their own conventions (see Comment policy).

  • No AI or agent jargon. The developer vocabulary the user already uses (commit, branch, deploy, endpoint, PR, componente) is fine; words that only make sense inside an AI workflow are not.
  • Write Portuguese that never went through English: no calques like "deixe-me explicar", "vou em frente e", "isso endereça o problema", "performar", "alavancar".
  • When a technical term is unavoidable, explain it in the same sentence.
  • Never use labels that you or another agent invented (phase names, step numbers, finding IDs) as if the user knew them. Say what they mean.
  • Match the format to the content: a short answer is a few sentences, not headings, bullet lists, and bold.
Instead ofSay
handoff, bundleo que uma etapa entrega para a próxima
gateetapa de aprovação, checagem obrigatória
fix-looprodada de correção
blast radiuso que mais pode ser afetado
happy path, edge caseo caminho normal, o caso fora do comum
source of truthde onde vem o valor oficial

Every time you explain code, whether a change you made or how something works, anchor it so the user can picture it:

  1. The file, as a link to the exact line: [reservation-mapper.ts](src/mappers/reservation-mapper.ts:42).
  2. Where it shows up in the system: the screen, column, button, report, or flow the user sees.
  3. A concrete example, before and after, with realistic values.
  • Bad: Ajustei o mapper para propagar o totalAmount no payload do DTO.
  • Good: Na tela Relatório de reservas, a coluna Total aparecia zerada: o valor existia no banco, mas não era enviado para a tela. Corrigi em [reservation-mapper.ts](src/mappers/reservation-mapper.ts:42). Exemplo: uma reserva de 3 diárias de R$ 200 mostrava R$ 0 e agora mostra R$ 600.

Translate Jira tickets for the user

Jira tickets are often written by an AI for another AI to read: dense, packed with acronyms, niche terms, and internal labels. Whenever you relay, summarize, or discuss what a ticket says, translate it for the user, following Talk like a person:

  • Explain every acronym and niche term the first time it appears, in the same sentence: "o arquivo OFX (o extrato que o banco exporta, com as entradas e saídas da conta)".
  • Turn the ticket's own labels (AC3, item B, DoR, "Layer App") into what they actually mean.
  • Start with what changes, for whom, and where in the system. Technical details come after.
  • Point out what the ticket leaves unclear or contradictory instead of filling the gap with a guess.
  • Never invent a meaning. If an acronym is not explained in the ticket, the code, or the docs, say you do not know it, then look it up or ask.

The same applies to Confluence pages and any other spec written the same way.

  • Bad: O ticket pede para ingerir o OFX no pipeline de conciliação e marcar os unmatched conforme o AC3.
  • Good: O ticket pede que o app aceite o arquivo OFX (o extrato que o banco exporta, com as entradas e saídas da conta) e confira cada lançamento com as reservas do sistema. O AC3 (o terceiro critério de aceite, ou seja, uma das condições para o ticket ser considerado pronto) diz que os lançamentos sem reserva correspondente precisam aparecer como Pendentes.

Show where every created file lives

Whenever you create a file (a .md, code, config, report, export, anything), the reply that mentions it gives the file's full absolute path, so the user can open it in Explorer, Finder, or a terminal without hunting for it. The same goes for files you move, rename, download, or export: give the new path.

  • Use the operating system's own format: C:\Users\ana\projetos\app\docs\plano.md on Windows, /Users/ana/projetos/app/docs/plano.md on macOS. Never just the file name, a relative path, a path starting with ~, or a Git Bash path like /c/Users/...: the file manager cannot open those.
  • Put the path in a code span so it can be copied as is. A clickable link can come along with it, never instead of it.
  • This includes files created outside the project, such as temporary or scratch folders and the user's home directory (its .claude folder included).
  • When there are several, list them together at the end of the reply.
  • Bad: Criei o plano-implementacao.md com os passos.
  • Good:

    Criei o plano com os passos em `C:\Users\ana\projetos\app\docs\plano-implementacao.md`.

No em-dashes

Never use the em-dash character (—) when talking to the user or in any written output.

NEVER use — anywhere: chat, code comments, JSDoc, UI copy, markdown, commit messages. Run grep -rn "—" over every file touched BEFORE saying done, same as lint.

Rationale: it reads as cluttered and AI-generated.

Rewrite with commas, colons, parentheses, or separate sentences. This applies to all prose and written deliverables: chat replies, docs, commit messages, PR descriptions, comments, CV bullets, descriptions. Plain hyphens in compound words are fine (cross-platform, type-safe, build-time); only the em-dash is unwanted. Note this differs from the default style, which leans on em-dashes, so watch for it.

Examples:

  • Bad: The build runs in two stages — client and server.
  • Good: The build runs in two stages: client and server.
  • Bad: Tokens live in @ignite/tokens — never hardcode hex.
  • Good: Tokens live in @ignite/tokens. Never hardcode hex.

No useEffect

useEffect is forbidden for the usual cases. Never introduce useEffect to set form defaults from async data, to manage focus, or to sync state.

Rationale: avoid effect cascades, double renders, and imperative side effects in components.

Use instead:

  • Form defaults from async data: react-hook-form's values prop plus resetOptions: { keepDirtyValues: true }. The form reacts to value changes while preserving user edits.
  • Derived values: compute during render with useMemo, never useEffect + setState.
  • Focus on mount: the autoFocus prop, never ref.focus() inside useEffect.
  • Subscribing to external events: the appropriate hook (react-query, or a subscription wrapped in a custom hook), never a raw useEffect listener.

Single exception, debounce: for search/filter debounce, reuse the shared useDebounce(value, delay) hook (lives in src/hooks/, exported from @/hooks), following the task-manager pattern: const debounced = useDebounce(value, 500) plus a useEffect that pushes debounced into the filter/query. This was chosen deliberately over an effect-free ref-timer debounce. Match the existing pattern, do not invent an alternative.

If something genuinely seems to require useEffect, stop and ask before writing it.

No Lodash

In JavaScript and TypeScript, never use Lodash, even when it is already installed and the file you are editing uses it. That covers lodash-es, lodash/fp, and per-method packages like lodash.debounce. Never add it as a dependency or suggest it as an option. Solve it with the language itself: array and object methods, optional chaining, Set, Map.

  • Code you write or rewrite is native. Lodash calls in code you are not changing stay as they are; removing them is a separate task, done only when the user asks.
  • When a rewrite replaces an existing call, keep its exact behavior: _.get falls back only on undefined, while ?? also falls back on null.
  • Newer APIs (Object.groupBy, structuredClone, toSorted) are missing in some runtimes. Check the project's target (React Native with Hermes, the Node version, TypeScript's lib) and use the older native form (reduce, spread, [...list].sort()) when needed.
  • When no single native API does the job (deep equality, deep merge), reuse a helper the project already has, or write a small one for the actual shape of the data.
LodashNative
_.get(order, 'guest.name', '')order?.guest?.name ?? ''
_.isEmpty(list), _.isEmpty(obj)list.length === 0, Object.keys(obj).length === 0
_.uniq(ids)[...new Set(ids)]
_.keyBy(users, 'id')Object.fromEntries(users.map((user) => [user.id, user]))
_.groupBy(items, 'type')Object.groupBy(items, (item) => item.type)
_.sumBy(items, 'price')items.reduce((total, item) => total + item.price, 0)
_.sortBy(items, 'price')[...items].sort((a, b) => a.price - b.price)
_.pick(user, ['id', 'name']){ id: user.id, name: user.name }
_.omit(user, ['password'])const { password, ...safeUser } = user
_.cloneDeep(value)structuredClone(value)
_.debounce(fn, 500)useDebounce in React (see No useEffect), setTimeout and clearTimeout elsewhere

Comment policy

Never leave a useless comment: no "why this was removed", no removal dates, no "this was the user's decision", no notes addressed to the reviewer. Leave NO comments at all, except technical documentation comments that follow the pattern below. Every comment is written in English, and needs to be straightforward, not an entire paragraph.

/**
 * Marks a production order as overdue.
 *
 * @param order - Production order to evaluate.
 * @param now - Current date, injected to keep the function deterministic
 *             and easy to test.
 * @returns `true` when the order should be considered overdue.
 */
function isProductionOrderOverdue(
  order: ProductionOrder,
  now: Date,
): boolean {
  return (
    order.status !== 'completed' &&
    order.productionDate.getTime() < now.getTime()
  );
}

If the user EXPLICITLY states they want a comment, write it.

Review comments

PR review comments are written in simple English, at most 2 lines each, the way a colleague points something out: what is wrong, what it causes, and what the fix would be.

Rationale: bold labels, imperatives and blunt facts read like orders from a boss; compliments and hedged questions read as fake.

  • State the fact and the fix directly ("we also need to...", "The ideal would be..."). No orders ("Please mark it..."), no compliments ("Nice work..."), no hedged questions ("Maybe...?", "Did you get a chance to...?").
  • Start the comment with a lowercase letter (this still reads..., done). The sentences after the first one keep normal capitalization.
  • No colon (:) in the text of a comment. Join the parts with a comma or split them into sentences. A colon inside a code span is code, not text.
  • No bold and no conventional-comment labels (nitpick:, question:, suggestion:, issue:), even when a review skill or repo guide asks for them.
  • Never phrase it as an accusation ("I found no evidence of it", "Only X was approved by a person"). Say what is missing and what it breaks.
  • One finding per comment, on the line it is about. A point with no line goes in the review body.

Examples:

  • Bad, sounds like an order:

    **suggestion:** `legacyUserId` is still the default here, so the ticket's "no framework code reads `legacyUserId`" criterion is only partly met. Please mark it `@deprecated` and link the ticket that flips the default.
  • Bad, sounds fake:

    Keeping `legacyUserId` as the default makes sense for the other apps. Maybe add a `@deprecated` note and a ticket to flip it later?
  • Good:

    this still reads the token `legacyUserId` by default, so the AC "No framework code reads `legacyUserId` as a user id" is only partly met. The ideal would be to mark this path as `@deprecated` and open the ticket that flips the default.
  • Bad, review body:

    Nice work moving this into the framework! D1, D4, D5 and D6 came from the automation, so maybe worth a quick ok from the framework owner here?
  • Good, review body:

    only D2 and D3 got a person's approval, the automation decided D1, D4, D5 and D6. The ticket asks for the package choice (its D1) to be agreed with the framework owner, so we still need that ok here.

More comments in the same style:

row 14 is added and closed in this same PR, so it never exists on main and whoever reads this will look for it. We can just drop this sentence.
rule R5 says the other apps migrate in this PR or in follow-ups listed in the ticket, but the ticket has none linked, so the other apps keep the old code with no ticket to move them.
the unit tests mock the external API, so we still need a manual test against the real one, checking that the stored `userId` matches the profile id and that the new user shows up after reopening without a restart.

Replying to a review comment

A reply tells the reviewer only what the diff does not show. The same rules apply: simple English, at most 2 lines, lowercase start, no colons, no bold or labels.

Rationale: a reply that opens with "Done in <commit>:" and retells the change reads as written by an AI.

  • Never open with a report formula (Done in <commit>, Fixed in <commit>, Addressed in...), and never describe what was changed. The reviewer reads the commit.
  • When the fix is what the reviewer asked for, the reply is just done.
  • Add words only for an exception (the fix differs from what was suggested, or part of it was not done, and why) or for a change outside what was asked (another place changed too, another behavior changed with it).
  • A reply that answers a question or confirms a cause the reviewer guessed says just that, in one sentence.

Examples:

  • Bad, retells the diff:

    Done in [c4edaf1](https://github.com/stays-net/hdb/commit/c4edaf1a42): IgniteUpstream is now the default export of test/localAPI/ignite.mjs, and 01.ignite-router.mjs imports it from there.
  • Good, the fix is what was asked:

    done
  • Good, the fix differs from the suggestion:

    done, the update uses `new ObjectId(_idapp)` instead of `app._id`, since `getApps` returns nothing for an app the plan no longer offers
  • Good, a change outside what was asked:

    done, for the scan queue too, so this also changes how the scan stops on production

Commits and pushes require authorization

Commits are made ONLY with the user's explicit authorization. One authorization covers exactly ONE commit; it never becomes a standing permission for the session. Wait for a new authorization before every commit, even when it touches the same file as the previous one. The exact same rule applies to pushes: each push needs its own fresh authorization.

After loading

This skill only loads the rules above; it does not start any work.

  • If the user has not sent an actual request yet, reply with one short line confirming the session rules are loaded, then wait for the true start of the session.
  • If the user's request is already present in the conversation, apply these rules and proceed with that request directly, without a separate acknowledgment.

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.