claude-skills
CLAUDE.md0 starsChanged 3 months agoMITView on GitHub
Instructions for Claude Code when working in this repo. When a skill needs an API key or other credential, follow the pattern established by granola — see granola/references/proton-pass-setup.md for the full worked example and exact commands. - Reference file, not a bespoke registry. <skill>/<skill>.env.example (committed) → <skill>/<skill>.env (gitignored), holding ENV_VAR=pass://vault/item/field. This is pass-cli run --env-file's native format — there is no cross-vendor standard for ENV_VAR → secret reference mappings, and dotenv-with-references is the closest thing to a de-facto one (1Password's…
- Reads credentials
In this repository10 other files it gives its agents.
- context-handoffSkill
- councilSkill
- deck-design-promptSkill
- doc-to-markdownSkill
- granolaSkill
- mckinsey-deckSkill
- pdf-to-markdownSkill
- url-to-markdownSkill
- wargameSkill
- yt-transcriptSkill
The file
We split this CLAUDE.md into the rules it gives an agent
2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 7
When a skill needs an API key or other credential, follow the pattern established by granola — see granola/references/proton-pass-setup.md …
- Very specific: line 59
If the *caller's* environment ever sets PROTON_PASS_SESSION_DIR unconditionally for unrelated reasons (see the lockdown note below — this …
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.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
CLAUDE.md
Instructions for Claude Code when working in this repo.
Secrets in skills
When a skill needs an API key or other credential, follow the pattern
established by granola — see granola/references/proton-pass-setup.md for
the full worked example and exact commands.
- Reference file, not a bespoke registry.
<skill>/<skill>.env.example(committed) →<skill>/<skill>.env(gitignored), holdingENV_VAR=pass://vault/item/field. This ispass-cli run --env-file's native format — there is no cross-vendor standard forENV_VAR → secret referencemappings, and dotenv-with-references is the closest thing to a de-facto one (1Password'sopand Proton Pass'spass-cliimplement it with near-identical flags). - Resolve via
pass-cli run, nothing else. The launcher (<skill>/scripts/<skill>.sh) doespass-cli run --env-file <skill>.env -- <command>. Neverpass-cli item view,run -- env, or echo the resolved var — those print the plaintext value. Masking onrunis best-effort (catches literal occurrences in streams it controls; doesn't catch encoded/transformed values or anything written straight to a file by the client). - Vault name = the service, agent name = the skill. These are not the
same thing, and it only looks that way when a skill and its service happen
to share a name (e.g.
granola/Granola). A vault holds a credential for an external service — multiple skills may legitimately want the same one (aurl-to-markdownskill and a futureweb-researchskill could both need Firecrawl). So: one dedicated single-item vault per service, reused across skills that need it; one agent per skill, even when two skills share a vault — that's what lets you revoke one skill's access without touching the other, and gives audit-log separation by cryptographic identity rather than a self-reported reason string.
This gives read-only, minimum-privilege access plus an audit trail (pass-cli vault create --name "<Service>" # store the credential in that vault, then, once per skill that needs it: pass-cli agent create <skill>-reader --expiration 1y pass-cli agent access grant <skill>-reader \ --vault-name "<Service>" --role viewerpass-cli agent monitor <skill>-reader). Item-scoped grants (--item-title) do not work withpass-cli run --env-file:pass://resolution requires a named vault, and an item-scoped session has zero vault visibility (pass-cli vault listreturns empty under it) — everypass://form fails withCould not find vault …, confirmed againstpass-cli's own source. A dedicated single-item vault gets the same isolation through the officially documented mechanism instead — Proton's own guidance is to organize agent credentials in vaults, not to lean on item-level shares for automation. Reserve item-level grants for what they're actually for: sharing one item from an otherwise-private vault with another person, consumed via explicitpass-cli item view --share-id --item-id, neverrun/inject. - One session directory per skill, via a skill-specific override
variable — never the bare
PROTON_PASS_SESSION_DIRname. Default to~/.pass-sessions/<skill>, but make it overridable through something like<SKILL>_RUNTIME_SESSION_DIR, not${PROTON_PASS_SESSION_DIR:-default}. If the caller's environment ever setsPROTON_PASS_SESSION_DIRunconditionally for unrelated reasons (see the lockdown note below — this is exactly what happened), a bare${PROTON_PASS_SESSION_DIR:-default}fallback silently inherits that instead of falling through to the skill's own default, and the runtime session ends up trying to authenticate against the wrong directory. This failure mode is non-obvious: it looks like a login/token problem, not a "wrong directory" problem. Session dirs are otherwise just files on disk read per-invocation; skills with their own dir don't interact at all, including when run concurrently in the same project. - Gate on file existence, not a config flag: if
<skill>.envis missing, print setup instructions to stderr and exit non-zero (reserve a distinct exit code for "not configured" vs. "pass-cli not found" vs. auth failure — seegranola/scripts/granola.shfor the pattern). - Self-heal the runtime session, don't make the user babysit it. Agent/PAT
sessions expire every ~2h; store the agent token as its own Proton Pass item
(e.g.
Agents/<Skill> Agent Token, fieldtoken) and have the launcher checkpass-cli infoagainst its session dir before running — on failure, fetch the token via the caller's personal session andpass-cli loginwith it, then proceed. This makes routine expiry invisible; only two things should ever surface to the user: the personal session also being stale (rare — they use it daily), or the token itself hitting its yearly expiration (agent renewis a manual, deliberate step — don't auto-renew on failure, since that would mean an unattended process can rotate its own long-lived credential). Seegranola/scripts/granola.shfor the reference implementation. - If Claude Code's own
pass-cliaccess is locked down (its Bash calls repointed to a dead-endPROTON_PASS_SESSION_DIRviasettings.jsonenv, plus aPreToolUsehook denying directpass-cli/PROTON_PASS_*commands — check~/.claude/settings.jsonand~/.claude/hooks/for whether this repo's user has set this up), a vetted wrapper script is the one thing still trusted to reach the personal session, by design. Two things break under that lockdown if not handled explicitly: (1) anypass-clicall meant to use the personal session must pinPROTON_PASS_SESSION_DIRto a skill-specific override variable (e.g.<SKILL>_PERSONAL_SESSION_DIR, defaulting to pass-cli's own platform default path) rather than relying on "no override" — the ambient value is no longer empty, it's the dead end; (2) per the point above, the skill's own runtime-session variable must not derive from barePROTON_PASS_SESSION_DIReither, for the same reason. Both mistakes were made and fixed once already ingranola.sh— read it before writing a new wrapper under an active lockdown. - Document setup and renewal in
<skill>/references/proton-pass-setup.md, written for the human to run themselves. Creating the agent is fine to do on the user's behalf if you're already driving a shell with their permission, but logging in with a raw PAT/agent token is not — that command carries a live secret through the tool-call transcript and should be left to the user (Claude Code's own permission classifier will typically block it anyway).
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.

