chore: publish 25ef5af
Built from main 25ef5af63e
fix: refuse to publish a build that logged a vite error
This commit is contained in:
Marcos Paulo
@@ -1,10 +0,0 @@
|
||||
# Reusable skills
|
||||
|
||||
These project-local skills extract the design and implementation patterns used by AI For Dummies. They are intentionally small: copy a skill into an agent's skill directory, or give the `SKILL.md` path to an agent when building a new chapter.
|
||||
|
||||
## Skills
|
||||
|
||||
- [`editorial-playbook`](editorial-playbook/SKILL.md) — shape a content-led, responsive, bilingual explainer with small interactive islands.
|
||||
- [`rules-case-study`](rules-case-study/SKILL.md) — turn repository rules, skills, CLI checks, hooks, and review policy into a source-linked teaching page.
|
||||
|
||||
The reference files are deliberately disclosed beside each skill. The `evals/evals.json` files contain small prompts for checking that an agent reaches the right workflow.
|
||||
@@ -1,23 +0,0 @@
|
||||
const packageFiles = {
|
||||
skill: { label: 'SKILL.md', title: 'The operating contract', body: 'The one file that should always be loaded. Define the exact trigger, the ordered workflow, safety limits, and the evidence the agent returns.', code: '---\nname: review-ui\ndescription: Review a changed UI for focus, reflow, and motion.\n---\n\n1. Inspect the changed interaction.\n2. Run the UI checks.\n3. Return findings with evidence.' },
|
||||
references: { label: 'references/', title: 'Facts, only when needed', body: 'Keep conditional detail out of the main instruction. A dialog pattern, framework caveat, or accessibility checklist belongs here when it is not needed for every review.', code: 'references/\n└── accessibility.md\n ├── keyboard interaction patterns\n └── focus and reflow checklist' },
|
||||
scripts: { label: 'scripts/', title: 'Mechanics that should not depend on memory', body: 'Turn deterministic checks into runnable tools. The agent still judges the result, but it should not have to recreate a viewport test or filename rule by hand.', code: 'scripts/\n└── check-reflow.mjs\n └── checks 320px, 1280px, and 4K widths' },
|
||||
assets: { label: 'assets/', title: 'Starting material, not hidden instructions', body: 'Use assets for templates and examples a person or agent can copy. Keep them clearly named so package readers can choose the right starting point.', code: 'assets/\n├── review-report.md\n└── focus-test-fixture.html' }
|
||||
};
|
||||
|
||||
const preview = document.querySelector('#package-preview');
|
||||
const buttons = [...document.querySelectorAll('[data-package-file]')];
|
||||
function renderPackage(file) {
|
||||
const item = packageFiles[file];
|
||||
preview.classList.remove('is-swapping');
|
||||
void preview.offsetWidth;
|
||||
preview.classList.add('is-swapping');
|
||||
preview.innerHTML = `<span>SELECTED / ${item.label}</span><h3>${item.title}</h3><p>${item.body}</p><pre><code>${item.code}</code></pre>`;
|
||||
buttons.forEach((button) => {
|
||||
const selected = button.dataset.packageFile === file;
|
||||
button.classList.toggle('active', selected);
|
||||
button.setAttribute('aria-selected', String(selected));
|
||||
});
|
||||
}
|
||||
buttons.forEach((button) => button.addEventListener('click', () => renderPackage(button.dataset.packageFile)));
|
||||
renderPackage('skill');
|
||||
@@ -1,19 +0,0 @@
|
||||
---
|
||||
name: editorial-playbook
|
||||
description: Use when building or reshaping a content-led interactive explainer, technical playbook, or presentation-like static page; define the information architecture, visual system, responsive behavior, bilingual copy, and minimal interactive islands before coding.
|
||||
---
|
||||
|
||||
# Editorial playbook
|
||||
|
||||
Treat the page as a guided argument, not a dashboard. Give it one audience, one job, and one memorable thesis.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Write the chapter map before markup. Every section gets a stable slug, number, title, purpose, and a single interaction or proof point when useful. Reach for [page anatomy](references/page-anatomy.md) when adding a new section.
|
||||
2. Compose from a few editorial primitives: label, thesis, pipeline or diagram, comparison/table, code panel, callout, source card, and next-chapter link. Keep the content model separate from rendering so more sections stay cheap.
|
||||
3. Use a restrained visual system: paper background, ink text, muted copy, one cool accent, one warm signal, hairlines, and typography with a strong display/body contrast. Prefer intentional asymmetry and generous rhythm over cards everywhere.
|
||||
4. Keep runtime light. Use plain HTML/CSS/JS for static, mostly content-led pages. Choose Astro or MDX only when many chapters need shared templates, content collections, or build-time localization. Preserve an existing framework when it already owns routing and tokens.
|
||||
5. Make the page bilingual at the content boundary. Pair English and Portuguese strings, toggle the document language, persist the choice, and translate labels, controls, status text, and dynamic details—not paths, commands, or code.
|
||||
6. Make interactions causal and inspectable. One active state should explain one idea; expose it with keyboard focus, an accessible state, a live status region, copy feedback, and a reduced-motion path.
|
||||
7. Design for mobile, Full HD, and 4K. Use fluid type and spacing, cap readable measure, stack dense regions at narrow widths, keep diagrams scrollable only when semantically necessary, and test 390px, 1920px, and 3840px viewports.
|
||||
8. Finish with evidence: content verification, JavaScript syntax checks, interaction tests, responsive browser checks, and a diff check. The section is done when its content, dynamic states, links, and three viewport classes pass.
|
||||
@@ -1,10 +0,0 @@
|
||||
[
|
||||
{
|
||||
"prompt": "Add a new bilingual chapter to a dependency-free static explainer with one diagram and one copy control. What should you decide and verify first?",
|
||||
"expected_behavior": "Create a chapter map and content model first; pair EN/PT strings; use a small accessible interaction; verify mobile, Full HD, and 4K behavior."
|
||||
},
|
||||
{
|
||||
"prompt": "The explainer needs 20 more sections but has no data source for section metadata. Recommend a lightweight implementation.",
|
||||
"expected_behavior": "Keep content in structured data and render shared editorial primitives; recommend plain HTML/CSS/JS for a small static site, or Astro/MDX when shared build-time content collections justify it."
|
||||
}
|
||||
]
|
||||
@@ -1,16 +0,0 @@
|
||||
# Page anatomy
|
||||
|
||||
Use this as a compact design contract for a new AI For Dummies chapter.
|
||||
|
||||
1. **Orientation** — eyebrow, chapter number, title, short promise, language control.
|
||||
2. **Thesis** — one sentence that changes how the reader sees the topic.
|
||||
3. **Model** — a pipeline, tree, timeline, or comparison that makes the relationship visible.
|
||||
4. **Practice** — a copy-ready prompt, command, example, or tiny exercise.
|
||||
5. **Proof** — source paths, checks, observed behavior, and the boundary between advice and enforcement.
|
||||
6. **Transfer** — a small “use this next” link to the next chapter or deeper source.
|
||||
|
||||
Keep the first screen editorial and calm. Let code, diagrams, and controls earn their space by teaching something. Avoid a generic hero followed by an undifferentiated card grid.
|
||||
|
||||
## Section contract
|
||||
|
||||
Each new section should answer: what does the reader learn, what is the visible proof, what can they copy or try, and what source supports it? Add its copy to the language map before adding a control. Add its slug to navigation only after the section has a stable purpose.
|
||||
+45
-33
@@ -1,33 +1,45 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width,initial-scale=1">
|
||||
<meta name="description" content="A practical guide to creating compact, reusable AI coding skills.">
|
||||
<title>AI For Dummies — Skills</title>
|
||||
<link rel="stylesheet" href="../chapters.css">
|
||||
<link rel="stylesheet" href="styles.css">
|
||||
</head>
|
||||
<body>
|
||||
<main>
|
||||
<header class="top"><a href="../summary/">← ROUTE MAP</a><span>03 / SKILLS</span><a href="../skills-review/">review desk ↗</a></header>
|
||||
<section class="hero"><p class="eyebrow">Reusable judgment</p><h1>Teach the<br><em>decision.</em></h1><p>A skill changes behavior. Keep the trigger precise, put the workflow in <code>SKILL.md</code>, and move conditional facts, scripts, and examples into focused files.</p></section>
|
||||
<section class="pipeline package-anatomy">
|
||||
<div><p class="eyebrow">Package anatomy</p><h2>One job.<br>More than<br>one <em>file.</em></h2><p class="package-hint">Choose a file to see why it belongs in the package.</p></div>
|
||||
<div class="package-workbench" data-package-workbench>
|
||||
<div class="package-tree" role="tablist" aria-label="Files in the review-ui skill package">
|
||||
<p>REVIEW-UI / SKILL PACKAGE</p>
|
||||
<button class="active" data-package-file="skill" role="tab" aria-selected="true"><code>├── SKILL.md</code><small>trigger + workflow</small></button>
|
||||
<button data-package-file="references" role="tab" aria-selected="false"><code>├── references/</code><small>conditional facts</small></button>
|
||||
<button data-package-file="scripts" role="tab" aria-selected="false"><code>├── scripts/</code><small>deterministic checks</small></button>
|
||||
<button data-package-file="assets" role="tab" aria-selected="false"><code>└── assets/</code><small>templates + examples</small></button>
|
||||
</div>
|
||||
<article class="package-preview" id="package-preview" aria-live="polite"></article>
|
||||
</div>
|
||||
</section>
|
||||
<section class="practice"><div><p class="eyebrow">Create a skill</p><h2>Observe →<br>trigger →<br>validate</h2></div><div class="steps"><article><b>01</b><div><strong>Observe friction</strong><span>Find a repeated decision or failure.</span></div></article><article><b>02</b><div><strong>Define the trigger</strong><span>Say when it should load and when it should stay out.</span></div></article><article><b>03</b><div><strong>Choose anatomy</strong><span>Use references for facts and scripts for deterministic mechanics.</span></div></article><article><b>04</b><div><strong>Evaluate behavior</strong><span>Test realistic prompts, edge cases, safety, and evidence.</span></div></article></div></section>
|
||||
<nav class="links"><a href="../agents/">Agents & trees →</a><a href="../rules/">Rules case study →</a><a href="../skills-review/">Review submitted skills →</a><a href="../full-guide/#create-skill">Full guide: skill forge →</a></nav>
|
||||
</main>
|
||||
<script src="app.js" defer></script>
|
||||
</body>
|
||||
</html>
|
||||
<!DOCTYPE html><html lang="en"> <head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>AI For Dummies — Skills</title><meta name="description" content="A skill changes behavior. Keep the trigger precise, put the workflow in SKILL.md, and move conditional facts, scripts, and examples into focused files."><link rel="stylesheet" href="/ai-for-dummies/_astro/tokens.CVOStimI.css"><link rel="stylesheet" href="/ai-for-dummies/fonts/fonts.css"><link rel="stylesheet" href="/ai-for-dummies/_astro/chapters.Bvwgp4pJ.css"><style>.package-workbench[data-astro-cid-xk5n4466]{display:grid;grid-template-columns:minmax(190px,.85fr) minmax(0,1.3fr);min-width:0;background:var(--ink);border:1px solid var(--ink);box-shadow:10px 10px color-mix(in srgb,var(--gold) 55%,transparent)}.package-tree[data-astro-cid-xk5n4466]{padding:22px 16px;border-right:1px solid var(--muted);min-width:0}.package-tree[data-astro-cid-xk5n4466]>p[data-astro-cid-xk5n4466],.package-preview[data-astro-cid-xk5n4466]>span[data-astro-cid-xk5n4466]{margin:0 0 14px;color:var(--gold);font:700 var(--step-0) / 1.35 ui-monospace,monospace;letter-spacing:.1em}.package-tree[data-astro-cid-xk5n4466] button[data-astro-cid-xk5n4466]{display:grid;grid-template-columns:minmax(0,1fr) auto;align-items:center;gap:8px;width:100%;padding:12px 8px;border:0;border-left:2px solid transparent;background:transparent;color:var(--line);text-align:left;cursor:pointer;transition:background .2s ease,border-color .2s ease,transform .2s ease}.package-tree[data-astro-cid-xk5n4466] button[data-astro-cid-xk5n4466]:hover,.package-tree[data-astro-cid-xk5n4466] button[data-astro-cid-xk5n4466]:focus-visible,.package-tree[data-astro-cid-xk5n4466] button[data-astro-cid-xk5n4466].active{border-left-color:var(--gold);background:var(--blue);outline:0}.package-tree[data-astro-cid-xk5n4466] button[data-astro-cid-xk5n4466]:hover{transform:translate(3px)}.package-tree[data-astro-cid-xk5n4466] code[data-astro-cid-xk5n4466]{min-width:0;overflow-wrap:anywhere;font:700 13px/1.4 ui-monospace,monospace}.package-tree[data-astro-cid-xk5n4466] small[data-astro-cid-xk5n4466]{color:var(--muted);font:11px/1.25 Arial,sans-serif;text-align:right}.package-preview[data-astro-cid-xk5n4466]{min-width:0;padding:26px;background:var(--ink);color:var(--paper)}.package-preview[data-astro-cid-xk5n4466] h3[data-astro-cid-xk5n4466]{margin:0 0 8px;font-size:clamp(24px,3vw,38px);line-height:1.02;letter-spacing:-.045em}.package-preview[data-astro-cid-xk5n4466] p[data-astro-cid-xk5n4466]{max-width:52ch;margin:0;color:var(--line)}.package-preview[data-astro-cid-xk5n4466] pre[data-astro-cid-xk5n4466]{max-width:100%;margin:20px 0 0;padding:15px;overflow:auto;border:1px solid var(--muted);background:var(--deep);color:var(--line);font:12px/1.55 ui-monospace,monospace}.package-preview[data-astro-cid-xk5n4466].is-swapping{animation:package-preview-in .2s cubic-bezier(.2,0,0,1) both}@keyframes package-preview-in{0%{opacity:.25;transform:translateY(7px)}to{opacity:1;transform:translateY(0)}}@media(max-width:800px){.package-workbench[data-astro-cid-xk5n4466]{grid-template-columns:1fr}.package-tree[data-astro-cid-xk5n4466]{border-right:0;border-bottom:1px solid var(--muted)}.package-preview[data-astro-cid-xk5n4466]{padding:22px}}@media(max-width:560px){.package-tree[data-astro-cid-xk5n4466]{padding:18px 10px}.package-tree[data-astro-cid-xk5n4466] button[data-astro-cid-xk5n4466]{padding:12px 6px}.package-tree[data-astro-cid-xk5n4466] small[data-astro-cid-xk5n4466]{display:none}.package-preview[data-astro-cid-xk5n4466]{padding:18px}.package-preview[data-astro-cid-xk5n4466] pre[data-astro-cid-xk5n4466]{font-size:var(--step-0)}}@media(prefers-reduced-motion:reduce){[data-astro-cid-xk5n4466],[data-astro-cid-xk5n4466]:before,[data-astro-cid-xk5n4466]:after{scroll-behavior:auto!important;animation-duration:.01ms!important;animation-iteration-count:1!important;transition-duration:.01ms!important}}
|
||||
.top[data-astro-cid-xattfbdu]{display:flex;align-items:baseline;justify-content:space-between;gap:20px;padding:24px 0;border-bottom:1px solid var(--line);font:700 var(--step-0) monospace;letter-spacing:.08em;text-transform:uppercase}.top[data-astro-cid-xattfbdu] a{color:var(--ink);text-decoration:none}.top[data-astro-cid-xattfbdu] a:focus-visible{outline:3px solid var(--red);outline-offset:2px}@media(max-width:560px){.cell[data-astro-cid-xattfbdu]:nth-child(2){display:none}}.footer[data-astro-cid-bmvnf73n]{padding:30px 0 70px;color:var(--muted);font-size:clamp(13px,13px,13px)}.links[data-astro-cid-bmvnf73n]{display:flex;flex-wrap:wrap;gap:10px;margin:28px 0 70px}.links[data-astro-cid-bmvnf73n] a{padding:10px 13px;color:var(--ink);border:1px solid var(--ink);text-decoration:none;font:var(--step-0) monospace;text-transform:uppercase}.links[data-astro-cid-bmvnf73n] a:hover{color:var(--paper);background:var(--ink)}.links[data-astro-cid-bmvnf73n] a:focus-visible{outline:3px solid var(--red);outline-offset:2px}.eyebrow[data-astro-cid-4yr5atew]{margin:0;font:600 var(--step-0) "DM Mono",monospace;letter-spacing:.1em;text-transform:uppercase}.tone-accent[data-astro-cid-4yr5atew]{color:var(--accent)}.tone-gold[data-astro-cid-4yr5atew]{color:var(--gold)}.tone-red[data-astro-cid-4yr5atew]{color:var(--red)}.hero[data-astro-cid-7xzskqga]{padding:100px 0 70px;max-width:950px}h1[data-astro-cid-7xzskqga]{margin:16px 0;font-size:clamp(52px,9vw,126px);line-height:.9;letter-spacing:-.07em}h1[data-astro-cid-7xzskqga] em{font:400 .9em Georgia,serif;color:var(--red)}.intro[data-astro-cid-7xzskqga] p{max-width:680px;margin:0;color:var(--muted);font-size:clamp(20px,20px,20px)}@media(max-width:800px){.hero[data-astro-cid-7xzskqga]{padding:65px 0 45px}}@media(max-width:560px){h1[data-astro-cid-7xzskqga]{font-size:clamp(56px,56px,56px)}.intro[data-astro-cid-7xzskqga] p{font-size:clamp(17px,17px,17px)}}
|
||||
</style></head> <body> <header class="top" id="top" data-astro-cid-xattfbdu> <div class="cell" data-astro-cid-xattfbdu><a href="/ai-for-dummies/summary/">← ROUTE MAP</a></div> <div class="cell" data-astro-cid-xattfbdu><span>03 / SKILLS</span></div> <div class="cell" data-astro-cid-xattfbdu><a href="/ai-for-dummies/skills-review/">review desk ↗</a></div> </header> <main> <section class="hero" data-astro-cid-7xzskqga> <p data-astro-cid-4yr5atew="true" class="eyebrow tone-red">Reusable judgment</p> <h1 data-astro-cid-7xzskqga><span>Teach the<br><em>decision.</em></span></h1> <div class="intro" data-astro-cid-7xzskqga> <p>A skill changes behavior. Keep the trigger precise, put the workflow in <code>SKILL.md</code>, and move conditional facts, scripts, and examples into focused files.</p> </div> </section> <section class="pipeline package-anatomy"> <div> <p class="eyebrow">Package anatomy</p> <h2>One job.<br>More than<br>one <em>file.</em></h2> <p class="package-hint">Choose a file to see why it belongs in the package.</p> </div> <div class="package-workbench" data-package-workbench data-astro-cid-xk5n4466> <div class="package-tree" role="tablist" aria-label="Files in the review-ui skill package" data-astro-cid-xk5n4466> <p data-astro-cid-xk5n4466>REVIEW-UI / SKILL PACKAGE</p> <button class="active" data-skill-file="skill" role="tab" aria-selected="true" data-astro-cid-xk5n4466> <code data-astro-cid-xk5n4466>├── SKILL.md</code> <small data-astro-cid-xk5n4466>trigger + workflow</small> </button><button data-skill-file="references" role="tab" aria-selected="false" data-astro-cid-xk5n4466> <code data-astro-cid-xk5n4466>├── references/</code> <small data-astro-cid-xk5n4466>conditional facts</small> </button><button data-skill-file="scripts" role="tab" aria-selected="false" data-astro-cid-xk5n4466> <code data-astro-cid-xk5n4466>├── scripts/</code> <small data-astro-cid-xk5n4466>deterministic checks</small> </button><button data-skill-file="assets" role="tab" aria-selected="false" data-astro-cid-xk5n4466> <code data-astro-cid-xk5n4466>└── assets/</code> <small data-astro-cid-xk5n4466>templates + examples</small> </button> </div> <article class="package-preview" id="package-preview" aria-live="polite" data-astro-cid-xk5n4466></article> </div> <script type="application/json" data-skill-files>[{"id":"skill","prefix":"├── ","label":"SKILL.md","caption":"trigger + workflow","title":"The operating contract","body":"The one file that should always be loaded. Define the exact trigger, the ordered workflow, safety limits, and the evidence the agent returns.","code":"---\nname: review-ui\ndescription: Review a changed UI for focus, reflow, and motion.\n---\n\n1. Inspect the changed interaction.\n2. Run the UI checks.\n3. Return findings with evidence."},{"id":"references","prefix":"├── ","label":"references/","caption":"conditional facts","title":"Facts, only when needed","body":"Keep conditional detail out of the main instruction. A dialog pattern, framework caveat, or accessibility checklist belongs here when it is not needed for every review.","code":"references/\n└── accessibility.md\n ├── keyboard interaction patterns\n └── focus and reflow checklist"},{"id":"scripts","prefix":"├── ","label":"scripts/","caption":"deterministic checks","title":"Mechanics that should not depend on memory","body":"Turn deterministic checks into runnable tools. The agent still judges the result, but it should not have to recreate a viewport test or filename rule by hand.","code":"scripts/\n└── check-reflow.mjs\n └── checks 320px, 1280px, and 4K widths"},{"id":"assets","prefix":"└── ","label":"assets/","caption":"templates + examples","title":"Starting material, not hidden instructions","body":"Use assets for templates and examples a person or agent can copy. Keep them clearly named so package readers can choose the right starting point.","code":"assets/\n├── review-report.md\n└── focus-test-fixture.html"}]</script> <script>
|
||||
(function () {
|
||||
const preview = document.querySelector('#package-preview');
|
||||
const buttons = document.querySelectorAll('[data-skill-file]');
|
||||
const dataNode = document.querySelector('[data-skill-files]');
|
||||
if (!preview || !dataNode) return;
|
||||
const files = JSON.parse(dataNode.textContent || '[]');
|
||||
|
||||
function renderPackage(id) {
|
||||
const item = files.find((entry) => entry.id === id);
|
||||
if (!item) return;
|
||||
preview.classList.remove('is-swapping');
|
||||
void preview.offsetWidth;
|
||||
preview.classList.add('is-swapping');
|
||||
preview.innerHTML =
|
||||
'<span>SELECTED / ' +
|
||||
item.label +
|
||||
'</span>' +
|
||||
'<h3>' +
|
||||
item.title +
|
||||
'</h3>' +
|
||||
'<p>' +
|
||||
item.body +
|
||||
'</p>' +
|
||||
'<pre><code>' +
|
||||
item.code +
|
||||
'</code></pre>';
|
||||
buttons.forEach(function (button) {
|
||||
const active = button.dataset.skillFile === id;
|
||||
button.classList.toggle('active', active);
|
||||
button.setAttribute('aria-selected', String(active));
|
||||
});
|
||||
}
|
||||
|
||||
buttons.forEach(function (button) {
|
||||
button.addEventListener('click', function () {
|
||||
renderPackage(button.dataset.skillFile);
|
||||
});
|
||||
});
|
||||
|
||||
renderPackage('skill');
|
||||
})();
|
||||
</script> </section> <section class="practice"> <div> <p class="eyebrow">Create a skill</p> <h2>Observe →<br>trigger →<br>validate</h2> </div> <div class="steps"> <article> <b>01</b> <div> <strong>Observe friction</strong> <span>Find a repeated decision or failure.</span> </div> </article><article> <b>02</b> <div> <strong>Define the trigger</strong> <span>Say when it should load and when it should stay out.</span> </div> </article><article> <b>03</b> <div> <strong>Choose anatomy</strong> <span>Use references for facts and scripts for deterministic mechanics.</span> </div> </article><article> <b>04</b> <div> <strong>Evaluate behavior</strong> <span>Test realistic prompts, edge cases, safety, and evidence.</span> </div> </article> </div> </section> </main> <section class="footer" data-astro-cid-bmvnf73n> <nav class="links" aria-label="Chapter navigation" data-astro-cid-bmvnf73n> <nav class="links" aria-label="Chapter navigation"> <a href="/ai-for-dummies/agents/">Agents & trees →</a> <a href="/ai-for-dummies/rules/">Rules case study →</a> <a href="/ai-for-dummies/skills-review/">Review submitted skills →</a> <a href="/ai-for-dummies/full-guide/#create-skill">Full guide: skill forge →</a> </nav> </nav> <div class="text" data-astro-cid-bmvnf73n> </div> </section> </body></html>
|
||||
@@ -1,18 +0,0 @@
|
||||
---
|
||||
name: rules-case-study
|
||||
description: Use when explaining how a repository turns agent guidance into enforceable behavior across context files, skills, CLI checks, Git hooks, CI, worktrees, or PR review; build a concise, source-linked case-study page.
|
||||
---
|
||||
|
||||
# Rules case study
|
||||
|
||||
Show the control loop: context → skills → CLI → commit → review. The reader should see where a rule lives, what executes it, and how to verify it.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Inspect authoritative files before writing copy. Start with the repository context file, skill directory, command or database ledger, enforcement scripts, hooks, staged-file config, CI, and review policy. Use [the interview source map](references/interview-source-map.md) as a routing hint, then confirm paths in the target repository.
|
||||
2. Separate guidance from enforcement. A context file or skill teaches an agent; a CLI check, hook, CI job, or reviewer blocks or reports behavior. Never describe prose as mechanically enforced.
|
||||
3. For every example, show the rule, exact source path, enforcement point, verification command, and remaining gap. Prefer one concrete ratchet or hook example over a list of vague best practices.
|
||||
4. Add a skills shelf. Each skill needs a trigger, the lesson it carries, a tiny example, and a source link. Keep examples short enough to copy into an agent prompt.
|
||||
5. Include a read-only exploration prompt that asks an agent to map rules to evidence and gaps. Add copy feedback and bilingual labels if the host guide supports both languages.
|
||||
6. Use a dependency-free standalone page when the case study is mostly explanatory. Link back to the main guide and exact source files. Do not modify the source repository merely to document it.
|
||||
7. Verify dynamic stage and skill states, source links, copy behavior, language switching, no horizontal overflow, and the 390px/1920px/3840px viewports. The page is done when every claim has a source or is clearly labeled as a design recommendation.
|
||||
@@ -1,10 +0,0 @@
|
||||
[
|
||||
{
|
||||
"prompt": "Explain a repository's AGENTS.md, reusable skills, UI ratchet script, Husky hooks, and PR review config as one teachable page.",
|
||||
"expected_behavior": "Build a context → skills → CLI → commit → review pipeline; link every claim to an exact source path; distinguish guidance from enforcement; include a short read-only exploration prompt."
|
||||
},
|
||||
{
|
||||
"prompt": "A skill says all pages need an h1 and a pre-commit script checks it. How should the case study describe that relationship?",
|
||||
"expected_behavior": "Describe the skill/context as guidance and the script/hook as executable enforcement, then show the verification command and any gap between local hooks and CI."
|
||||
}
|
||||
]
|
||||
@@ -1,18 +0,0 @@
|
||||
# Interview source map
|
||||
|
||||
This map records the implementation inspected for the rules case study. Reconfirm paths when the source repository changes.
|
||||
|
||||
| Concern | Source | Role |
|
||||
| --- | --- | --- |
|
||||
| Shared context | `AGENTS.md` | Stack, commands, product shape, conventions, and verification expectations. |
|
||||
| Reusable procedures | `.agents/skills/` | Focused workflows such as gates, frontend, Go API, repo DB, and skill writing. |
|
||||
| Machine-readable routing | `.agents/db/commands.json` | Canonical checks and code-generation commands. |
|
||||
| UI enforcement | `scripts/check-ui-contract.mjs` | Ratchet for buttons, catches, headings, colors, and duplicate components. |
|
||||
| Ratchet state | `scripts/ui-contract-baseline.json` | Baseline counts that new violations cannot exceed. |
|
||||
| Commit boundary | `.husky/pre-commit` | Runs lint-staged and the UI contract check. |
|
||||
| Commit message boundary | `.husky/commit-msg` | Runs commitlint. |
|
||||
| Staged-file tools | `.lintstagedrc.cjs` | Biome, ESLint, Prettier, and Buf formatting by file type. |
|
||||
| Independent review | `.pr-review.json` | Review focus, exclusions, security constraints, and test expectations. |
|
||||
| Agent roles | `.claude/agents/` | Prior-art scout, scoped implementer, and verifier responsibilities. |
|
||||
|
||||
The source of truth is the repository. This table is a teaching map, not a replacement for reading the files.
|
||||
@@ -1,25 +0,0 @@
|
||||
---
|
||||
name: skill-reviewer
|
||||
description: Review an Agent Skill package and produce a kind, evidence-backed improvement brief. Use when assessing a SKILL.md, its trigger, instructions, scripts, references, safety, or evaluation readiness; do not rewrite the package unless asked.
|
||||
---
|
||||
|
||||
# Skill reviewer
|
||||
|
||||
Review the submitted package before proposing changes. Preserve the author's intent: this is a constructive assessment, not a replacement of their domain expertise.
|
||||
|
||||
## Review flow
|
||||
|
||||
1. Read `SKILL.md` and list bundled files. Check frontmatter validity, package-name alignment, and whether the description says both what the skill does and when it applies.
|
||||
2. Identify the narrow job, the expected inputs, safe boundaries, a default workflow, and observable output. Mark any claim you cannot verify as a question, not a defect.
|
||||
3. Recommend only additions that change execution: a small RULES section for real invariants, a script for repeated fragile work, a reference for conditional detail, or eval cases for behavior that matters.
|
||||
4. Flag secrets, destructive actions, network calls, and unclear approval boundaries prominently. Never copy credentials into review artifacts.
|
||||
5. Return a friendly brief with: what already works, highest-value improvements, suggested package layout, and a small set of realistic test prompts.
|
||||
|
||||
## Quality bar
|
||||
|
||||
- Prefer precise activation language over broad phrases such as "use for code."
|
||||
- Keep the main instructions lean; send conditional or lengthy material to `references/` and explain exactly when to read it.
|
||||
- Favor evidence and defaults over generic rules or tool menus.
|
||||
- Recommend scripts only when they remove repeated, error-prone mechanics; document prerequisites and use relative paths.
|
||||
|
||||
Read [the review rubric](references/review-rubric.md) when scoring a package.
|
||||
@@ -1,7 +0,0 @@
|
||||
# Review rubric
|
||||
|
||||
Assess six dimensions: discoverability, scope, procedure, safety, resources, and proof.
|
||||
|
||||
For each finding, state the observed evidence, the practical consequence, and the smallest helpful change. Do not call missing files a problem unless the workflow genuinely needs them. A strong review explains why the recommendation belongs in the skill rather than in general agent behavior.
|
||||
|
||||
Test prompts should include one normal request and one boundary case. Assertions should be observable, such as valid JSON, an explicit approval request before mutation, or a report containing file locations.
|
||||
@@ -1,19 +0,0 @@
|
||||
---
|
||||
name: skill-rewriter
|
||||
description: Rewrite an existing Agent Skill into a concise, safer, and more discoverable package while preserving its intended capability. Use after a skill review or when the user asks to improve a SKILL.md; do not alter original submissions in place without explicit approval.
|
||||
---
|
||||
|
||||
# Skill rewriter
|
||||
|
||||
Create a separate revised package so the author can compare it with the original. Retain domain-specific facts that are supported by the source; replace generic filler with decisions the agent would otherwise miss.
|
||||
|
||||
## Rewrite flow
|
||||
|
||||
1. Read the original package and any review brief. Keep its intended job and remove only unsupported assumptions, unsafe commands, or instructions that conflict with the requested boundary.
|
||||
2. Write valid frontmatter: a lowercase hyphenated name matching the folder and a description that states capability plus trigger terms.
|
||||
3. Use a short, friendly structure: Purpose, When to use, Inputs, Workflow, Rules, Output, and Verification. Omit headings that add no decision-making value.
|
||||
4. Move conditional detail to `references/`; add a script only for deterministic repeated work and name its prerequisites. Use paths relative to the skill root.
|
||||
5. Add concrete safety gates for mutation, credentials, and external systems. Never preserve a secret in the rewritten package.
|
||||
6. Validate the new package and give the author an end-to-end explanation of the changes and one next evaluation step.
|
||||
|
||||
Read [the rewrite checklist](references/rewrite-checklist.md) for final checks.
|
||||
@@ -1,10 +0,0 @@
|
||||
# Rewrite checklist
|
||||
|
||||
- `name` is lowercase, hyphenated, and matches the folder.
|
||||
- `description` says what the skill does and when to use it.
|
||||
- The default workflow has clear inputs and a concrete result.
|
||||
- Important limits have a reason; rules are not generic boilerplate.
|
||||
- Bundled resources are linked from `SKILL.md` and loaded only when needed.
|
||||
- Commands use relative paths and document prerequisites.
|
||||
- Mutations require an explicit user approval at the moment they occur.
|
||||
- The package has one normal and one boundary-case evaluation prompt.
|
||||
@@ -1 +0,0 @@
|
||||
.top > *{min-width:0}.top a{overflow-wrap:anywhere}.package-hint{max-width:27ch;color:var(--muted)}.package-workbench{display:grid;grid-template-columns:minmax(190px,.85fr) minmax(0,1.3fr);min-width:0;background:var(--ink);border:1px solid var(--ink);box-shadow:10px 10px 0 color-mix(in srgb,var(--gold) 55%,transparent)}.package-tree{padding:22px 16px;border-right:1px solid #426070;min-width:0}.package-tree>p,.package-preview>span{margin:0 0 14px;color:var(--gold);font:700 11px/1.35 ui-monospace,monospace;letter-spacing:.1em}.package-tree button{display:grid;grid-template-columns:minmax(0,1fr) auto;align-items:center;gap:8px;width:100%;padding:12px 8px;border:0;border-left:2px solid transparent;background:transparent;color:#d6e1e4;text-align:left;cursor:pointer;transition:background .2s ease,border-color .2s ease,transform .2s ease}.package-tree button:hover,.package-tree button:focus-visible,.package-tree button.active{border-left-color:var(--gold);background:#1f3a4b;outline:0}.package-tree button:hover{transform:translateX(3px)}.package-tree code{min-width:0;overflow-wrap:anywhere;font:700 13px/1.4 ui-monospace,monospace}.package-tree small{color:#aebfc7;font:11px/1.25 Arial,sans-serif;text-align:right}.package-preview{min-width:0;padding:26px;background:#173245;color:var(--paper)}.package-preview h3{margin:0 0 8px;font-size:clamp(24px,3vw,38px);line-height:1.02;letter-spacing:-.045em}.package-preview p{max-width:52ch;margin:0;color:#d6e1e4}.package-preview pre{max-width:100%;margin:20px 0 0;padding:15px;overflow:auto;border:1px solid #466274;background:#102837;color:#d6e1e4;font:12px/1.55 ui-monospace,monospace}.package-preview.is-swapping{animation:package-preview-in .34s ease both}@keyframes package-preview-in{from{opacity:.25;transform:translateY(7px)}to{opacity:1;transform:translateY(0)}}.links a{transition:background .2s ease,color .2s ease,transform .2s ease}.links a:hover{transform:translateY(-2px)}@media(max-width:800px){.package-workbench{grid-template-columns:1fr}.package-tree{border-right:0;border-bottom:1px solid #426070}.package-preview{padding:22px}}@media(max-width:520px){.top{gap:12px}.top a{font-size:10px}.package-tree{padding:18px 10px}.package-tree button{padding:12px 6px}.package-tree small{display:none}.package-preview{padding:18px}.package-preview pre{font-size:11px}}@media(prefers-reduced-motion:reduce){*,*::before,*::after{scroll-behavior:auto!important;animation-duration:.01ms!important;animation-iteration-count:1!important;transition-duration:.01ms!important}}
|
||||
Reference in New Issue
Block a user