From 15ec1ceac01a0962920209cd725c5be7cbd5a231 Mon Sep 17 00:00:00 2001 From: Matthew Batchelder Date: Sat, 23 May 2026 21:40:14 -0400 Subject: [PATCH 01/18] chore: drop the plugin/skill from gh-pages (now lives on main) --- skills/skill-patterns/README.md | 78 ------ skills/skill-patterns/SKILL.md | 41 ---- .../references/choosing-patterns.md | 27 --- skills/skill-patterns/references/patterns.md | 227 ------------------ 4 files changed, 373 deletions(-) delete mode 100644 skills/skill-patterns/README.md delete mode 100644 skills/skill-patterns/SKILL.md delete mode 100644 skills/skill-patterns/references/choosing-patterns.md delete mode 100644 skills/skill-patterns/references/patterns.md diff --git a/skills/skill-patterns/README.md b/skills/skill-patterns/README.md deleted file mode 100644 index 85e8d9e..0000000 --- a/skills/skill-patterns/README.md +++ /dev/null @@ -1,78 +0,0 @@ -# skill-patterns - -A skill that helps you **build better Skills**. When you're creating or improving an agent Skill, it figures out which skill-design patterns the skill's purpose calls for — grounding, critique, decision-making, output shaping, control, composition — and weaves them in for you, so you don't have to hand-pick them. - -Backed by the catalog at [skillpatterns.ai](https://skillpatterns.ai). - -## What it does - -When you start writing or editing a `SKILL.md`, this skill: - -1. **Grounds** in the full pattern catalog (bundled in `references/patterns.md`). -2. **Reads the skill's purpose** — what it does, its inputs/outputs, and what could go wrong. -3. **Selects the patterns that fit** using an intent → pattern guide (`references/choosing-patterns.md`), applies the clear fits, and proposes the borderline ones. -4. **Shows you what it applied and why**, so you can adjust — or take over and pick yourself. - -It deliberately keeps things lean (most skills need only 2–4 patterns) and asks before anything high-stakes. You get pattern-informed skills by default, without reading the whole catalog or choosing manually. - -## Install - -### Via `npx skills` (recommended) - -```bash -npx skills add https://github.com/borkweb/skill-patterns --skill skill-patterns -``` - -Once it's listed on [skills.sh](https://skills.sh), you can also discover it with: - -```bash -npx skills find skill-patterns -``` - -The `npx skills` ecosystem installs into Claude Code, Cursor, Codex, Gemini CLI, and other supported agents. - -### Manual (Claude Code) - -Copy this skill's directory into your skills location: - -```bash -# Personal (available everywhere) -cp -R skill-patterns ~/.claude/skills/skill-patterns - -# or Project-scoped (shared with the repo) -cp -R skill-patterns .claude/skills/skill-patterns -``` - -Claude Code auto-discovers it — no restart needed for project skills. - -## Using it - -- **Automatic:** just start building a skill ("create a skill that…", "improve this SKILL.md") and it activates, applying the relevant patterns and noting what it chose. -- **Manual:** invoke `/skill-patterns` to apply it deliberately. -- **Drive it yourself:** say "let me pick" and it'll show the relevant patterns and apply only what you choose. - -**Verify (Claude Code):** run `/help` and look for `skill-patterns` in the list. - -## What's inside - -``` -skill-patterns/ -├── SKILL.md # the skill: when it applies + the apply-by-default flow -└── references/ - ├── choosing-patterns.md # intent → pattern decision guide - └── patterns.md # full catalog snapshot (definitions + example prompts) -``` - -## Maintenance - -`references/patterns.md` is a generated snapshot of the live catalog. When the catalog changes, regenerate it from the site's machine-readable export: - -```bash -curl -s https://skillpatterns.ai/llms.txt > references/patterns.md -``` - -The catalog is also available as structured data at [`skillpatterns.ai/patterns.json`](https://skillpatterns.ai/patterns.json). - -## License - -MIT. diff --git a/skills/skill-patterns/SKILL.md b/skills/skill-patterns/SKILL.md deleted file mode 100644 index 9b24957..0000000 --- a/skills/skill-patterns/SKILL.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -name: skill-patterns -description: Use when creating or improving an agent Skill (writing or editing a SKILL.md) — selects and applies the skill-design patterns the skill's purpose calls for, so the author doesn't have to hand-pick them. Triggers on "create a skill", "write a SKILL.md", "improve this skill", "make a skill that…", "turn this into a skill". ---- - -# Skill Patterns - -A catalog of reusable, *behavioral* patterns for agent Skills — grounding, critique, decision-making, output shaping, control, and composition. When someone is building or improving a Skill, apply the patterns that fit its purpose **by default**, without making the author pick. - -## When this applies - -Whenever you're authoring or revising a Skill's instructions: drafting a new `SKILL.md`, improving an existing one, or designing a multi-step skill or workflow. If the user is doing something else, skip it. - -## How to apply patterns (default flow) - -1. **Ground in the catalog.** Read `references/patterns.md` for the full set — each pattern's definition, what it adds, and a ready-to-adapt example prompt. Treat it as authoritative; prefer it over improvising patterns from memory. (If you have network access and want the latest, the live source is `https://skillpatterns.ai/llms.txt`.) - -2. **Understand the skill's job.** In a sentence or two: what does it do, what are its inputs and outputs, and what could go wrong — irreversible actions? ambiguous briefs? facts that must be right? multiple data sources? machine-read output? - -3. **Select by intent — don't make the user choose.** Use `references/choosing-patterns.md` to map the skill's characteristics to candidate patterns, then classify each: - - **Clear fit** → apply it. Weave its example-prompt guidance into the `SKILL.md` you're writing, adapted to this skill (fill the `[brackets]`). - - **Plausible** → mention it in one line and let the author decide. - - **Not relevant** → leave it out silently. - -4. **Don't over-apply.** Most good skills use **two to four** patterns; more usually makes a skill worse. If you're reaching for five or more, justify it or cut. - -5. **Surface what you did.** After drafting, list the patterns you applied (one line each: *pattern — why*) and any plausible ones you skipped. This keeps the choices auditable and lets the author override. - -6. **Let them drive if they want.** If the author would rather choose — or says "let me pick" — show the relevant candidates and apply only what they select. - -## Decision policy (apply vs. ask) - -- **Apply by default, no need to ask:** Scope guardrails and Clarification gate for anything that acts or takes ambiguous input; Trusted sources for anything fact-dependent; Schema-locked output for anything another system parses. -- **Propose, then confirm:** patterns that change the interaction model or add real cost — Adversarial push back, Premortem, multi-pass self-review, Council-style debate. -- **Always confirm before:** removing a pattern the user explicitly asked for, or applying more than four. - -## Note - -This skill is itself a composition of its own catalog: it grounds in an authoritative source (Trusted sources), generates bounded candidates (Bounded option generation), decides what to apply vs. surface (Codified judgment), exposes its choices for override (Clarification gate), and loads detail only when needed (Progressive disclosure). - -`references/patterns.md` is a generated snapshot of the live catalog (`skillpatterns.ai/llms.txt`); regenerate it when the catalog changes. diff --git a/skills/skill-patterns/references/choosing-patterns.md b/skills/skill-patterns/references/choosing-patterns.md deleted file mode 100644 index c43d830..0000000 --- a/skills/skill-patterns/references/choosing-patterns.md +++ /dev/null @@ -1,27 +0,0 @@ -# Choosing patterns by intent - -Map the skill's behavior to candidate patterns. Most skills need **2–4**; don't over-apply. Full catalog with example prompts is in `patterns.md`. - -| If the skill… | Reach for… | -|---|---| -| relies on facts that must be correct | Trusted sources, Confidence calibration | -| pulls from multiple sources or feeds | Graceful degradation, Signal vs. noise | -| often gets vague or ambiguous briefs | Clarification gate, Question sharpening | -| makes a recommendation or decision | Bounded option generation, Decision capture, Stakes-scaled rigor | -| reviews or evaluates work | Encoded reasoning, Gap-to-target scoring, Self-critique | -| must catch errors before it ships | Prove it works, Premortem, Failure mode preloading, Disconfirmation | -| takes an irreversible or high-stakes action | Human in the loop, Scope guardrails | -| runs autonomously or for a long time | Codified judgment, Circuit breaker, Long-term memory | -| produces a deliverable in a set format | Artifact creation, Format projection | -| feeds another system (machine-readable) | Schema-locked output | -| encodes one tool or library's conventions | Convention wrapper | -| should match a particular voice or style | Exemplars over instruction | -| is a multi-step or multi-skill workflow | Decomposition, Workflows as superset, Externalized working state, Progressive disclosure | -| tends to produce people-pleasing answers | Anti-sycophancy | -| benefits from a specific expert stance | Role priming | - -## Selection notes - -- **Default-apply** (no need to ask): Scope guardrails + Clarification gate when the skill acts or takes ambiguous input; Trusted sources when it's fact-dependent; Schema-locked output when its output is machine-read. -- **Propose then confirm** (adds cost or changes the interaction): Adversarial push back, Premortem, Council-style debate, multi-pass review. -- **Composition patterns** (Decomposition, Workflows as superset, Externalized working state, Progressive disclosure, Long-term memory) apply to multi-step or cross-session skills — not simple single-shot ones. diff --git a/skills/skill-patterns/references/patterns.md b/skills/skill-patterns/references/patterns.md deleted file mode 100644 index 50a60e3..0000000 --- a/skills/skill-patterns/references/patterns.md +++ /dev/null @@ -1,227 +0,0 @@ - - -# Skill Patterns - -> Reusable, composable techniques for shaping how an AI agent behaves — 34 patterns across 6 categories. When creating or improving a Skill, apply the patterns whose purpose matches the task; each entry includes an example prompt you can adapt. Most skills use 2–4 patterns — don't over-apply. Site: https://skillpatterns.ai/ - -## Grounding & accuracy -Keep the agent tethered to truth and honest about what it knows. - -### Confidence calibration -Requires the agent to mark which parts of its output it's confident about and which are guesses. -- What it adds: Tags claims by certainty so high-risk pieces are visible at a glance; Distinguishes what's verified against sources from what's inferred or assumed; Tells you where to spend your verification time and where you can move fast. -- Example prompt: As you produce [output], mark each substantive claim with a confidence level: high (verified against a source or directly observable), medium (inferred from pattern or adjacent evidence), low (filling a gap, best guess, please verify). For low-confidence claims, briefly note what would raise the confidence — a source to check, a test to run, a person to ask. Don't smooth out uncertainty in the final wording; if it's a guess, it should read like one. -- URL: https://skillpatterns.ai/patterns/confidence-calibration/ - -### Convention wrapper -Packages a specific tool, library, or domain's conventions as on-demand knowledge the Skill applies only when that area is in play. -- What it adds: Encodes the right way to use a specific tool or library, not generic advice; Activates only when the task actually touches that area; Keeps the detailed reference out of context until it's needed. -- Example prompt: When the task involves [tool / library / domain], follow these conventions: [rules, or point to a reference doc]. Use this specific guidance rather than generic best practices, and only pull in the detailed reference when the task actually touches [area]. If a convention here conflicts with your default approach, this guidance wins. If the task is outside [area], ignore this. -- URL: https://skillpatterns.ai/patterns/convention-wrapper/ - -### Exemplars over instruction -Anchors the Skill's output in concrete examples of "good" rather than describing it in rules. -- What it adds: Matches the shape, voice, and structure of provided examples; Surfaces which exemplar it drew from when the choice is ambiguous; Asks for a new exemplar when the work falls outside the set. -- Example prompt: Here are exemplars of [strong outputs / preferred voice / target format]: [paste 2-4 examples]. Match the shape and voice of these rather than following rules I might write down. When the task falls outside what the exemplars cover, say so and ask for a new exemplar instead of guessing. Cite which exemplar most influenced the output. -- URL: https://skillpatterns.ai/patterns/exemplars-over-instruction/ - -### Graceful degradation -When an input or source is unavailable, the Skill produces the best partial result and flags what was missing, instead of blocking or guessing. -- What it adds: Continues with available inputs when a source fails; Names which sources were unavailable and what they'd have affected; Marks the result as partial rather than presenting it as complete. -- Example prompt: If a required input or source is unavailable or errors out, don't block or silently fill the gap. Proceed with what you have, clearly mark the result as partial, and list which sources were missing and what they affected. Only hard-stop if a missing input makes the whole task meaningless — and say which one. -- URL: https://skillpatterns.ai/patterns/graceful-degradation/ - -### Signal vs. noise -Forces an explicit list of which sources count as signal versus noise before analysis — including the noise you're most tempted to lean on anyway. -- What it adds: Names the signal sources to weight and the noise to exclude up front; Calls out the tempting-but-noisy source you'd otherwise over-rely on; Lets you instruct the agent to actively discount that source. -- Example prompt: Before analyzing [topic], list your sources in two columns: signal (what should drive the conclusion) and noise (what to discount). Then name the one noisy source you're most likely to lean on anyway — vanity metrics, a loud stakeholder, recency — and treat it as noise on purpose. Weight the analysis toward signal, and flag any place noise is creeping back in. -- URL: https://skillpatterns.ai/patterns/signal-noise-pre-commitment/ - -### Trusted sources -Anchors the agent in specific authoritative references so it stops improvising from training data. -- What it adds: Cites which source supports each claim; Defers to specified sources when they conflict with general knowledge; Flags gaps instead of filling them silently. -- Example prompt: Ground this Skill in the following authoritative sources: [URLs / paths / docs]. When the task touches this area, consult these first. If your training contradicts these sources, the sources win. Cite which source each claim comes from. If a source is missing or ambiguous, flag the gap rather than filling it from prior knowledge. -- URL: https://skillpatterns.ai/patterns/trusted-sources/ - -## Decision-making -Structure how choices get made and recorded. - -### Bounded option generation -Forces a fixed number of distinct alternatives with trade-offs before converging on a recommendation. -- What it adds: Generates options that are genuinely different, not variations; Names what each option optimizes for and what it gives up; Recommends one, addressing why not the others. -- Example prompt: Before recommending [a decision / an approach], generate [3] meaningfully different options. Each must take a different bet — not variations of the same shape. For each, name what it's optimizing for and what it's giving up. Then recommend one, including why the other options were rejected rather than only why this one wins. -- URL: https://skillpatterns.ai/patterns/bounded-option-generation/ - -### Decision capture -Surfaces the assumptions, alternatives considered, and reasoning trail alongside the output so the decision is auditable. -- What it adds: Records what was assumed and what was uncertain; Lists alternatives considered and why they were rejected; Writes the reasoning trail for a reader who wasn't in the room. -- Example prompt: Alongside [the output / the recommendation], capture: the assumptions you made, the alternatives you considered, the reasoning that led to this choice, and the conditions under which you'd revisit it. Write it for a reader who wasn't in the room. Keep it short — enough that someone three months from now can tell whether the decision still holds. -- URL: https://skillpatterns.ai/patterns/decision-capture/ - -### Question sharpening -Challenges and sharpens the question itself before answering — naming the premise and pushing past the generic framing. -- What it adds: Surfaces the assumptions baked into the question as asked; Voices the consensus, average answer as a foil to push past it; Steers toward the sharper question without drafting your framing for you. -- Example prompt: Before answering [question], interrogate the question itself. Name the premise it assumes. Say plainly what the generic, consensus answer would be — then treat that as the floor to beat, not the answer. Ask me the one or two questions that would sharpen this into the version only I would ask. Don't write my framing for me; supplying it would just anchor us to the average. -- URL: https://skillpatterns.ai/patterns/question-sharpening/ - -### Stakes-scaled rigor -Tunes how much verification effort to spend to the stakes — a glance for low-risk reversible work, a full interrogation for high-impact irreversible calls. -- What it adds: Judges reversibility and impact before deciding how hard to check; Spends minimal effort on cheap, reversible steps; Reserves deep verification for high-stakes, hard-to-undo decisions. -- Example prompt: Before verifying [output / decision], size the stakes: how reversible is it, and how big is the blast radius if it's wrong? Match your rigor to that — a quick sanity check for low-risk, easily-undone work; a thorough interrogation for high-impact or irreversible calls. Say which level you chose and why, so I can push for more if I disagree. -- URL: https://skillpatterns.ai/patterns/stakes-scaled-rigor/ - -## Output shaping -Control the form and structure of what comes out. - -### Artifact creation -Directs the Skill to produce a concrete, standalone deliverable rather than a conversational response. -- What it adds: Returns a finished artifact (doc, deck outline, spec, mockup, dataset) you can lift out and use; Matches a defined structure or template so the output is predictable; Separates the artifact from the surrounding chatter — you know what to keep. -- Example prompt: Produce a standalone [artifact type: brief, spec, one-pager, dashboard outline, draft P2 post] rather than answering conversationally. Follow this structure: [sections / template / required fields]. Return the artifact as a self-contained block I can copy out. Keep commentary about the artifact separate from the artifact itself — if you need to flag assumptions or open questions, put them after, not inside. -- URL: https://skillpatterns.ai/patterns/artifact-creation/ - -### Format projection -Renders one canonical artifact into multiple downstream forms while preserving the underlying content. -- What it adds: Produces the source artifact once, then derives variants from it; Each variant matches its channel's conventions (length, tone, format); Surfaces what was cut or compressed in each derivation. -- Example prompt: Produce the canonical [artifact: decision doc, spec, research summary] first. Then derive these variants from it: [list: P2 post, Slack summary, exec brief, email update]. Each variant should match the conventions of its channel. Don't re-reason — derive. Note what was cut or compressed in each variant so I can spot if something important got lost. -- URL: https://skillpatterns.ai/patterns/format-projection/ - -### Schema-locked output -Forces output into a strict, validated structure and repairs or rejects anything that doesn't conform. -- What it adds: Emits output that matches a defined schema or field set exactly; Validates against the schema before returning, and repairs what doesn't fit; Fails loudly when the content can't be made to conform, instead of bending the format. -- Example prompt: Return [output] strictly as [schema / field set / JSON shape]: [fields and their types]. Include every required field, use exactly these names, and add nothing outside the schema. Before returning, validate against it — if something doesn't conform, fix it. If the content genuinely can't fit the schema, say so explicitly rather than bending the format or inventing fields. -- URL: https://skillpatterns.ai/patterns/schema-locked-output/ - -## Critique & stress-testing -Find weaknesses before the work ships. - -### Adversarial push back -Pits a challenger persona or parallel agent against the work to expose weaknesses before it ships. -- What it adds: Argues the strongest case against the proposal, with reasoning; Surfaces assumptions that wouldn't survive scrutiny; Forces defense of choices instead of quiet acceptance. -- Example prompt: Before finalizing [output], take the role of [adversary: skeptical reviewer, hostile architect, opposing counsel, competitor's CTO]. Argue the strongest case against the proposal. Identify the assumptions most likely to fail, the evidence that's missing, and the decisions that would look wrong in hindsight. Return the pushback and the original work side by side. -- URL: https://skillpatterns.ai/patterns/adversarial-push-back/ - -### Disconfirmation -Has the agent actively seek evidence that would disprove its current hypothesis, and state what would change its mind. -- What it adds: Looks for the evidence that would falsify the current belief, not just confirm it; States explicitly what observation would change the conclusion; Treats a belief with no disconfirming test as an assumption, not a finding. -- Example prompt: For [hypothesis / conclusion], don't just gather support for it — actively look for the evidence that would prove it wrong. State, in one line, what observation or result would change your mind. If nothing could, say so and flag it as an assumption rather than a finding. Report the disconfirming checks you ran alongside the conclusion. -- URL: https://skillpatterns.ai/patterns/disconfirmation/ - -### Encoded reasoning -Bakes review rubrics, validation steps, and quality checks into how the Skill operates. -- What it adds: Runs outputs against a defined rubric before returning them; Surfaces which criteria passed, failed, or are uncertain; Catches predictable failure modes the team has seen before. -- Example prompt: Before returning output, check the work against these criteria: [rubric items]. Report which criteria passed, failed, or are uncertain. Don't return work that fails [hard criteria] — revise and retry. Surface the rubric results alongside the output so I can see the reasoning. -- URL: https://skillpatterns.ai/patterns/encoded-reasoning/ - -### Failure mode preloading -Names the specific ways this kind of work tends to go wrong, so the agent watches for them. -- What it adds: Lists the known failure modes for this kind of task up front; Watches for each one while working, not only at the end; Flags when the work starts drifting toward a named failure mode. -- Example prompt: Before starting [task], name the specific ways this kind of work usually goes wrong — [known failure modes, or ask me for them]. Keep that list in view as you work and check against it as you go, not only at the end. If the work starts drifting toward one of these failure modes, stop and flag it rather than pushing through. In the result, note which failure modes you actively guarded against. -- URL: https://skillpatterns.ai/patterns/failure-mode-preloading/ - -### Gap-to-target scoring -Scores each dimension on a 0–10 scale, describes concretely what a 10 would look like, closes the gap, then re-scores to show the movement. -- What it adds: Rates each dimension numerically instead of a vague pass/fail; Spells out what a perfect 10 looks like for this specific work; Re-scores after improvements so the gain is visible. -- Example prompt: Evaluate [work] by scoring each of these dimensions 0–10: [dimensions]. For any score below 10, describe concretely what a 10 would look like for this specific case, then do the work to close the gap. Re-score afterward and show the before → after for each dimension. Keep the final verdict consistent with the scores. -- URL: https://skillpatterns.ai/patterns/gap-to-target-scoring/ - -### Premortem -Skill imagines the work has already failed and reasons backward to why. -- What it adds: Generates the most plausible failure stories before the work ships; Surfaces risks that wouldn't appear in a forward-looking review; Names which current assumptions, if wrong, cause the failure. -- Example prompt: Before finalizing [the plan / the decision / the proposal], run a premortem. Imagine it's [6 months / a year / one quarter] from now and this work has clearly failed. Generate the 3 most plausible failure stories — what went wrong, in what order, and why it wasn't caught in time. For each, name the assumption in the current plan that, if wrong, made the failure inevitable. Return the failure stories alongside the original work, with the riskiest assumptions called out. -- URL: https://skillpatterns.ai/patterns/premortem/ - -### Prove it works -Before claiming the work is done, the Skill proves it actually happened — running it, checking output, showing evidence — instead of asserting completion. -- What it adds: Runs the verification before saying 'done', not after; Shows the evidence (output, test result, screenshot) behind any success claim; Treats 'this looks finished' as a prompt to test, not to stop. -- Example prompt: Before you claim [task] is complete, actually verify it: run it, check the output, and show me the evidence. Don't say "done", "fixed", or "working" without the result that proves it. If you can't verify a claim, mark it unverified rather than asserting it. Treat "this looks finished" as a signal to test, not to stop. -- URL: https://skillpatterns.ai/patterns/verification-before-completion/ - -### Self-critique -Has the agent review its own output against criteria, identify weaknesses, and revise before returning. -- What it adds: Produces a first draft, then critiques it against the brief; Names the weakest reasoning and the most fragile assumption; Returns the revised output with a note on what changed and why. -- Example prompt: After producing [output], step back and critique your own work against [criteria: the original brief, the rubric, what a strong reviewer would notice]. Identify the weakest reasoning, the most fragile assumption, and the part most likely to be wrong. Revise. Return the revised output along with a brief note on what changed and why. -- URL: https://skillpatterns.ai/patterns/self-critique/ - -### Self-tuning -After a run, the Skill flags its own ambiguous or missing instructions and proposes concrete edits to itself. -- What it adds: Notices where its own instructions were unclear, incomplete, or forced a workaround; Proposes a specific edit — quotes the line and gives the replacement — not a vague 'could be better'; Distinguishes a clean run from one that surfaced an improvement worth making. -- Example prompt: After completing [task], reflect on the instructions you just followed. If anything was ambiguous, missing, or forced a workaround, propose a specific edit to this Skill — quote the line and give the replacement. If the run was clean, say so and suggest nothing. Don't edit the skill yourself; surface the proposal for review. -- URL: https://skillpatterns.ai/patterns/self-tuning/ - -## Control -Govern how the agent behaves within a task — when it pauses, asks, stops, and the stance it takes. - -### Anti-sycophancy -Bans hedging and hollow agreement — the agent commits to a position, names the weakest point plainly, and pushes past the first polished answer. -- What it adds: Cuts filler agreement ('great question', 'that could work'); Commits to a recommendation and says what would change it; Names the weakest part of the work plainly instead of smoothing it over. -- Example prompt: Don't hedge or flatter. Skip "great question", "that's a good point", and "that could work". Take a clear position on [topic] and state what evidence would change it. If part of this is weak, say which part and why — plainly. If my idea has a real problem, tell me directly rather than softening it. Push past your first answer to a sharper one before you settle. -- URL: https://skillpatterns.ai/patterns/anti-sycophancy/ - -### Circuit breaker -Tracks an accumulating 'am I thrashing?' signal during a loop and forces a stop-and-ask before the agent flails. -- What it adds: Counts warning signs — reverts, edits to unrelated files, repeated failed attempts; Trips a hard stop after a set budget instead of grinding on; Surfaces what it tried and why it's stuck, rather than continuing silently. -- Example prompt: While working [task] in a loop, watch for signs you're thrashing: reverting your own changes, touching files unrelated to the goal, or the same fix failing more than [N] times. Keep a running count. When you hit [the budget — e.g., 3 failed attempts or 5 unrelated files], stop and surface what you've tried, what's still failing, and your best guess at why — then ask me before continuing. Don't grind past the limit. -- URL: https://skillpatterns.ai/patterns/circuit-breaker/ - -### Clarification gate -Makes the agent ask clarifying questions before producing output when the brief is ambiguous. -- What it adds: Detects ambiguity or missing constraints before starting work; Asks only the questions whose answers would change the output; Holds off on producing until the brief is clear enough to commit to. -- Example prompt: Before producing [output], check whether the brief is clear enough to commit to. If anything ambiguous would change the result — scope, audience, constraints, definition of done — ask me those questions first, as one short batch, and wait. Only ask what you genuinely can't proceed without; don't ask things the brief already answers. If it's already clear, say so and proceed without stalling. -- URL: https://skillpatterns.ai/patterns/clarification-gate/ - -### Codified judgment -Encodes when the agent should decide on its own versus pause — so routine choices auto-resolve and only genuinely high-stakes calls escalate. -- What it adds: Defines decision principles the agent applies without asking; Separates 'always stop for this' from 'never stop for this'; Logs the auto-decisions it made so they can be audited later. -- Example prompt: As you work, don't ask me about every fork. Decide on your own using these principles: [principles]. Always stop and ask for: [high-stakes, irreversible, or taste-defining choices]. Never stop for: [reversible, mechanical, low-stakes choices] — just decide and note it. Keep a short running log of the decisions you made on your own and why, so I can review them afterward. -- URL: https://skillpatterns.ai/patterns/codified-judgment/ - -### Human in the loop -Inserts explicit checkpoints where the agent pauses for discernment before proceeding. -- What it adds: Stops before destructive, irreversible, or high-stakes steps; Surfaces what it's about to do and waits for confirmation; Distinguishes routine steps (proceed) from judgment calls (pause). -- Example prompt: Before [specific actions: deploying, sending, deleting, committing, finalizing], pause and summarize what you're about to do and why. Wait for my confirmation, redirect, or override before proceeding. Routine steps can run without checkpoints; judgment calls always pause. [When presenting me with options, allow me to keep the default, give me two more, and let me enter my own.] -- URL: https://skillpatterns.ai/patterns/human-in-the-loop/ - -### Role priming -Puts the agent in a specific stance for the duration of the Skill so its reasoning carries that perspective. -- What it adds: Approaches the work from the named role's priorities and constraints; Uses the vocabulary and reference points of that role; Stays in role across follow-ups within the same task. -- Example prompt: Approach this work as [role: staff engineer reviewing a PR, finance partner reviewing a forecast, support lead reviewing a flow]. Use the priorities, vocabulary, and constraints that role brings. Stay in role across follow-up questions within this task. If you'd break role to be more helpful, say so and ask before switching. -- URL: https://skillpatterns.ai/patterns/role-priming/ - -### Scope guardrails -Defines what the Skill should not do and declines or escalates out-of-scope or unsafe requests instead of attempting them. -- What it adds: States the boundaries of what's in and out of scope up front; Declines or flags requests that fall outside them, with a reason; Routes genuinely out-of-scope or risky asks to a human instead of improvising. -- Example prompt: Operate within these boundaries for [task]: in scope — [what it should do]; out of scope — [what it must not do]. If a request falls outside the in-scope list, don't attempt it — say it's out of scope, explain why in a line, and suggest where it should go instead. If something looks unsafe or irreversible beyond your remit, stop and escalate to me rather than improvising. -- URL: https://skillpatterns.ai/patterns/scope-guardrails/ - -## Composition -Structure work across multiple steps and skills — sequencing, shared state, and staged context. - -### Decomposition -Breaks a complex task into smaller, well-scoped sub-tasks and tackles them one at a time. -- What it adds: Splits the problem into parts before attempting any of it; Defines each sub-task's input and output so the pieces fit back together; Surfaces the breakdown so you can correct the plan before work starts. -- Example prompt: Before working on [task], break it into a short list of smaller, well-scoped sub-tasks. For each, note what it needs as input and what it should produce. Show me the breakdown and let me adjust it before you start. Then work through the sub-tasks one at a time, keeping each self-contained, and assemble the results at the end. -- URL: https://skillpatterns.ai/patterns/decomposition/ - -### Externalized working state -Keeps a live, structured state file — a running ledger of what's been checked or decided — that survives across steps and skills instead of relying on chat memory. -- What it adds: Writes progress and findings to a file, not just the conversation; Tracks what's been ruled out, not only what's confirmed; Lets separate steps or skills coordinate through a shared, structured record. -- Example prompt: For [multi-step work], maintain a structured state file at [path] rather than holding everything in this conversation. After each step, update it: what you checked, what you confirmed, what you ruled out, and what's still open. Read it back at the start of each step. Write it so a fresh session — or a different skill — could pick up exactly where this left off. -- URL: https://skillpatterns.ai/patterns/externalized-working-state/ - -### Long-term memory -Persists learnings, preferences, and decisions across sessions and recalls them next time, instead of starting cold. -- What it adds: Records durable facts, preferences, and decisions to a store that outlives the session; Recalls the relevant ones at the start of related work; Updates or retires memories when they're superseded, rather than hoarding. -- Example prompt: Keep a durable memory across sessions for [domain]. When something is worth remembering — a preference, a decision and its rationale, a recurring fact — write it to [memory store / file]. At the start of related work, recall the relevant entries and apply them instead of asking again. When a memory is contradicted or out of date, update or remove it rather than letting it pile up. Tell me what you stored or recalled. -- URL: https://skillpatterns.ai/patterns/long-term-memory/ - -### Progressive disclosure -Loads only the context needed for the current sub-task, expanding as the work deepens. -- What it adds: Starts with the minimum context the current step requires; Pulls in more detail only when the work actually reaches it; Keeps unrelated material out of the way until it's relevant. -- Example prompt: Work through [task] in stages, loading only the context each stage needs. Start with the high-level [overview / index / table of contents]; pull in the detailed [files / sections / data] only when a step actually requires them. Don't front-load everything. When you move to a new sub-task, say what additional context you're bringing in and why, so the scope stays visible. -- URL: https://skillpatterns.ai/patterns/progressive-disclosure/ - -### Workflows as superset -Composes this Skill with others into a sequenced flow. -- What it adds: Triggers other Skills in a defined order; Passes outputs from one stage as inputs to the next; Surfaces workflow state so you can see where you are in the chain. -- Example prompt: Run this as a workflow: [Skill 1] → [Skill 2] → [Skill 3]. Pass the output of each stage as input to the next. After each stage, summarize what was produced and confirm before moving on. If a stage fails its checks, stop and surface the issue rather than continuing. -- URL: https://skillpatterns.ai/patterns/workflows-as-superset/ From 68f0a05d87330569fc76bc556da5f23f13492ab7 Mon Sep 17 00:00:00 2001 From: Matthew Batchelder Date: Sat, 23 May 2026 22:13:52 -0400 Subject: [PATCH 02/18] feat: Self-tuning stays silent when no tuning is needed --- _patterns/self-tuning.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/_patterns/self-tuning.md b/_patterns/self-tuning.md index d46ebf6..5138e05 100644 --- a/_patterns/self-tuning.md +++ b/_patterns/self-tuning.md @@ -3,11 +3,11 @@ title: "Self-tuning" slug: self-tuning icon: "fa-solid fa-arrows-rotate" category: critique -summary: "After a run, the Skill flags its own ambiguous or missing instructions and proposes concrete edits to itself." +summary: "After a run, the Skill proposes concrete edits to its own instructions when they were unclear or incomplete — and stays silent when nothing needs changing." adds: - "Notices where its own instructions were unclear, incomplete, or forced a workaround" - "Proposes a specific edit — quotes the line and gives the replacement — not a vague 'could be better'" - - "Distinguishes a clean run from one that surfaced an improvement worth making" + - "Stays silent on a clean run; speaks up only when there's a real improvement to make" prompt: | - After completing [task], reflect on the instructions you just followed. If anything was ambiguous, missing, or forced a workaround, propose a specific edit to this Skill — quote the line and give the replacement. If the run was clean, say so and suggest nothing. Don't edit the skill yourself; surface the proposal for review. + After completing [task], reflect on the instructions you just followed. Only speak up if something was ambiguous, missing, or forced a workaround — and then propose a specific edit to this Skill: quote the line and give the replacement. If the run was clean and nothing needs changing, say nothing at all about tuning — don't announce that it went fine. Don't edit the skill yourself; surface the proposal for review. --- From 898ddea975da90a3899e40e634f9d4bb8234aed0 Mon Sep 17 00:00:00 2001 From: Matthew Batchelder Date: Sat, 23 May 2026 22:18:24 -0400 Subject: [PATCH 03/18] docs: add AGENTS.md + CLAUDE.md symlink (excluded from site build) --- AGENTS.md | 38 ++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + _config.yml | 2 ++ 3 files changed, 41 insertions(+) create mode 100644 AGENTS.md create mode 120000 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..4f6a794 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,38 @@ +# AGENTS.md + +Guidance for AI agents (and humans) working in this repository. + +## Two branches, two jobs + +- **`main`** (default) — the installable **plugin** for Claude / Codex / Gemini. Holds the `.claude-plugin/` manifests and the `skills/skill-patterns/` skill. +- **`gh-pages`** — the **website** that publishes [skillpatterns.ai](https://skillpatterns.ai) (a Jekyll site). It holds the **canonical pattern catalog** in `_patterns/*.md` and generates `/llms.txt` and `/patterns.json` on build. + +## The catalog lives on gh-pages; the plugin carries a snapshot + +The source of truth for the patterns is `_patterns/*.md` on **gh-pages**. The plugin on **main** ships a *generated snapshot* at `skills/skill-patterns/references/patterns.md` — never hand-edit it. + +## ⚠️ On ANY catalog change, update BOTH branches + +When you add, edit, rename, or remove a pattern (or change categories), do both: + +1. **`gh-pages`** — edit the source in `_patterns/` (and `_data/categories.yml` for category changes), then rebuild and verify: + ``` + bundle exec jekyll build + ``` +2. **`main`** — regenerate the plugin's snapshot from the rebuilt catalog and commit: + ``` + curl -s https://skillpatterns.ai/llms.txt > skills/skill-patterns/references/patterns.md + ``` + (Before the site is live, copy the freshly built `_site/llms.txt` instead.) + +Commit on **both** branches. A change that lands on only one branch leaves the site and the plugin out of sync. + +## Conventions + +- Patterns sort **alphabetically by title** within their category; the `order` frontmatter field is unused. +- `/llms.txt` and `/patterns.json` regenerate from `_patterns/` automatically on build — don't edit them by hand. +- Pattern frontmatter: `title`, `slug`, `icon` (FontAwesome Free), `category` (a key in `_data/categories.yml`), `summary`, `adds` (list), `prompt` (block scalar). + +## Deploy + +GitHub Pages builds from the **`gh-pages`** branch (`CNAME` → skillpatterns.ai lives there). `main` is the default branch and the plugin source. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/_config.yml b/_config.yml index a6e4ae3..93792cb 100644 --- a/_config.yml +++ b/_config.yml @@ -27,4 +27,6 @@ exclude: - .superpowers/ - vendor/ - skills/ + - AGENTS.md + - CLAUDE.md - "*.pdf" From ebb8dbe9eee053540a483a75be3b7f21bcb3174a Mon Sep 17 00:00:00 2001 From: Matthew Batchelder Date: Sat, 23 May 2026 22:31:15 -0400 Subject: [PATCH 04/18] catalog: merge Self-critique into Encoded reasoning MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fold Self-critique's distinct behaviors (draft→critique→revise, naming the weakest reasoning and most fragile assumption, the note on what changed) into Encoded reasoning, then delete Self-critique. The two were the same self-review move; "Encoded reasoning" survives as the more load-bearing name — predefined rubric plus a hard pass/fail gate. Critique category 9→8, total 34→33. Counts (home eyebrow, llms.txt, patterns.json) are Liquid-generated and update on build. Co-Authored-By: Claude Opus 4.7 (1M context) --- _patterns/encoded-reasoning.md | 10 +++++----- _patterns/self-critique.md | 14 -------------- 2 files changed, 5 insertions(+), 19 deletions(-) delete mode 100644 _patterns/self-critique.md diff --git a/_patterns/encoded-reasoning.md b/_patterns/encoded-reasoning.md index d83b283..c80a9bf 100644 --- a/_patterns/encoded-reasoning.md +++ b/_patterns/encoded-reasoning.md @@ -4,11 +4,11 @@ slug: encoded-reasoning icon: "fa-solid fa-list-check" category: critique order: 1 -summary: "Bakes review rubrics, validation steps, and quality checks into how the Skill operates." +summary: "Bakes the review rubric and quality gates into the Skill — it drafts, checks its own work against the criteria, and revises before returning." adds: - - "Runs outputs against a defined rubric before returning them" - - "Surfaces which criteria passed, failed, or are uncertain" - - "Catches predictable failure modes the team has seen before" + - "Runs output against a defined rubric — or, absent one, the brief and what a strong reviewer would notice" + - "Reports which criteria passed, failed, or are uncertain, and names the weakest reasoning and most fragile assumption" + - "Holds back work that fails a hard criterion — revises, retries, and returns a note on what changed" prompt: | - Before returning output, check the work against these criteria: [rubric items]. Report which criteria passed, failed, or are uncertain. Don't return work that fails [hard criteria] — revise and retry. Surface the rubric results alongside the output so I can see the reasoning. + Before returning [output], check your own work against these criteria: [rubric items — or, absent a rubric, the original brief and what a strong reviewer would notice]. Report which criteria passed, failed, or are uncertain, and name the weakest reasoning and the most fragile assumption. Don't return work that fails a hard criterion — revise and retry. Return the revised output with a brief note on what changed and why. --- diff --git a/_patterns/self-critique.md b/_patterns/self-critique.md deleted file mode 100644 index 234a01d..0000000 --- a/_patterns/self-critique.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "Self-critique" -slug: self-critique -icon: "fa-solid fa-pen-to-square" -category: critique -order: 2 -summary: "Has the agent review its own output against criteria, identify weaknesses, and revise before returning." -adds: - - "Produces a first draft, then critiques it against the brief" - - "Names the weakest reasoning and the most fragile assumption" - - "Returns the revised output with a note on what changed and why" -prompt: | - After producing [output], step back and critique your own work against [criteria: the original brief, the rubric, what a strong reviewer would notice]. Identify the weakest reasoning, the most fragile assumption, and the part most likely to be wrong. Revise. Return the revised output along with a brief note on what changed and why. ---- From 803d2125e31bbb7ca04cb7852b0bfc16d2e6c797 Mon Sep 17 00:00:00 2001 From: Matthew Batchelder Date: Sat, 23 May 2026 22:37:59 -0400 Subject: [PATCH 05/18] =?UTF-8?q?catalog:=20rename=20Workflows=20as=20supe?= =?UTF-8?q?rset=20=E2=86=92=20Skill=20chaining?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Plain technique name over the thesis-y "as superset" framing: the pattern chains other skills in sequence, passing each stage's output to the next. Slug changes too (workflows-as-superset → skill-chaining), so the old /patterns/workflows-as-superset/ URL now 404s. Icon diagram-project → link to match the linear-chain metaphor. Content unchanged. Co-Authored-By: Claude Opus 4.7 (1M context) --- _patterns/{workflows-as-superset.md => skill-chaining.md} | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) rename _patterns/{workflows-as-superset.md => skill-chaining.md} (85%) diff --git a/_patterns/workflows-as-superset.md b/_patterns/skill-chaining.md similarity index 85% rename from _patterns/workflows-as-superset.md rename to _patterns/skill-chaining.md index 10af5f0..0f23b16 100644 --- a/_patterns/workflows-as-superset.md +++ b/_patterns/skill-chaining.md @@ -1,7 +1,7 @@ --- -title: "Workflows as superset" -slug: workflows-as-superset -icon: "fa-solid fa-diagram-project" +title: "Skill chaining" +slug: skill-chaining +icon: "fa-solid fa-link" category: composition order: 3 summary: "Composes this Skill with others into a sequenced flow." From 20469c181b5bde9ed2f71b06282d85bd5573c834 Mon Sep 17 00:00:00 2001 From: Matthew Batchelder Date: Sat, 23 May 2026 22:48:52 -0400 Subject: [PATCH 06/18] catalog: sharpen four pattern names MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Prove it works: slug verification-before-completion → prove-it-works (title kept; URL changes) - Adversarial push back → Adversarial pushback (title only; slug unchanged) - Convention wrapper → Scoped conventions (slug → scoped-conventions) - Codified judgment → Decision delegation (slug → decision-delegation) Old /patterns/{verification-before-completion,convention-wrapper,codified-judgment}/ URLs now 404. using.md reference updated. Pattern bodies unchanged. Co-Authored-By: Claude Opus 4.7 (1M context) --- _patterns/adversarial-push-back.md | 2 +- _patterns/{codified-judgment.md => decision-delegation.md} | 4 ++-- .../{verification-before-completion.md => prove-it-works.md} | 2 +- _patterns/{convention-wrapper.md => scoped-conventions.md} | 4 ++-- using.md | 2 +- 5 files changed, 7 insertions(+), 7 deletions(-) rename _patterns/{codified-judgment.md => decision-delegation.md} (93%) rename _patterns/{verification-before-completion.md => prove-it-works.md} (95%) rename _patterns/{convention-wrapper.md => scoped-conventions.md} (93%) diff --git a/_patterns/adversarial-push-back.md b/_patterns/adversarial-push-back.md index c3b1665..7aa9b52 100644 --- a/_patterns/adversarial-push-back.md +++ b/_patterns/adversarial-push-back.md @@ -1,5 +1,5 @@ --- -title: "Adversarial push back" +title: "Adversarial pushback" slug: adversarial-push-back icon: "fa-solid fa-gavel" category: critique diff --git a/_patterns/codified-judgment.md b/_patterns/decision-delegation.md similarity index 93% rename from _patterns/codified-judgment.md rename to _patterns/decision-delegation.md index c9d7611..9774f47 100644 --- a/_patterns/codified-judgment.md +++ b/_patterns/decision-delegation.md @@ -1,6 +1,6 @@ --- -title: "Codified judgment" -slug: codified-judgment +title: "Decision delegation" +slug: decision-delegation icon: "fa-solid fa-scale-balanced" category: control summary: "Encodes when the agent should decide on its own versus pause — so routine choices auto-resolve and only genuinely high-stakes calls escalate." diff --git a/_patterns/verification-before-completion.md b/_patterns/prove-it-works.md similarity index 95% rename from _patterns/verification-before-completion.md rename to _patterns/prove-it-works.md index d054091..96f6a96 100644 --- a/_patterns/verification-before-completion.md +++ b/_patterns/prove-it-works.md @@ -1,6 +1,6 @@ --- title: "Prove it works" -slug: verification-before-completion +slug: prove-it-works icon: "fa-solid fa-circle-check" category: critique summary: "Before claiming the work is done, the Skill proves it actually happened — running it, checking output, showing evidence — instead of asserting completion." diff --git a/_patterns/convention-wrapper.md b/_patterns/scoped-conventions.md similarity index 93% rename from _patterns/convention-wrapper.md rename to _patterns/scoped-conventions.md index 402a0cd..b198634 100644 --- a/_patterns/convention-wrapper.md +++ b/_patterns/scoped-conventions.md @@ -1,6 +1,6 @@ --- -title: "Convention wrapper" -slug: convention-wrapper +title: "Scoped conventions" +slug: scoped-conventions icon: "fa-solid fa-screwdriver-wrench" category: grounding summary: "Packages a specific tool, library, or domain's conventions as on-demand knowledge the Skill applies only when that area is in play." diff --git a/using.md b/using.md index f3caf65..c3ab206 100644 --- a/using.md +++ b/using.md @@ -32,7 +32,7 @@ Not sure which to grab? [Browse the catalog]({{ '/' | relative_url }}) — it's ## Fill in the brackets -The `[brackets]` are slots, not literal text. The Convention wrapper prompt, for instance, starts: +The `[brackets]` are slots, not literal text. The Scoped conventions prompt, for instance, starts: > When the task involves `[tool / library / domain]`, follow these conventions: `[rules, or point to a reference doc]`… From 1fc4df14624fab813376d4abe366994defafa002 Mon Sep 17 00:00:00 2001 From: Matthew Batchelder Date: Sat, 23 May 2026 22:50:48 -0400 Subject: [PATCH 07/18] catalog: change Adversarial pushback slug to adversarial-pushback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit slug adversarial-push-back → adversarial-pushback to match the one-word title. Old /patterns/adversarial-push-back/ URL now 404s. Co-Authored-By: Claude Opus 4.7 (1M context) --- _patterns/{adversarial-push-back.md => adversarial-pushback.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename _patterns/{adversarial-push-back.md => adversarial-pushback.md} (96%) diff --git a/_patterns/adversarial-push-back.md b/_patterns/adversarial-pushback.md similarity index 96% rename from _patterns/adversarial-push-back.md rename to _patterns/adversarial-pushback.md index 7aa9b52..1ba2a76 100644 --- a/_patterns/adversarial-push-back.md +++ b/_patterns/adversarial-pushback.md @@ -1,6 +1,6 @@ --- title: "Adversarial pushback" -slug: adversarial-push-back +slug: adversarial-pushback icon: "fa-solid fa-gavel" category: critique order: 3 From 7388e1e462b7bb5b8489498d66174b5e75109c52 Mon Sep 17 00:00:00 2001 From: Matthew Batchelder Date: Sat, 23 May 2026 23:30:23 -0400 Subject: [PATCH 08/18] site: improve mobile top nav and sidebar MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Shorten nav labels on mobile: "What are these?" → "What?", "How to use" → "Using" (desktop keeps full labels). - Make the pattern sidebar collapsible on mobile via a "Browse patterns" toggle, collapsed by default so content isn't pushed down; expands into a scrollable 60vh region. - Replace the "GitHub" nav text with the FontAwesome GitHub logo on desktop and mobile (aria-label retained for a11y). Co-Authored-By: Claude Opus 4.7 (1M context) --- _includes/header.html | 6 +++--- _includes/sidebar.html | 6 +++++- assets/css/style.css | 18 +++++++++++++++++- assets/js/app.js | 10 ++++++++++ 4 files changed, 35 insertions(+), 5 deletions(-) diff --git a/_includes/header.html b/_includes/header.html index bfa1ca9..84729f1 100644 --- a/_includes/header.html +++ b/_includes/header.html @@ -1,9 +1,9 @@
SkillPatterns

Reusable patterns for composing AI Skills. · MIT License

+ diff --git a/_includes/header.html b/_includes/header.html index 3b54e57..bc2d4d2 100644 --- a/_includes/header.html +++ b/_includes/header.html @@ -7,7 +7,7 @@ PatternsPatterns DocsDocs Install the SkillInstall - + diff --git a/assets/css/style.css b/assets/css/style.css index a63daf5..87a03a0 100644 --- a/assets/css/style.css +++ b/assets/css/style.css @@ -202,6 +202,7 @@ a:hover { text-decoration: underline; } .footer-nav { display: flex; flex-wrap: wrap; justify-content: center; gap: 8px 20px; margin-bottom: 12px; } .footer-nav a { font-weight: 500; } .footer-nav a:hover { color: var(--text); } +.footer-theme { margin: 12px auto 0; } /* Hero */ .mono { font-family: var(--mono); } @@ -297,18 +298,20 @@ a:hover { text-decoration: underline; } /* Sidebar becomes an off-canvas drawer toggled by the header hamburger */ html.has-sidebar .header-link { display: none; } html.has-sidebar .nav-hamburger { display: grid; } + .site-header .theme-toggle { display: none; } .sidebar { - position: fixed; top: var(--header-h); right: 0; left: auto; bottom: 0; z-index: 40; - width: min(330px, 86vw); height: auto; flex: none; flex-basis: auto; + position: fixed; top: var(--header-h); right: 0; left: auto; z-index: 40; + width: min(330px, 86vw); height: calc(100dvh - var(--header-h)); flex: none; padding: 16px 14px 28px; border-left: 1px solid var(--border); border-right: none; border-bottom: none; - background: var(--bg); overflow-y: auto; box-shadow: -16px 0 50px rgba(0,0,0,.3); + background: var(--bg); overflow-y: auto; -webkit-overflow-scrolling: touch; + box-shadow: -16px 0 50px rgba(0,0,0,.3); transform: translateX(100%); visibility: hidden; transition: transform .26s ease, visibility .26s ease; } .sidebar.is-open { transform: translateX(0); visibility: visible; } .sidebar-nav { display: block; } .sidebar-cat:first-child { margin-top: 0; } - body.nav-drawer-open { overflow: hidden; } + html.nav-drawer-open { overflow: hidden; } .content { padding: 24px 20px; } .home { padding: 24px 20px; } diff --git a/assets/js/app.js b/assets/js/app.js index cab81f8..d1fdea0 100644 --- a/assets/js/app.js +++ b/assets/js/app.js @@ -1,15 +1,14 @@ (function () { 'use strict'; - /* Theme toggle */ - var toggle = document.getElementById('theme-toggle'); - if (toggle) { + /* Theme toggle (header + footer share the same behavior) */ + Array.prototype.forEach.call(document.querySelectorAll('.theme-toggle'), function (toggle) { toggle.addEventListener('click', function () { var next = document.documentElement.getAttribute('data-theme') === 'dark' ? 'light' : 'dark'; document.documentElement.setAttribute('data-theme', next); try { localStorage.setItem('theme', next); } catch (e) {} }); - } + }); /* Mobile sidebar drawer (opened by the header hamburger) */ var sidebar = document.getElementById('sidebar'); @@ -21,7 +20,7 @@ if (backdrop) { backdrop.classList.toggle('is-visible', open); } hamburger.setAttribute('aria-expanded', open ? 'true' : 'false'); hamburger.setAttribute('aria-label', open ? 'Close navigation' : 'Open navigation'); - document.body.classList.toggle('nav-drawer-open', open); + document.documentElement.classList.toggle('nav-drawer-open', open); }; hamburger.addEventListener('click', function () { setDrawer(!sidebar.classList.contains('is-open'));