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/DESIGN.md b/DESIGN.md new file mode 100644 index 0000000..f1c3397 --- /dev/null +++ b/DESIGN.md @@ -0,0 +1,119 @@ +# Design System — skillpatterns.ai + +The site's visual language, captured so changes stay consistent. The source of +truth is `assets/css/style.css`; this file explains the intent behind it. + +## Principles + +- **Semantic tokens, never hard-coded color.** Every color is a CSS variable on + `:root` with a `[data-theme="dark"]` override. New components must use tokens + so dark mode works for free. +- **Restraint.** Subtraction default — an element earns its pixels or it's cut. +- **Accessibility is not optional.** Text meets WCAG AA contrast (≥4.5:1); + interactive chrome meets the 44px touch target (AAA 2.5.5) where practical, and + never less than 24px (AA 2.5.8). Keyboard focus is always visible. + +## Color tokens + +Defined in `:root` (light) and overridden under `[data-theme="dark"]`. + +| Token | Light | Dark | Use | +|-------|-------|------|-----| +| `--bg` | `#ffffff` | `#0f1115` | Page background | +| `--bg-elevated` | `#f7f8fa` | `#14161c` | Cards, chips, inputs, hovers | +| `--border` | `#e7e9ee` | `#23262f` | Hairline dividers | +| `--border-strong` | `#dfe2e8` | `#2a2e38` | Input borders, emphasis | +| `--text` | `#0b1020` | `#f1f3f8` | Primary text, headings | +| `--text-muted` | `#4b5263` | `#a9b0be` | Body copy, secondary text | +| `--text-faint` | `#6b7280` | `#8b93a3` | Tertiary labels, captions, footer | +| `--accent` | `#3858E9` | `#6b8aff` | Links, active state, highlights | +| `--accent-contrast` | `#ffffff` | `#0b1020` | Text on an accent fill | + +The `--prompt-*` tokens style the example-prompt card (a warm "code" surface). + +**Contrast rule:** `--text-faint` is the lightest text allowed on body copy and +clears 4.5:1 on both `--bg` and `--bg-elevated`. Do not introduce a lighter gray +for text. Verify any new text/background pair at ≥4.5:1 (≥3:1 for ≥18px bold). + +### Category accents (`--cat`) + +Color is **wayfinding**: each of the six categories owns a hue, set as a `--cat` +variable on `[data-cat=""]` (the home section, sidebar group, jump-nav chip, +and pattern-detail wrapper). Because custom properties inherit, descendants just +reference `var(--cat, var(--accent))` — section titles, sidebar labels, chip text, +card icon tiles, the detail eyebrow/title/bullets, and the active-pattern tint all +pick it up automatically. + +| Category | Light | Dark | +|----------|-------|------| +| `grounding` | `#3858E9` | `#6b8aff` | +| `decision` | `#0B7D6F` | `#3fd6c0` | +| `output` | `#683FE6` | `#a48bff` | +| `critique` | `#C5314C` | `#ff7d94` | +| `control` | `#8F5E12` | `#e0a64a` | +| `composition` | `#23783A` | `#5fc06f` | + +Light hues are tuned to clear **4.5:1 on `--bg-elevated`** (the chip background, the +strictest case); dark hues clear it comfortably. Adding/recoloring a category means +adding a `--cat` pair here and re-verifying contrast. Tints (icon tiles, active +state) are derived with `color-mix(in srgb, var(--cat) N%, …)`, so they track the +hue automatically — never hard-code a tint. + +## Typography + +- **Sans:** system stack (`--sans`). **Mono:** system mono (`--mono`), used for the + hero eyebrow and prompt bodies. +- **Scale (px):** hero `clamp(40,7vw,68)` · page h1 `36` · intro h1 `34` · pattern + title `22` · card/section titles `16` · body `15.5–16` · meta/labels `11–14`. +- **Weight:** 800 for display/brand, 700 for titles, 500–600 for UI, 400 body. +- Uppercase micro-labels use `letter-spacing: .05–.07em` and `--text-faint`/`--accent`. + +## Spacing + +Informal scale; prefer multiples of ~4 (`4, 6, 8, 10, 14, 16, 18, 22, 26`). +Section rhythm leans on `padding-top` + a `--border` top rule. Radii: `--radius` +(10px) for surfaces, `8px` buttons/inputs, `12–16px` cards, `999px` pills. + +## Components + +- **Header** (`.site-header`) — sticky, `--header-h` (57px) tall. Nav links are + 44px tap targets; the GitHub link is a FontAwesome brand glyph with an + `aria-label`. +- **Theme toggle** (`.theme-toggle`) — 40px button; FontAwesome moon/sun swapped + by `[data-theme]` via `::before`. +- **Cards** (`.pcard`) — bordered, `--card-bg`, lift on hover (gated by + `prefers-reduced-motion`). +- **Sidebar** (`.sidebar`) — desktop: sticky index. Mobile (≤820px): collapses + behind a `.sidebar-toggle` disclosure (`aria-expanded`/`aria-controls`), with an + animated reveal and rotating chevron. +- **Category nav** (`.cat-nav`) — sticky, horizontally-scrollable pill chips that + jump to `#cat-` sections on the home page. +- **Prompt card** (`.prompt`) — the warm-toned copyable example partial. + +## Icons + +FontAwesome 6 Free (loaded via CDN, `preconnect`ed). Use `` +or `fa-brands` for brand marks. Don't mix in unicode glyphs or emoji — they render +inconsistently across platforms. + +## Motion + +- Transitions ≤ ~250ms, `ease`/`ease-out`. Every animation has a purpose + (affordance, confirmation, reveal) — no decorative motion. +- **Always gate motion** behind `@media (prefers-reduced-motion: reduce)` — see the + block at the top of `style.css`. + +## Responsive + +- **≤820px:** layout stacks; sidebar becomes the disclosure; nav labels shorten + ("What?", "Using"). This range serves tablets. +- **≤560px:** phone tightening — smaller hero, reduced padding, tighter card gap. + +## Accessibility checklist for new work + +1. Color pairs ≥4.5:1 (text) / ≥3:1 (large bold, non-text). +2. Interactive targets ≥44px (≥24px minimum for dense lists). +3. Visible `:focus-visible` ring (inherited globally — don't remove it). +4. Decorative icons get `aria-hidden="true"`; icon-only controls get `aria-label`. +5. Any motion respects `prefers-reduced-motion`. + diff --git a/_config.yml b/_config.yml index a6e4ae3..3b25f1e 100644 --- a/_config.yml +++ b/_config.yml @@ -3,6 +3,7 @@ description: "A catalog of reusable patterns for composing AI Skills." url: "https://skillpatterns.ai" baseurl: "" repo_url: "https://github.com/borkweb/skill-patterns" +google_analytics: "G-X6BTVP0R5T" collections: patterns: @@ -22,9 +23,13 @@ exclude: - Gemfile - Gemfile.lock - README.md + - DESIGN.md - LICENSE - docs/ - .superpowers/ - vendor/ - skills/ + - AGENTS.md + - CLAUDE.md - "*.pdf" + - "*.sh" diff --git a/_includes/analytics.html b/_includes/analytics.html new file mode 100644 index 0000000..41e7d4d --- /dev/null +++ b/_includes/analytics.html @@ -0,0 +1,11 @@ +{%- if jekyll.environment == "production" and site.google_analytics -%} + + + +{%- endif -%} diff --git a/_includes/footer.html b/_includes/footer.html index 04aa60f..68af832 100644 --- a/_includes/footer.html +++ b/_includes/footer.html @@ -1,4 +1,13 @@ diff --git a/_includes/head.html b/_includes/head.html index f3bfa03..1b06bf1 100644 --- a/_includes/head.html +++ b/_includes/head.html @@ -1,5 +1,6 @@ +{%- include analytics.html -%} {% assign page_title = page.title | default: site.title %} {% assign page_desc = page.summary | default: page.description | default: site.description %} {% if page.title and page.title != site.title %}{{ page_title }} · {{ site.title }}{% else %}{{ site.title }}{% endif %} @@ -11,8 +12,9 @@ - + + + diff --git a/_layouts/doc.html b/_layouts/doc.html new file mode 100644 index 0000000..338b2ec --- /dev/null +++ b/_layouts/doc.html @@ -0,0 +1,9 @@ +--- +layout: default +--- +
+ {%- include sidebar.html -%} +
+ {{ content }} +
+
diff --git a/_layouts/home.html b/_layouts/home.html index 3dbfcd2..02a8759 100644 --- a/_layouts/home.html +++ b/_layouts/home.html @@ -1,28 +1,45 @@ --- layout: default --- +{%- comment -%} Sidebar isn't shown as a column on the home page (hidden on desktop); +it exists only to power the mobile hamburger drawer. {%- endcomment -%} +{%- include sidebar.html -%}
+
-
{{ site.patterns | size }} composable patterns
+
{{ site.patterns | size }} composable patterns
{{ content }} -
- - +
+ Browse the catalog + Install the Skill
+
+
{{ site.patterns | size }}
Patterns
+
{{ site.data.categories | size }}
Categories
+
0
Dependencies
+
{% assign cats = site.data.categories | sort: "order" %} - {% for cat in cats %} -
-

{{ cat.title | escape }}

-

{{ cat.description | escape }}

-
- {% assign pats = site.patterns | where: "category", cat.key | sort_natural: "title" %} - {% for p in pats %}{% include pattern-card.html pattern=p %}{% endfor %} -
-
- {% endfor %} - +
+ {% for cat in cats %} + {% assign pats = site.patterns | where: "category", cat.key | sort_natural: "title" %} + + {% endfor %} +
diff --git a/_layouts/pattern.html b/_layouts/pattern.html index b74c830..ae82904 100644 --- a/_layouts/pattern.html +++ b/_layouts/pattern.html @@ -4,10 +4,10 @@
{%- include sidebar.html -%}
- ← All patterns + ← All patterns {% assign cat = site.data.categories | where: "key", page.category | first %} -
-
{{ cat.title | escape }}
+
+
{{ cat.title | escape }}
{% include pattern.html pattern=page %}
diff --git a/_patterns/adversarial-push-back.md b/_patterns/adversarial-pushback.md similarity index 92% rename from _patterns/adversarial-push-back.md rename to _patterns/adversarial-pushback.md index c3b1665..1ba2a76 100644 --- a/_patterns/adversarial-push-back.md +++ b/_patterns/adversarial-pushback.md @@ -1,6 +1,6 @@ --- -title: "Adversarial push back" -slug: adversarial-push-back +title: "Adversarial pushback" +slug: adversarial-pushback icon: "fa-solid fa-gavel" category: critique order: 3 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/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/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/_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. ---- 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. --- 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." diff --git a/assets/css/style.css b/assets/css/style.css index 927b5b6..87a03a0 100644 --- a/assets/css/style.css +++ b/assets/css/style.css @@ -5,7 +5,7 @@ --border-strong: #dfe2e8; --text: #0b1020; --text-muted: #4b5263; - --text-faint: #8a90a0; + --text-faint: #6b7280; --accent: #3858E9; --accent-contrast: #ffffff; --prompt-bg: #fdf6dd; @@ -35,7 +35,7 @@ --border-strong: #2a2e38; --text: #f1f3f8; --text-muted: #a9b0be; - --text-faint: #6b7280; + --text-faint: #8b93a3; --accent: #6b8aff; --accent-contrast: #0b1020; --prompt-bg: #211d10; @@ -52,12 +52,36 @@ --hero-glow: rgba(91,124,255,.30); --hero-search-shadow: none; } +/* Category accents — color as wayfinding. Each --cat inherits to descendants. + All hues verified ≥4.5:1 (WCAG AA) on their text backgrounds in both themes. */ +[data-cat="grounding"] { --cat: #3858E9; } +[data-cat="decision"] { --cat: #0B7D6F; } +[data-cat="output"] { --cat: #683FE6; } +[data-cat="critique"] { --cat: #C5314C; } +[data-cat="control"] { --cat: #8F5E12; } +[data-cat="composition"] { --cat: #23783A; } +[data-theme="dark"] [data-cat="grounding"] { --cat: #6b8aff; } +[data-theme="dark"] [data-cat="decision"] { --cat: #3fd6c0; } +[data-theme="dark"] [data-cat="output"] { --cat: #a48bff; } +[data-theme="dark"] [data-cat="critique"] { --cat: #ff7d94; } +[data-theme="dark"] [data-cat="control"] { --cat: #e0a64a; } +[data-theme="dark"] [data-cat="composition"] { --cat: #5fc06f; } * { box-sizing: border-box; } -html { scroll-behavior: smooth; scroll-padding-top: 72px; } -@media (prefers-reduced-motion: reduce) { html { scroll-behavior: auto; } } +html { scroll-behavior: smooth; scroll-padding-top: 72px; overflow-x: clip; } +@media (prefers-reduced-motion: reduce) { + html { scroll-behavior: auto; } + .pcard { transition: none; } + .pcard:hover { transform: none; } + .sidebar, .sidebar-backdrop { transition: none; } + .hero__blob { animation: none; } + .cat-box, .btn { transition: none; } + .cat-box:hover, .btn:hover { transform: none; } +} body { margin: 0; font-family: var(--sans); color: var(--text); background: var(--bg); line-height: 1.5; } a { color: var(--accent); text-decoration: none; } a:hover { text-decoration: underline; } +:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; border-radius: 4px; } +.header-nav a:focus-visible { text-decoration: none; } /* Header */ .site-header { @@ -68,14 +92,23 @@ a:hover { text-decoration: underline; } } .brand { font-weight: 800; font-size: 18px; color: var(--text); letter-spacing: -.01em; } .brand span { color: var(--accent); } -.header-nav { display: flex; align-items: center; gap: 18px; } -.header-nav a { color: var(--text-muted); font-size: 14px; font-weight: 500; } +.header-nav { display: flex; align-items: center; gap: 14px; } +.header-nav a { display: inline-flex; align-items: center; min-height: 44px; color: var(--text-muted); font-size: 14px; font-weight: 500; } +.header-nav a:hover { color: var(--text); text-decoration: none; } +.header-nav .nav-short { display: none; } +.header-nav .fa-github { font-size: 19px; line-height: 1; padding: 0 2px; } .theme-toggle { - width: 34px; height: 34px; border-radius: 8px; border: 1px solid var(--border-strong); + width: 40px; height: 40px; border-radius: 8px; border: 1px solid var(--border-strong); background: var(--bg-elevated); cursor: pointer; display: grid; place-items: center; padding: 0; } -.theme-toggle__icon::before { content: "🌙"; font-size: 15px; } -[data-theme="dark"] .theme-toggle__icon::before { content: "☀️"; } +.theme-toggle__icon::before { font-family: "Font Awesome 6 Free"; font-weight: 900; content: "\f186"; font-size: 14px; color: var(--text-muted); } +[data-theme="dark"] .theme-toggle__icon::before { content: "\f185"; color: var(--text-muted); } +.nav-hamburger { display: none; width: 40px; height: 40px; border-radius: 8px; border: 1px solid var(--border-strong); background: var(--bg-elevated); cursor: pointer; place-items: center; padding: 0; } +.nav-hamburger__icon::before { font-family: "Font Awesome 6 Free"; font-weight: 900; content: "\f0c9"; font-size: 15px; color: var(--text-muted); } +.nav-hamburger[aria-expanded="true"] .nav-hamburger__icon::before { content: "\f00d"; } +.sidebar-backdrop { position: fixed; inset: var(--header-h) 0 0 0; background: rgba(8,10,18,.5); opacity: 0; visibility: hidden; transition: opacity .22s ease, visibility .22s ease; z-index: 30; } +.sidebar-backdrop.is-visible { opacity: 1; visibility: visible; } +@media (min-width: 821px) { .sidebar-backdrop, body > .sidebar { display: none; } } /* Layout */ .layout { display: flex; align-items: flex-start; max-width: 1120px; margin: 0 auto; } @@ -90,13 +123,23 @@ a:hover { text-decoration: underline; } border: 1px solid var(--border-strong); border-radius: 8px; background: var(--bg); color: var(--text); } +.sidebar-search { position: sticky; top: 0; z-index: 1; margin: 0 0 14px; padding-bottom: 2px; background: var(--bg); } +.sidebar-search i { position: absolute; left: 11px; top: 50%; transform: translateY(-50%); color: var(--text-faint); font-size: 13px; pointer-events: none; } +.sidebar-search input { padding-left: 34px; } +.sidebar-empty { color: var(--text-faint); font-size: 13px; padding: 8px 10px; margin: 6px 0 0; } +.sidebar-pages { list-style: none; margin: 0 0 4px; padding: 0 0 14px; border-bottom: 1px solid var(--border); display: flex; flex-direction: column; gap: 2px; } +.sidebar-pages a { display: flex; align-items: center; gap: 10px; padding: 8px 10px; border-radius: 6px; font-size: 13.5px; font-weight: 600; color: var(--text-muted); } +.sidebar-pages a i { width: 1.15em; text-align: center; color: var(--text-faint); font-size: 13px; } +.sidebar-pages a:hover { background: var(--bg-elevated); color: var(--text); text-decoration: none; } +.sidebar-pages a.is-active { background: color-mix(in srgb, var(--accent) 12%, transparent); color: var(--accent); } +.sidebar-pages a.is-active i { color: var(--accent); } .sidebar-cat { margin-top: 18px; } -.sidebar-cat__title { font-size: 11px; font-weight: 700; text-transform: uppercase; letter-spacing: .07em; color: var(--text-faint); margin: 0 0 6px; } +.sidebar-cat__title { font-size: 11px; font-weight: 700; text-transform: uppercase; letter-spacing: .07em; color: var(--cat, var(--text-faint)); margin: 0 0 6px; } .sidebar-cat ul { list-style: none; margin: 0; padding: 0; } -.sidebar-cat a { display: block; padding: 4px 10px; font-size: 13.5px; color: var(--text-muted); border-radius: 6px; } +.sidebar-cat a { display: block; padding: 8px 10px; font-size: 13.5px; color: var(--text-muted); border-radius: 6px; } .sidebar-cat a:hover { text-decoration: none; background: var(--bg-elevated); } -.sidebar-cat a.is-active { background: var(--accent); color: var(--accent-contrast); font-weight: 600; } -.sidebar-cat a.is-active:hover { background: var(--accent); } +.sidebar-cat a.is-active { background: color-mix(in srgb, var(--cat, var(--accent)) 14%, transparent); color: var(--cat, var(--accent)); font-weight: 600; } +.sidebar-cat a.is-active:hover { background: color-mix(in srgb, var(--cat, var(--accent)) 18%, transparent); } .sidebar-cat a i { display: inline-block; width: 1.15em; margin-right: 8px; text-align: center; color: var(--text-faint); } .sidebar-cat a.is-active i { color: inherit; } @@ -106,9 +149,9 @@ a:hover { text-decoration: underline; } .intro h1 { font-size: 34px; font-weight: 800; letter-spacing: -.02em; margin: 0 0 12px; } .intro p { color: var(--text-muted); max-width: var(--content-max); font-size: 16px; margin: 0 0 10px; } -.cat-section { padding-top: 26px; } -.cat-section__title { font-size: 13px; font-weight: 700; text-transform: uppercase; letter-spacing: .06em; color: var(--accent); margin: 0 0 2px; } -.cat-section__desc { color: var(--text-faint); margin: 0 0 8px; font-size: 14px; } +.cat-section { padding-top: 46px; } +.cat-section__title { font-size: 18px; font-weight: 800; text-transform: uppercase; letter-spacing: .035em; color: var(--cat, var(--accent)); margin: 0 0 5px; } +.cat-section__desc { color: var(--text-faint); margin: 0 0 16px; font-size: 14px; } .pattern { padding: 22px 0; border-top: 1px solid var(--border); max-width: var(--content-max); } .pattern__title { font-size: 22px; font-weight: 800; letter-spacing: -.01em; margin: 0 0 6px; } @@ -116,7 +159,7 @@ a:hover { text-decoration: underline; } .pattern__adds-label { font-size: 12px; text-transform: uppercase; letter-spacing: .05em; color: var(--text); margin: 0 0 8px; } .pattern__adds { list-style: none; margin: 0 0 16px; padding: 0; } .pattern__adds li { position: relative; padding: 4px 0 4px 22px; color: var(--text-muted); } -.pattern__adds li::before { content: "+"; position: absolute; left: 0; color: var(--accent); font-weight: 800; } +.pattern__adds li::before { content: "+"; position: absolute; left: 0; color: var(--cat, var(--accent)); font-weight: 800; } .prompt { border: 1px solid var(--prompt-border); border-radius: var(--radius); overflow: hidden; background: var(--prompt-bg); } .prompt__head { display: flex; justify-content: space-between; align-items: center; padding: 9px 14px; background: var(--prompt-bg-head); border-bottom: 1px solid var(--prompt-border); } @@ -129,7 +172,7 @@ a:hover { text-decoration: underline; } .is-hidden { display: none !important; } /* Content pages (about, how-to) */ -.page { max-width: 880px; margin: 0 auto; padding: 48px 28px 72px; } +.page { flex: 1 1 auto; min-width: 0; max-width: 820px; padding: 40px 40px 72px; } .page h1 { font-size: 36px; font-weight: 800; letter-spacing: -.025em; margin: 0 0 10px; } .page h2 { font-size: 22px; font-weight: 700; letter-spacing: -.01em; color: var(--text); margin: 44px 0 14px; padding-top: 28px; border-top: 1px solid var(--border); } .page h1 + h2 { border-top: none; padding-top: 0; margin-top: 22px; } @@ -156,6 +199,10 @@ a:hover { text-decoration: underline; } .site-footer { border-top: 1px solid var(--border); padding: 28px 24px; text-align: center; color: var(--text-faint); font-size: 13px; } .site-footer p { margin: 4px 0; } .site-footer a { color: var(--text-muted); } +.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); } @@ -164,39 +211,134 @@ a:hover { text-decoration: underline; } .hero__bg::before { content: ""; position: absolute; inset: 0; background-image: linear-gradient(var(--grid-line) 1px, transparent 1px), linear-gradient(90deg, var(--grid-line) 1px, transparent 1px); background-size: 38px 38px; -webkit-mask-image: radial-gradient(560px 240px at 50% 0, #000, transparent 75%); mask-image: radial-gradient(560px 240px at 50% 0, #000, transparent 75%); } .hero__bg::after { content: ""; position: absolute; left: 50%; top: -130px; transform: translateX(-50%); width: 620px; height: 360px; border-radius: 50%; background: var(--hero-glow); filter: blur(48px); } .hero__inner { position: relative; max-width: 720px; margin: 0 auto; } -.hero__eyebrow { font-size: 12px; letter-spacing: .1em; color: var(--accent); margin-bottom: 14px; } -.hero h1 { font-size: clamp(40px, 7vw, 68px); line-height: 1.02; letter-spacing: -.03em; margin: 0; font-weight: 800; color: var(--text); } -[data-theme="light"] .hero h1 { background: linear-gradient(120deg, #0b1020, #3858E9 62%, #6d4aff); -webkit-background-clip: text; background-clip: text; -webkit-text-fill-color: transparent; color: transparent; } -[data-theme="dark"] .hero h1 { color: #fff; text-shadow: 0 0 42px rgba(91,124,255,.45); } -.hero p { font-size: 18px; color: var(--text-muted); margin: 16px auto 26px; max-width: 540px; line-height: 1.5; } -.search--home { position: relative; max-width: 460px; margin: 0 auto; } -.search--home i { position: absolute; left: 16px; top: 50%; transform: translateY(-50%); color: var(--text-faint); font-size: 14px; } -.search--home input { width: 100%; padding: 13px 16px 13px 42px; border: 1px solid var(--border-strong); border-radius: 12px; font-size: 15px; font-family: var(--sans); background: var(--bg); color: var(--text); box-shadow: var(--hero-search-shadow); } +.hero__eyebrow { display: inline-flex; align-items: center; gap: 8px; font-size: 12.5px; letter-spacing: .1em; color: var(--text-muted); padding: 6px 14px; border-radius: 999px; border: 1px solid var(--border-strong); background: color-mix(in srgb, var(--bg) 70%, transparent); margin-bottom: 18px; } +.hero__eyebrow i { color: var(--accent); } +.hero h1 { font-size: clamp(40px, 7.4vw, 76px); line-height: 1.02; letter-spacing: -.03em; margin: 0; font-weight: 850; color: var(--text); } +.hero h1 .grad { background: linear-gradient(100deg, #5b7cff, #b45cff 45%, #ff7da6 80%); -webkit-background-clip: text; background-clip: text; -webkit-text-fill-color: transparent; color: transparent; } +[data-theme="dark"] .hero h1 { text-shadow: 0 0 42px rgba(91,124,255,.22); } +.hero p { font-size: clamp(17px, 2.2vw, 20px); color: var(--text-muted); margin: 18px auto 0; max-width: 580px; line-height: 1.5; } + +/* Hero — aurora blobs, CTAs, stats */ +.hero__inner { position: relative; z-index: 1; } +.hero__blobs { position: absolute; inset: 0; z-index: 0; overflow: hidden; pointer-events: none; } +.hero__blob { position: absolute; border-radius: 50%; filter: blur(64px); opacity: .4; animation: hero-float 18s ease-in-out infinite; } +.hero__blob.a { width: 420px; height: 420px; top: -150px; left: -60px; background: radial-gradient(circle, #5b7cff, transparent 70%); } +.hero__blob.b { width: 400px; height: 400px; top: -120px; right: -50px; background: radial-gradient(circle, #b45cff, transparent 70%); animation-delay: -6s; } +.hero__blob.c { width: 340px; height: 340px; bottom: -200px; left: 42%; background: radial-gradient(circle, #2ad3c0, transparent 70%); animation-delay: -11s; } +[data-theme="dark"] .hero__blob { opacity: .5; } +@keyframes hero-float { 0%, 100% { transform: translate(0, 0) scale(1); } 50% { transform: translate(26px, -22px) scale(1.08); } } +.hero__cta { display: flex; flex-wrap: wrap; gap: 12px; justify-content: center; margin-top: 28px; } +.btn { display: inline-flex; align-items: center; gap: 9px; padding: 13px 24px; border-radius: 12px; font-weight: 650; font-size: 15px; transition: transform .15s ease, box-shadow .15s ease, border-color .15s ease; } +.btn--primary { color: #fff; background: linear-gradient(100deg, var(--accent), #8b5cff); box-shadow: 0 14px 34px color-mix(in srgb, var(--accent) 38%, transparent); } +.btn--primary:hover { transform: translateY(-2px); box-shadow: 0 20px 44px color-mix(in srgb, var(--accent) 48%, transparent); text-decoration: none; } +.btn--ghost { color: var(--text); border: 1px solid var(--border-strong); background: color-mix(in srgb, var(--bg) 60%, transparent); } +.btn--ghost:hover { transform: translateY(-2px); border-color: var(--accent); text-decoration: none; } +.hero__stats { display: flex; flex-wrap: wrap; gap: 36px; justify-content: center; margin: 36px 0 0; } +.hero__stat dt { font-size: 30px; font-weight: 800; letter-spacing: -.02em; color: var(--text); } +.hero__stat dd { margin: 4px 0 0; font-size: 12px; color: var(--text-faint); text-transform: uppercase; letter-spacing: .08em; } + /* Index card grid */ .home { max-width: 1040px; margin: 0 auto; padding: 10px 24px 64px; } + +/* Category overview — at-a-glance index above the sticky nav and full sections */ +.cat-overview { display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); gap: 20px; padding: 18px 0 10px; } +.cat-box { position: relative; border: 1px solid var(--border); border-radius: 18px; padding: 22px; background: var(--card-bg); overflow: hidden; transition: transform .18s ease, box-shadow .18s ease, border-color .18s ease; } +.cat-box::before { content: ""; position: absolute; inset: 0 0 auto 0; height: 4px; background: var(--cat, var(--accent)); } +.cat-box::after { content: ""; position: absolute; top: -50px; right: -50px; width: 150px; height: 150px; border-radius: 50%; background: var(--cat, var(--accent)); opacity: .12; filter: blur(26px); pointer-events: none; } +.cat-box:hover { transform: translateY(-3px); border-color: color-mix(in srgb, var(--cat, var(--accent)) 45%, transparent); box-shadow: var(--card-hover-shadow); } +.cat-box__head { display: flex; align-items: center; gap: 10px; } +.cat-box__head:hover { text-decoration: none; } +.cat-box__title { font-size: 17px; font-weight: 750; color: var(--cat, var(--accent)); margin: 0; letter-spacing: -.01em; } +.cat-box__head:hover .cat-box__title { text-decoration: underline; } +.cat-box__count { margin-left: auto; font-family: var(--mono); font-size: 12px; color: var(--text-faint); background: color-mix(in srgb, var(--cat, var(--accent)) 12%, transparent); border-radius: 999px; padding: 2px 9px; } +.cat-box__desc { color: var(--text-muted); font-size: 13.5px; margin: 8px 0 14px; line-height: 1.45; } +.cat-box__list { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 4px; } +.cat-box__list a { display: flex; align-items: center; gap: 10px; padding: 8px 11px; border-radius: 9px; font-size: 14px; color: var(--text); border: 1px solid transparent; transition: background .14s ease, border-color .14s ease; } +.cat-box__list a i { width: 1.1em; flex: 0 0 auto; text-align: center; color: var(--cat, var(--accent)); font-size: 12px; } +.cat-box__list a:hover { background: color-mix(in srgb, var(--cat, var(--accent)) 9%, var(--bg)); border-color: color-mix(in srgb, var(--cat, var(--accent)) 30%, transparent); text-decoration: none; } + +.cat-nav { + position: sticky; top: var(--header-h); z-index: 5; + display: flex; gap: 8px; overflow-x: auto; scrollbar-width: none; + padding: 12px 0; margin: 0 0 6px; background: var(--bg); border-bottom: 1px solid var(--border); +} +.cat-nav::-webkit-scrollbar { display: none; } +.cat-nav a { + display: inline-flex; align-items: center; min-height: 34px; padding: 5px 13px; white-space: nowrap; + font-size: 13px; font-weight: 600; color: var(--cat, var(--text-muted)); + background: var(--bg-elevated); border: 1px solid var(--border); border-radius: 999px; +} +.cat-nav a:hover { border-color: var(--cat, var(--border-strong)); background: color-mix(in srgb, var(--cat, var(--accent)) 8%, var(--bg-elevated)); text-decoration: none; } +.patterns-head { margin: 0 0 4px; } +.patterns-head h1 { font-size: 28px; font-weight: 800; letter-spacing: -.02em; margin: 0 0 6px; } +.patterns-head p { color: var(--text-muted); font-size: 15px; margin: 0; } +.cat-section { scroll-margin-top: 120px; } .card-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(264px, 1fr)); gap: 16px; } .pcard { display: block; border: 1px solid var(--border); border-radius: 16px; padding: 20px; background: var(--card-bg); text-decoration: none; transition: transform .15s, box-shadow .15s, border-color .15s; } .pcard:hover { transform: translateY(-3px); border-color: var(--card-hover-border); box-shadow: var(--card-hover-shadow); text-decoration: none; } -.pcard__icon { width: 44px; height: 44px; border-radius: 12px; display: grid; place-items: center; font-size: 18px; margin-bottom: 14px; background: var(--icon-tile-bg); border: 1px solid var(--icon-tile-border); color: var(--accent); } +.pcard__icon { width: 44px; height: 44px; border-radius: 12px; display: grid; place-items: center; font-size: 18px; margin-bottom: 14px; background: var(--icon-tile-bg); background: color-mix(in srgb, var(--cat, var(--accent)) 12%, transparent); border: 1px solid var(--icon-tile-border); border-color: color-mix(in srgb, var(--cat, var(--accent)) 22%, transparent); color: var(--cat, var(--accent)); } .pcard__title { font-size: 16px; font-weight: 700; color: var(--text); margin: 0 0 6px; letter-spacing: -.01em; } -.pattern__title i { color: var(--accent); margin-right: 10px; font-size: 0.9em; } +.pattern__title i { color: var(--cat, var(--accent)); margin-right: 10px; font-size: 0.9em; } .pcard__summary { font-size: 13.5px; color: var(--text-muted); margin: 0; line-height: 1.45; } -.no-results { color: var(--text-faint); padding: 12px 0; } +.no-results { color: var(--text-muted); padding: 16px 0; font-size: 15px; } +.no-results__reset { background: none; border: none; padding: 0; font: inherit; color: var(--accent); font-weight: 600; cursor: pointer; } +.no-results__reset:hover { text-decoration: underline; } /* Detail page */ .back-link { display: inline-block; font-size: 13px; color: var(--text-muted); margin-bottom: 16px; } .pattern__eyebrow { font-size: 11px; font-weight: 700; text-transform: uppercase; letter-spacing: .06em; margin-bottom: 4px; } -.pattern__eyebrow a { color: var(--accent); } +.pattern__eyebrow a { color: var(--cat, var(--accent)); } .pattern-detail .pattern { border-top: none; padding-top: 0; } /* Responsive */ @media (max-width: 820px) { - .layout { flex-direction: column; } - .sidebar { position: static; width: 100%; height: auto; flex-basis: auto; border-right: none; border-bottom: 1px solid var(--border); } + .layout { flex-direction: column; align-items: stretch; } + + /* 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; 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; -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; } + html.nav-drawer-open { overflow: hidden; } + .content { padding: 24px 20px; } .home { padding: 24px 20px; } .hero { padding: 44px 20px 36px; } + .hero__stats { gap: 26px; } .page { padding: 32px 20px 56px; } .page tbody td:first-child { width: auto; } + .header-nav { gap: 12px; } + .header-nav .nav-full { display: none; } + .header-nav .nav-short { display: inline; } +} + +/* Phones — tighter than tablet (which keeps the 820px treatment) */ +@media (max-width: 560px) { + .site-header { padding: 0 16px; } + .hero { padding: 36px 18px 28px; } + .hero h1 { font-size: clamp(30px, 8.5vw, 40px); } + .hero p { font-size: 16px; } + .hero__cta { flex-direction: column; align-items: stretch; } + .hero__cta .btn { justify-content: center; } + .hero__stats { gap: 18px; } + .hero__stat dt { font-size: 24px; } + .content { padding: 20px 16px; } + .home { padding: 18px 16px 48px; } + .page { padding: 28px 16px 48px; } + .page h1 { font-size: 30px; } + .card-grid { grid-template-columns: 1fr; gap: 12px; } + .cat-overview { grid-template-columns: 1fr; gap: 14px; } + .patterns-head h1 { font-size: 24px; } } diff --git a/assets/js/app.js b/assets/js/app.js index 5cfcfc3..d1fdea0 100644 --- a/assets/js/app.js +++ b/assets/js/app.js @@ -1,35 +1,66 @@ (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'); + var hamburger = document.getElementById('nav-hamburger'); + var backdrop = document.getElementById('sidebar-backdrop'); + if (sidebar && hamburger) { + var setDrawer = function (open) { + sidebar.classList.toggle('is-open', open); + 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.documentElement.classList.toggle('nav-drawer-open', open); + }; + hamburger.addEventListener('click', function () { + setDrawer(!sidebar.classList.contains('is-open')); + }); + if (backdrop) { backdrop.addEventListener('click', function () { setDrawer(false); }); } + sidebar.addEventListener('click', function (e) { + if (e.target.closest('a')) { setDrawer(false); } + }); + document.addEventListener('keydown', function (e) { + if (e.key === 'Escape' && sidebar.classList.contains('is-open')) { setDrawer(false); } + }); } /* Index search — filters cards by full-text data-search attribute */ + /* Sidebar pattern filter (detail pages) */ var search = document.getElementById('pattern-search'); - var cards = Array.prototype.slice.call(document.querySelectorAll('.pcard')); - if (search && cards.length) { - var sections = Array.prototype.slice.call(document.querySelectorAll('.cat-section')); - var noResults = document.getElementById('no-results'); + var sideItems = Array.prototype.slice.call(document.querySelectorAll('.sidebar-cat li')); + if (search && sideItems.length) { + var sideGroups = Array.prototype.slice.call(document.querySelectorAll('.sidebar-cat')); + var sideEmpty = document.getElementById('sidebar-empty'); - var applyFilter = function (q) { - q = (q || '').trim().toLowerCase(); + var applyFilter = function (raw) { + var q = (raw || '').trim().toLowerCase(); var anyVisible = false; - cards.forEach(function (c) { - var match = q === '' || (c.getAttribute('data-search') || '').indexOf(q) !== -1; - c.classList.toggle('is-hidden', !match); + sideItems.forEach(function (li) { + var a = li.querySelector('a'); + var match = q === '' || (a ? a.textContent.toLowerCase() : '').indexOf(q) !== -1; + li.classList.toggle('is-hidden', !match); if (match) { anyVisible = true; } }); - sections.forEach(function (s) { - s.classList.toggle('is-hidden', s.querySelectorAll('.pcard:not(.is-hidden)').length === 0); + sideGroups.forEach(function (g) { + g.classList.toggle('is-hidden', g.querySelectorAll('li:not(.is-hidden)').length === 0); }); - if (noResults) { noResults.classList.toggle('is-hidden', anyVisible); } + if (sideEmpty) { sideEmpty.classList.toggle('is-hidden', anyVisible); } + }; + + var resetSearch = function () { + search.value = ''; + applyFilter(''); + search.focus(); }; search.addEventListener('input', function () { applyFilter(search.value); }); @@ -39,8 +70,7 @@ e.preventDefault(); search.focus(); } else if (e.key === 'Escape' && document.activeElement === search) { - search.value = ''; - applyFilter(''); + resetSearch(); } }); } diff --git a/about.md b/docs.md similarity index 90% rename from about.md rename to docs.md index cf0e83b..12e1b23 100644 --- a/about.md +++ b/docs.md @@ -1,8 +1,8 @@ --- -layout: page -title: What are skill patterns? +layout: doc +title: Docs description: Reusable, composable techniques for shaping how an AI agent behaves. -permalink: /about/ +permalink: /docs/ --- # What are skill patterns? @@ -30,4 +30,4 @@ Patterns are grouped by what they're *for*: Every pattern in the catalog has the same shape: a one-line **definition**, a short list of **what it adds**, and a copyable **example prompt partial** — a ready-to-use snippet with `[bracketed]` slots you fill in with your specifics. -[Browse the patterns →]({{ '/' | relative_url }}) · [How to use them →]({{ '/using/' | relative_url }}) +[Browse the patterns →]({{ '/patterns/' | relative_url }}) · [Install the Skill →]({{ '/using/' | relative_url }}) diff --git a/index.html b/index.html index bdcb460..b76a1d5 100644 --- a/index.html +++ b/index.html @@ -1,6 +1,7 @@ --- layout: home title: Skill Patterns +sidebar: true --- -

Skill Patterns

-

Reusable techniques you can drop into a Skill to bake in specific behaviors — grounding, critique, decision-making, output shaping, and more.

+

Compose AI Skills that actually behave.

+

Drop-in techniques for grounding, critique, decision-making, and output shaping — proven moves you paste straight into a Skill.

diff --git a/manual.md b/manual.md new file mode 100644 index 0000000..d1afb27 --- /dev/null +++ b/manual.md @@ -0,0 +1,57 @@ +--- +layout: doc +title: Manual usage +description: Place patterns by hand — copy a prompt partial, fill in the brackets, and compose a few. +permalink: /manual/ +--- + +# Manual usage + +Prefer to place patterns by hand instead of letting an AI do it? Here's the whole workflow. (To install the Skill and let AI apply patterns for you, see [Install]({{ '/using/' | relative_url }}).) + +## Build manually + +1. Find a pattern that matches the behavior you want. +2. Copy its **example prompt partial**. +3. Fill in the `[bracketed]` slots with your specifics. +4. Paste it into your Skill's instructions (its `SKILL.md`) — or, for a one-off, straight into your prompt. + +That's it. A pattern is just a well-worded instruction; the catalog saves you from rediscovering the wording every time. + +### Choosing patterns + +Not sure which to grab? [Browse the catalog]({{ '/patterns/' | relative_url }}) — it's grouped by purpose, so skim the category that fits your skill's job. Most skills need only **two to four** patterns; composing more usually makes a skill worse. Or skip the picking entirely and let an AI choose (see [Install]({{ '/using/' | relative_url }})). + +### Fill in the brackets + +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]`… + +Replace `[tool / library / domain]` with `FastAPI`, swap in your actual conventions, and it's ready. + +### Compose several + +Patterns stack — most real Skills use two or three. Pick them in the order the work flows. A "draft a proposal" Skill might combine three: + +```text +# 1 — Clarification gate +Before producing the proposal, if anything ambiguous would change the result — +scope, audience, budget — ask me those questions first and wait. + +# 2 — Bounded option generation +Then generate 3 meaningfully different directions. For each, name what it +optimizes for and what it gives up. Recommend one, and say why not the others. + +# 3 — Decision capture +Alongside the recommendation, capture the assumptions you made and the +alternatives you rejected, written for someone who wasn't in the room. +``` + +Each block is one pattern, lightly adapted. Together they turn a vague "write me a proposal" into a reliable flow. + +## Test and adapt + +Patterns are starting points, not law. Run your Skill, watch where the agent drifts, and tighten the wording — make a criterion stricter, add a placeholder, or drop a step that's overkill. The prompts in the catalog are written to be edited. + +[Browse the patterns →]({{ '/patterns/' | relative_url }}) · [Install the Skill →]({{ '/using/' | relative_url }}) diff --git a/patterns.html b/patterns.html new file mode 100644 index 0000000..eafbb44 --- /dev/null +++ b/patterns.html @@ -0,0 +1,29 @@ +--- +layout: default +title: Patterns +permalink: /patterns/ +sidebar: true +--- +
+ {%- include sidebar.html -%} +
+
+

Patterns

+

{{ site.patterns | size }} composable techniques, grouped by the behavior they install.

+
+ {% assign cats = site.data.categories | sort: "order" %} + + {% for cat in cats %} +
+

{{ cat.title | escape }}

+

{{ cat.description | escape }}

+
+ {% assign pats = site.patterns | where: "category", cat.key | sort_natural: "title" %} + {% for p in pats %}{% include pattern-card.html pattern=p %}{% endfor %} +
+
+ {% endfor %} +
+
diff --git a/run.sh b/run.sh new file mode 100755 index 0000000..dac1088 --- /dev/null +++ b/run.sh @@ -0,0 +1,3 @@ +#!/bin/bash + +bundle exec jekyll serve --port 4069 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/ diff --git a/using.md b/using.md index f3caf65..806c4c0 100644 --- a/using.md +++ b/using.md @@ -1,65 +1,34 @@ --- -layout: page -title: Using the patterns -description: How to take a pattern's example prompt and put it to work in your own Skill. +layout: doc +title: Install the Skill +description: Add the Skill Patterns Skill and let your AI apply the right patterns as you build. permalink: /using/ --- -# Using the patterns +# Install the Skill -Most people build a Skill *with* an AI — so the fastest way to use these patterns is to let the AI apply them for you. Prefer to place them by hand? That works too, and the rest of this page walks through it. +Most people build a Skill *with* an AI — so the fastest way to use these patterns is to install the Skill and let the AI apply them for you. Prefer to place patterns by hand? See [Manual usage]({{ '/manual/' | relative_url }}). -## Build with an AI +## Get the Skill -> **Point your agent at the catalog** — [`/llms.txt`]({{ '/llms.txt' | relative_url }}) or [`/patterns.json`]({{ '/patterns.json' | relative_url }}) — and ask it to apply the patterns your skill's purpose calls for. It selects and weaves them in, then shows you what it chose so you can adjust. -> -> **Even easier:** install the **skill-patterns** skill — `npx skills add https://github.com/borkweb/skill-patterns --skill skill-patterns` — and it applies the right patterns automatically whenever you build a Skill. +Using a Skill makes pattern selection a breeze. Grab it and add it to your Skill-creation workflow. -That's the whole point of the catalog: you shouldn't have to hand-pick. The sections below are for when you *want* to. - -## The basic move - -1. Find a pattern that matches the behavior you want. -2. Copy its **example prompt partial**. -3. Fill in the `[bracketed]` slots with your specifics. -4. Paste it into your Skill's instructions (its `SKILL.md`) — or, for a one-off, straight into your prompt. - -That's it. A pattern is just a well-worded instruction; the catalog saves you from rediscovering the wording every time. - -## Choosing patterns - -Not sure which to grab? [Browse the catalog]({{ '/' | relative_url }}) — it's grouped by purpose, so skim the category that fits your skill's job. Most skills need only **two to four** patterns; composing more usually makes a skill worse. Or skip the picking entirely and let an AI choose (above). - -## Fill in the brackets - -The `[brackets]` are slots, not literal text. The Convention wrapper prompt, for instance, starts: - -> When the task involves `[tool / library / domain]`, follow these conventions: `[rules, or point to a reference doc]`… - -Replace `[tool / library / domain]` with `FastAPI`, swap in your actual conventions, and it's ready. - -## Compose several +``` +npx skills add borkweb/skill-patterns --skill skill-patterns +``` -Patterns stack — most real Skills use two or three. Pick them in the order the work flows. A "draft a proposal" Skill might combine three: +## Build with AI -```text -# 1 — Clarification gate -Before producing the proposal, if anything ambiguous would change the result — -scope, audience, budget — ask me those questions first and wait. +### Using the Skill -# 2 — Bounded option generation -Then generate 3 meaningfully different directions. For each, name what it -optimizes for and what it gives up. Recommend one, and say why not the others. +The easiest way to select patterns is using the Skill, which will apply the right patterns automatically whenever you build a Skill. -# 3 — Decision capture -Alongside the recommendation, capture the assumptions you made and the -alternatives you rejected, written for someone who wasn't in the room. -``` +**Example prompt to create a Skill:** -Each block is one pattern, lightly adapted. Together they turn a vague "write me a proposal" into a reliable flow. +> Create a Skill with /skill-creator and /skill-patterns that accepts an article URL, helps me craft my own narrative, then creates an X post and/or a LinkedIn post. -## Test and adapt +### Pointing your agent at the catalog -Patterns are starting points, not law. Run your Skill, watch where the agent drifts, and tighten the wording — make a criterion stricter, add a placeholder, or drop a step that's overkill. The prompts in the catalog are written to be edited. +If you don't want to use the Skill, but you still want your agent to auto-select patterns for you, you can point the agent at the catalog: [`/llms.txt`]({{ '/llms.txt' | relative_url }}) or [`/patterns.json`]({{ '/patterns.json' | relative_url }}) — and ask it to apply the patterns your skill's purpose calls for. It selects and weaves them in, then shows you what it chose so you can adjust. -[Browse the patterns →]({{ '/' | relative_url }}) · [What are skill patterns? →]({{ '/about/' | relative_url }}) +[Browse the patterns →]({{ '/patterns/' | relative_url }}) · [Place patterns by hand →]({{ '/manual/' | relative_url }})