skilldrop-cli 0.16.12 → 0.16.14

package/packs/research/skills/source-synthesis/SKILL.md

@@ -1,115 +1,112 @@
 ---
 name: source-synthesis
-description: Synthesise a set of supplied sources — papers, articles, reports, interview transcripts — into findings where every claim is cited to a source and a location ([S1:p4]), agreement and disagreement across sources are explicit, each finding carries an evidence-strength rating with the criteria used, and the gaps and what the sources do not say are listed. Never adds outside facts unless tagged as such, and ships a citation checker. Use when the user hands over several sources and asks to "synthesise these", "what do these papers say", "literature review", "pull the findings together", or "where do the sources agree and disagree".
+description: Answer a question from a set of sources the user supplied — papers, reports, articles, interview notes, emails — saying only what the material supports, labelling anything that comes from elsewhere where it appears, counting a source that repeats another once, and giving a labelled estimate when the user needs a figure the sources don't settle. Written in the length and format the user asked for; a full cited literature review only when that is the ask. Use when the user hands over several sources and asks to "synthesise these", "what do these papers say", "pull together what we know", "literature review", or "where do the sources agree and disagree".
 ---
 
 # source-synthesis
 
-You turn a pile of sources the user supplied into findings they can rely on and check. Every
-claim points to a source and a place in it, so a reader can verify it in under a minute.
-Where sources agree, you say how many and which; where they disagree, you show both sides and
-why they might differ. You add nothing from your own knowledge unless it is tagged
-`[outside]`. The synthesis is only as good as its sources, so each finding says how strong its
-evidence is and on what criteria.
+**The rule: say only what the material supports, and mark everything else where it appears.**
+The user handed over sources because they want to know what *those* say. A plausible fact from
+memory, a rule you happen to know about, a price range that sounds right: each one
+reads exactly like a finding, and the user can't tell it apart. The agent's habit is to fill
+gaps helpfully. This skill's job is to keep the line between "the sources say" and "I'm adding"
+visible in every sentence.
 
-What to research and where to look comes first, from `research-plan`. If the findings point to
-several rival explanations, rank them with `hypothesis-comparison`. To turn messy material into
-a brief for another skill rather than findings, use `brief-intake`.
+Two things follow from the rule:
+
+- **A source that repeats another is one source.** An article quoting a survey's figure, an
+  email forwarding a report, three people retelling the same story: trace each figure to where
+  it started and count that origin once. Agreement between echoes is not agreement.
+- **Hearsay and half-memories are reported as what they are.** "A neighbour said it was about half
+  price" is something someone said, not a data point, and an undated clipping is undated.
 
 ## How to respond
 
-**Four rules come before the steps and outrank them:**
-
-- **Answer what was asked, first.** Open with the answer, the decision or the artifact, in plain words. Scores, matrices, frameworks and tags come after it, and anything that doesn't change the answer is cut.
-- **Use only what you were given.** Don't add facts, names, numbers, incidents, history, steps or sections the input doesn't contain. What you need and don't have is left out of the artifact and listed once at the end under "To confirm".
-- **Deliver from what you have.** When the request gives you something to work on, state your assumptions in a line and produce the result. When it gives you nothing to work on, ask for it in one or two plain sentences and say what you will do once you have it.
-- **Write for someone who has never heard of this skill.** No skill names, no paths or scripts from this folder, no internal terms, and nothing about how the run was set up. A next step is one plain sentence at the end that describes the work.
-- **For this skill:** The reply itself carries the answer: the recommendation, the numbers behind it and the caveats. Saved files are extra. Don't report that your own checks passed.
-
-1. **Ask once for what's missing.** You need the **sources** themselves (text, files or
-   excerpts, not titles) and the **question** the synthesis answers. If the user has a
-   research plan, take the question and sub-questions from it. Ask for both in one message.
-   If the user sends only titles or links you can't open, ask for the text. Don't summarise a
-   paper from memory.
-
-2. **Register the sources.** Give each one an id (`S1`, `S2`, …) and one line: author or owner,
-   title, date, type (peer-reviewed study, survey, internal report, news article, interview,
-   opinion piece), and for studies the method and sample size if the source states them. Note
-   how location works in each: page numbers, section numbers, or timestamps for transcripts.
-   Mark sources that aren't independent (two articles reporting the same survey count as one
-   line of evidence).
-
-3. **Extract claims before you synthesise.** For each source, list the claims that bear on the
-   question, each with its location, in the source's own terms. Keep the source's hedges:
-   "associated with" stays "associated with", not "causes". Quote the key sentence when the
-   wording matters.
-
-4. **Group claims into findings, one per sub-question or theme.** For each finding:
-   - **State it in one sentence,** worded no stronger than its weakest supporting source.
-   - **Cite every source that supports it,** with locations: `[S1:p4; S3:§2.1]`.
-   - **Show agreement and disagreement:** "S1, S3 and S4 agree; S2 disagrees", and give the
-     likely reason for the disagreement when the sources show one (different population,
-     period, definition or method). Don't average conflicting results into a middle answer.
-   - **Rate the evidence strength** (strong / moderate / limited / conflicting) and say which
-     criteria drove it: independent sources, source type, method, sample size, recency,
-     directness. Criteria are in [`reference.md`](reference.md).
-
-5. **List the gaps and what the sources don't say.** Sub-questions no source answers;
-   populations, periods or regions no source covers; claims everyone repeats but nobody tests;
-   and the question the user is likely to ask next that these sources can't answer. Write
-   these as statements: ✅ *"None of the sources measures effects beyond 12 months."*
-
-6. **Tag anything from outside.** If context the sources don't give is genuinely needed (a
-   definition, a well-known date), add it with `[outside]` so the reader knows to check it.
-   Keep it rare. Never use `[outside]` to fill a gap in the findings; list the gap instead.
-
-7. **Write it up with [`templates/synthesis.md`](templates/synthesis.md):** the question, the
-   source register, the bottom line in three sentences or fewer, findings with citations and
-   strength, the agreement and disagreement table, gaps, what the sources do not say, and the
-   `[outside]` list.
-
-8. **Check every citation.** Save the draft and run:
-
-   ```bash
-   # Claude Code
-   python3 "${CLAUDE_SKILL_DIR}/scripts/citations.py" synthesis.md -o citation-check.md
-   # Other IDEs (from the skill folder)
-   python3 scripts/citations.py synthesis.md -o citation-check.md
-   ```
-
-   It reads the `## Sources` section of the draft (or a separate file with `--sources`), and
-   reports citations that don't resolve, malformed citations, paragraphs and table rows with no
-   citation, citations with no location, sources never cited, and every `[outside]` claim. Fix
-   every error, and either fix or explain each warning. A source never cited is a question:
-   did it say nothing relevant, or did you miss it? Say which in the source register.
-
-**Non-interactive runs** (subagent, CI, headless): with no source text, emit
-`BLOCKED: need the sources' text, not titles or links`. A missing question becomes
-`[assumption] The question is: …`, inferred from the sources and stated at the top.
-
-## Useful references in this skill
-
-- [`reference.md`](reference.md) — citation format, evidence-strength criteria, how to handle disagreement, independence, and common distortions
-- [`templates/synthesis.md`](templates/synthesis.md) — the synthesis skeleton
-- [`scripts/citations.py`](scripts/citations.py) — checks that every citation resolves and every claim is cited (stdlib only)
-- [`examples/four-day-week.md`](examples/four-day-week.md) — worked example: four sources on a four-day-week pilot, the synthesis, and the checker's real output on a first draft and the fixed draft
+1. **Answer the question first, in the user's terms.** The opening lines say what the material
+   supports on the question they asked, organised around the decision in front of them (the
+   options on the table, the yes/no, the number they need). Not source by source.
+
+2. **Fit the size and format they asked for.** "Half a page", "a few bullets for the meeting",
+   "two pages for the board pack", a chat answer: that is the format. Name sources in plain
+   words where a claim comes from them ("the pilot report", "the team lead's interview",
+   "the manager survey"), so a reader can check it. Use bracketed citations with locations, a source
+   register or strength ratings only when the user asked for a literature review or an
+   evidence summary with citations (see **A cited literature review** below).
+
+3. **Check the sources before you trust them.**
+   - Add up every total, percentage and per-unit figure a source gives from its own parts, and
+     say plainly when one doesn't match ("the report says 60 staff took part; its team table adds
+     to 54").
+   - Where sources disagree on a number, show both, and give the reason they might differ when
+     the sources show one: a different population, period, size or definition. Say which one
+     fits the user's situation better and why. Don't average them.
+   - Keep each source's hedges. "Associated with" stays "associated with"; "about a third"
+     stays approximate, and a change that happened alongside another change is not put down to
+     either one.
+
+4. **When they need a figure the sources don't settle, estimate it and label it.** A cost, a
+   break-even point, a likely uptake: work it out from what the sources give, show the
+   sum, and give the range the uncertain inputs produce. If an input has to come from outside
+   the material, write it into the sentence as yours ("assuming 21 working days a month,
+   which none of the sources gives"), never as a finding. End with the one or
+   two facts that would settle it. "The sources can't say" on its own is not an answer.
+
+5. **Say what the material doesn't cover, once, briefly.** The gaps that matter for the
+   decision, as plain statements at the end: ✅ *"None of the sources measures effects beyond
+   six months."* Not a list of everything a perfect study
+   would have measured.
+
+6. **Deliver from what you have.** If you have the sources' text and the question, write the
+   answer, stating in one line any assumption about what they want. Ask first only when there
+   is nothing to work from: titles or links you can't open, or no sources at all. Then ask for
+   the text in one or two plain sentences. Don't summarise a paper from its title or from
+   memory.
+
+7. **Keep the machinery out of the reply.** No skill names, no paths or scripts, no "checks
+   passed", no notes about how the run was set up. The reply carries the answer. A file is
+   saved only when the user asked for one, and it is the answer itself, nothing beside it.
+
+## A cited literature review
+
+When the user asks for a literature review, an evidence summary with citations, or findings
+"every claim cited", produce the full form: a source register, findings grouped by theme with
+`[S1:p4]` citations to a location, agreement and disagreement named source by source, an
+evidence-strength rating with its criteria, and the gaps. Citation format, strength criteria
+and how to handle disagreement are in [`reference.md`](reference.md); the skeleton is
+[`templates/synthesis.md`](templates/synthesis.md); a worked example is
+[`examples/four-day-week.md`](examples/four-day-week.md).
+
+Before you hand it over, run the citation checker on the saved draft and fix what it reports:
+
+```bash
+# Claude Code
+python3 "${CLAUDE_SKILL_DIR}/scripts/citations.py" synthesis.md
+# Other IDEs (from the skill folder)
+python3 scripts/citations.py synthesis.md
+```
+
+It reports citations that don't resolve, claims with no citation, citations with no location
+and sources never cited. It is your check, not part of the deliverable: don't save its report
+for the user or mention that it passed.
 
 ## Quality bar
 
-- **Every claim is cited to a source and a location.** The checker reports no errors; any warning left is explained.
-- **Nothing comes from outside the sources** unless it is tagged `[outside]`, and gaps are never filled from memory.
-- **Agreement and disagreement are explicit,** with the sources named on each side and a likely reason for the split where the sources show one.
-- **Each finding has a strength rating and the criteria behind it.** A finding from one survey never reads like one from three independent studies.
-- **Findings are no stronger than their sources.** Hedges survive; correlation stays correlation.
-- **Gaps and what the sources do not say are listed** as specific statements.
-- **Sources that aren't independent are counted once.**
+- **Nothing reads as coming from the sources that doesn't.** Every outside input is marked as
+  outside in the sentence where it appears; no gap is filled from memory.
+- **Echoes are counted once.** A figure repeated by a second source is traced to its origin.
+- **The sources' own sums are checked,** and any that don't add up are named.
+- **The answer opens the reply and fits the requested size and format.**
+- **A needed figure gets a worked, labelled estimate** with its range and what would settle it,
+  not a refusal.
+- **Findings are no stronger than their sources.** Hedges, approximations and confounds
+  survive; hearsay stays hearsay.
 
 ## When to use this skill
 
+- ✅ "Here's everything I've collected — what do we actually know?"
 - ✅ "Synthesise these six papers / reports / articles on X"
-- ✅ Turning a set of interview transcripts into cited themes
+- ✅ Turning interview notes or transcripts into what they show, with the disagreements kept
 - ✅ A literature review or evidence summary for a decision
-- ✅ Checking where a set of analyst reports agree and where they don't
 
 ## When NOT to use this skill
 
@@ -122,10 +119,16 @@ a brief for another skill rather than findings, use `brief-intake`.
 
 ## Anti-patterns to avoid
 
-- ❌ **Source-by-source summaries.** "S1 says…, S2 says…" is an annotated list, not a synthesis. Organise by finding.
-- ❌ **A citation with no location.** `[S2]` on a 60-page report can't be checked.
-- ❌ **Smoothing over conflict.** "Results were mixed" hides which sources disagree and why.
+- ❌ **The helpful outside fact.** A regulation's threshold, a typical salary, an industry
+  norm, written as if a source said it. Label it in the sentence, or leave it out.
+- ❌ **Counting echoes.** "Two sources agree on 63%" when the second one is quoting the first.
+- ❌ **Stopping at "the sources can't say".** The user asked a practical question; show the
+  sum with labelled assumptions and what would settle it.
+- ❌ **A research report for a meeting note.** Source registers, strength tables and
+  bracketed citations on a request for five bullets.
+- ❌ **Source-by-source summaries.** "S1 says…, S2 says…" is a list, not an answer. Organise by
+  the decision.
+- ❌ **Taking a source's total on trust.** Add it up.
 - ❌ **Promoting hedges.** "May be associated with" becomes "drives" by the second paragraph.
-- ❌ **Counting echoes.** Three news stories about one study are one source.
-- ❌ **Filling gaps from memory.** A plausible fact with no source is the error this skill exists to prevent.
-- ❌ **Citing a title you haven't read.** If you only have the abstract, say so in the register and rate accordingly.
+- ❌ **Machinery in the reply.** "Citations all pass", file names of working drafts, the
+  skill's own vocabulary.

package/packs/research/skills/source-synthesis/evals/evals.json

@@ -74,6 +74,34 @@
         "It gives the up-front gap as about £10,100 (£14,200 against about £4,100)",
         "It does not add energy prices, grant scheme rules or typical heat pump costs from outside the notes, unless clearly labelled as not coming from the notes"
       ]
+    },
+    {
+      "id": 6,
+      "held_out": "2026-10-17",
+      "prompt": "I'm the practice manager at Brackenmoor Veterinary Practice. We have three vets. The partners decide on Thursday whether to start opening on Saturday mornings, and they've asked me one question: would a Saturday morning clinic cover its own staffing cost in its first year? I've put five things in this folder: client-survey-summary.md, wcapa-benchmarking-extract.md, practice-ledger-article.md, fenwick-lane-call-notes.txt and finance-email.txt. Go by what these say. The partners want a straight answer and a number they can argue about, not a literature review, so keep it to one page at most. I'm in theatre all day and can't answer questions, so just write it up.",
+      "assertions": [
+        "It answers the question directly: on the evidence in the files, a Saturday clinic probably would not cover its staffing cost across the first year, because the 14-a-session benchmark clears the break-even but the closer comparison (Fenwick Lane, 4 vets) ran at 8 to 9 a session for six months and only reached about 12 by month ten",
+        "It works out a break-even of roughly 11 to 12 appointments a session from the finance email (£640 to £680 a session divided by £58 contribution per appointment), or an equivalent comparison of contribution against cost",
+        "It treats the Practice Ledger's 14-a-session figure as a repeat of the WCAPA report, not as a second source confirming it",
+        "It points out that the WCAPA figure and Fenwick Lane's figures disagree and gives a reason to weigh them differently, such as the WCAPA practices being larger (median 7 vets, with larger practices reporting higher numbers) than Brackenmoor",
+        "It flags that the finance email's £680 a session does not match its own line items, which add up to £640, rather than silently using one of the two",
+        "Any first-year figure the files do not give directly is labelled as an estimate, and it says what would settle the question, such as finding out whether Saturday bookings would be new visits or moved from weekdays, which neither the survey nor Fenwick Lane measured",
+        "It does not invent figures that are not in the files, such as a share of Saturday visits moved from weekdays, a ratio of survey intent to actual bookings, or Saturday pay rates, and it fits on about one page without stopping to ask questions"
+      ]
+    },
+    {
+      "id": 7,
+      "held_out": "2026-10-17",
+      "prompt": "I'm secretary of the Hollins Green Amateur Dramatic Society, which is a fancy name for twenty-odd of us who put on a panto every January. The committee wants to know if we should move it from St Aldric's church hall to the primary school hall, because someone thinks we'd sell more tickets. I'm not a numbers person and this is all I've got, scribbled down:\n\n1. Bev from the Oakhurst Players told me at the summer fete they moved to their school hall and \"sold out every night\". I think she said 180 seats? Might have been 150.\n\n2. A clipping from the Linden Vale Gazette, no date on it, Mum cut it out ages ago: \"Linden Vale Players' panto raises £2,300 for hall roof fund ... an audience of nearly 600 across four nights.\"\n\n3. Chatted to Mr Pruett, the school caretaker. He said the hall seats 220 \"with the stage in\" but the fire officer's limit might be lower, he wasn't sure. Hire is £45 an hour. Or was it £45 a session? I didn't write it down properly.\n\n4. Our own panto last January at St Aldric's: three nights, roughly 110 a night I think, tickets £8. I'm fairly sure we turned people away on the Saturday.\n\nCould you give me a few bullet points I can read out at Tuesday's committee meeting? Five or six at most, please, nothing long.",
+      "assertions": [
+        "It does not give a firm yes: it says the notes cannot show whether moving would sell more tickets, and that the best evidence for extra demand is the society's own report of turning people away on the Saturday",
+        "It names the things to check before deciding, including the school hall's actual permitted capacity (220 or the possibly lower fire limit) and whether the £45 is per hour or per session",
+        "It treats Bev's \"sold out every night\" and the 150-or-180 seat figure as second-hand and uncertain, not as established fact",
+        "It does not use the undated Linden Vale clipping as evidence that moving venue raises sales, since the clipping says nothing about a venue change or when it happened",
+        "Any figure it gives for extra tickets, takings or hire cost is clearly labelled as a rough estimate and, for hire cost, shows that it depends on whether the £45 is per hour or per session",
+        "It does not invent facts that are not in the notes, such as fire regulations, typical panto audiences, or details about the Oakhurst or Linden Vale groups beyond what is written",
+        "It stays within six bullet points, short enough to read out, and delivers them without stopping to ask questions first"
+      ]
     }
   ]
 }

package/packs/research/skills/source-synthesis/evals/files/6/client-survey-summary.md

@@ -0,0 +1,15 @@
+# Brackenmoor Veterinary Practice: client survey on opening hours
+
+Run by reception, March 2026. Emailed to 2,950 active clients; 412 replied (14%).
+
+**Question: "If we offered appointments on Saturday mornings (9am to 1pm), would you use them?"**
+
+| Answer | Share of replies |
+|---|---|
+| Definitely | 38% |
+| Probably | 27% |
+| Unlikely or no | 35% |
+
+Free-text comments mostly mentioned work hours ("I can never get there before 6") and vaccination boosters.
+
+Note from reception: we did not ask whether people would use a Saturday slot instead of a weekday visit or as well as one, or how often they would come. The survey went to clients with an email address on file, so older clients are probably under-represented.

package/packs/research/skills/source-synthesis/evals/files/6/fenwick-lane-call-notes.txt

@@ -0,0 +1,10 @@
+Call with Tom Ashdown, practice manager, Fenwick Lane Vets (4 vets, edge of town, about 20 min from us)
+My notes, 9 Oct 2026
+
+- They started Saturday mornings 9-1 about eleven months ago.
+- First six months were slow: "eight or nine appointments a session, some weeks fewer".
+- Picked up after that. By month ten they were at about twelve a session. Now month eleven, similar.
+- Staffing cost per Saturday about £740. That includes paying a locum vet at a premium, because their own vets would not cover weekends at first.
+- He thinks it will pay for itself in year two but "not this year, honestly".
+- Most Saturday bookings are vaccinations and minor stuff, not surgery.
+- He said he hasn't looked at whether Saturday clients are new or people who'd have come in on a weekday anyway.

package/packs/research/skills/source-synthesis/evals/files/6/finance-email.txt

@@ -0,0 +1,21 @@
+From: Dana Whitcombe (Finance Lead, Brackenmoor Veterinary Practice)
+To: Practice Manager
+Subject: Re: Saturday numbers
+Date: 13 Oct 2026
+
+Hi,
+
+Quick numbers for the Saturday question.
+
+Average contribution per appointment, after drugs and consumables, comes out at £58 on last year's figures. That's across all appointment types.
+
+Saturday staffing at our own rates, if we cover it ourselves with no locum:
+- Vet: £360
+- Nurse: £170
+- Receptionist: £110
+
+So £680 a session.
+
+Call it 50 Saturdays a year once you take out the bank holiday weekends.
+
+Dana

package/packs/research/skills/source-synthesis/evals/files/6/practice-ledger-article.md

@@ -0,0 +1,13 @@
+# The Practice Ledger, May 2026
+
+## Is it time to open on Saturdays?
+
+*By our staff writer*
+
+Clients' working lives have changed, and more practices are asking whether a Saturday morning clinic would pay its way.
+
+Practices that open on Saturday mornings see an average of 14 appointments per session in their first year, according to the WCAPA 2025 Benchmarking Report. That is encouraging news for any practice weighing up the move.
+
+Saturday opening is quickly becoming something clients expect rather than a bonus, and practices that hold back risk losing younger pet owners to competitors who open at weekends.
+
+For practices thinking about it, the advice is to start with a trial and to talk to the team early about rotas.

package/packs/research/skills/source-synthesis/evals/files/6/wcapa-benchmarking-extract.md

@@ -0,0 +1,12 @@
+# Westbourne Companion Animal Practice Association (WCAPA)
+## Benchmarking Report 2025, extract: Section 4, Extended hours
+
+Sample: 41 member practices that returned the extended-hours questionnaire. Median practice size 7 full-time-equivalent vets (range 3 to 16).
+
+Of these, 17 practices introduced Saturday morning opening between 2022 and 2024.
+
+Practices that open on Saturday mornings see an average of 14 appointments per session in their first year. The range across practices was 6 to 23 appointments per session. Larger practices and those in town centres reported the higher figures.
+
+Average staffing cost per Saturday morning session, as reported by practices: £610.
+
+Figures are self-reported by practices and have not been audited.

package/packs/research/skills/source-synthesis/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "source-synthesis",
-  "version": "0.1.1",
-  "description": "Synthesise a set of supplied sources — papers, articles, reports, interview transcripts — into findings where every claim is cited to a source and a location ([S1:p4]), agreement and disagreement across sources are explicit, each finding carries an evidence-strength rating with the criteria used, and the gaps and what the sources do not say are listed. Never adds outside facts unless tagged as such, and ships a citation checker. Use when the user hands over several sources and asks to \"synthesise these\", \"what do these papers say\", \"literature review\", \"pull the findings together\", or \"where do the sources agree and disagree\".",
+  "version": "0.2.0",
+  "description": "Answer a question from a set of sources the user supplied — papers, reports, articles, interview notes, emails — saying only what the material supports, labelling anything that comes from elsewhere where it appears, counting a source that repeats another once, and giving a labelled estimate when the user needs a figure the sources don't settle. Written in the length and format the user asked for; a full cited literature review only when that is the ask. Use when the user hands over several sources and asks to \"synthesise these\", \"what do these papers say\", \"pull together what we know\", \"literature review\", or \"where do the sources agree and disagree\".",
   "entrypoint": "SKILL.md",
   "deps": {
     "npm": [],
@@ -37,6 +37,6 @@
   "permissions": {"network": [], "commands": [], "files": "named-paths"},
   "model": {
     "tier": "standard",
-    "rationale": "Bounded synthesis over supplied text with a fixed citation format and strength criteria; the citation checker catches the mechanical failures, so mid-tier judgment is enough."
+    "rationale": "Bounded synthesis over supplied text. The hard part is keeping outside knowledge out and checking the sources' own sums, which a mid-tier model does when told to."
   }
 }

package/packs/skill-engineering/skills/skill-author/SKILL.md

@@ -123,7 +123,7 @@ derived from the task wording, no siblings checked, every tool targeted.
 
 ## When NOT to use this skill
 
-- ❌ Adding a skill to the skilldrop catalogue itself, with its manifest, pack and `validate.py` rules: use `contribution-wizard`
+- ❌ Adding a skill to the skilldrop catalogue itself, with its manifest, pack and `validate.py` rules: follow that repo's `AGENTS.md` and run `python3 validate.py`
 - ❌ Auditing a skill that already exists: use `skill-review`
 - ❌ Adding evals to an existing skill without changing it: use `eval-harness-generator`
 - ❌ Repo-wide always-on rules for agents (commands, conventions, forbidden actions): use `agents-md-generator`

package/packs/skill-engineering/skills/skill-author/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "skill-author",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Write a new portable Agent Skill (a SKILL.md folder) from a described task, for Claude Code, Codex, Copilot, Cursor, Kiro or Antigravity in any repo — a description that leads with the artifact and ends with trigger phrases, decisive steps, a quality bar, when and when-not sections naming near-miss siblings, anti-patterns, a non-interactive rule, reference files and scripts that work in every tool, acceptance evals and trigger queries, and the install path for each tool. Use when the user says \"turn this into a skill\", \"write a SKILL.md for…\", \"make an agent skill that…\", or wants a repeatable task packaged so their coding agent does it the same way every time.",
   "entrypoint": "SKILL.md",
   "deps": {
@@ -13,7 +13,6 @@
   },
   "related": [
     "agents-md-generator",
-    "contribution-wizard",
     "eval-harness-generator",
     "skill-review"
   ],

package/packs/skill-engineering/skills/skill-review/SKILL.md

@@ -115,7 +115,7 @@ against the skills named in the folder itself.
 ## When NOT to use this skill
 
 - ❌ Writing a new skill from a task description: use `skill-author`
-- ❌ Adding a skill to the skilldrop catalogue itself, which has its own manifest and `validate.py` rules: use `contribution-wizard`
+- ❌ Adding a skill to the skilldrop catalogue itself, which has its own manifest and `validate.py` rules: follow that repo's `AGENTS.md` and run `python3 validate.py`
 - ❌ Generating more eval cases for a skill whose only gap is coverage: use `eval-harness-generator`
 - ❌ Reviewing a repo's always-on AGENTS.md policy file: use `agents-md-generator`
 - ❌ Threat-modelling the agent deployment that runs skills (its tools, data and egress): use `agent-threat-model`

package/packs/skill-engineering/skills/skill-review/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "skill-review",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Audit an existing Agent Skill folder (SKILL.md plus its scripts, references and evals) for Claude Code, Codex, Copilot, Cursor, Kiro or Antigravity, and return a READY / FIX FIRST / REWRITE verdict with severity-tagged findings across five areas — whether a router would pick it and whether it collides with a sibling, portability, safety (mapped to the OWASP Agentic Skills Top 10), structure, and eval coverage — backed by a stdlib lint script for the mechanical checks. Use when the user says \"review this skill\", \"is my SKILL.md any good\", \"why doesn't my skill trigger\", \"is this skill safe to install\", or wants a skill checked before sharing or publishing it.",
   "entrypoint": "SKILL.md",
   "deps": {
@@ -14,7 +14,6 @@
   "related": [
     "agent-threat-model",
     "agents-md-generator",
-    "contribution-wizard",
     "doc-critique",
     "eval-harness-generator",
     "skill-author"

package/packs/solution-architect/skills/api-contract-draft/SKILL.md

@@ -55,7 +55,7 @@ Produces the contract *before* the code — a valid OpenAPI 3.1 document two tea
 ## When NOT to use this skill
 
 - ❌ Documenting an API that already exists — that's `guide-builder` (reference archetype)
-- ❌ Choosing REST vs GraphQL vs gRPC — that's `tech-comparison-matrix`; this skill starts after
+- ❌ Choosing REST vs GraphQL vs gRPC — this skill starts after that choice is made
 - ❌ Reviewing a contract someone else drafted — `doc-critique` or `council-review`
 - ❌ Generating server/client code from the spec — hand the frozen contract to the codegen tool
 

package/packs/solution-architect/skills/api-contract-draft/manifest.json

@@ -1,11 +1,11 @@
 {
   "name": "api-contract-draft",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Draft an OpenAPI 3.1 contract from a feature brief or story — resource-oriented paths, a full error catalog (RFC 9457), pagination/idempotency/versioning decided not deferred, examples on every operation, plus a decisions log so review argues choices instead of YAML. Use when the user wants to design an API, draft an OpenAPI/Swagger spec, define request/response shapes, or agree a contract between frontend/backend or two teams before code.",
   "entrypoint": "SKILL.md",
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
-  "related": ["council-review", "doc-critique", "guide-builder", "tech-comparison-matrix", "user-story-splitter"],
+  "related": ["council-review", "doc-critique", "guide-builder", "user-story-splitter"],
   "tags": ["api-design", "openapi", "contract-first", "rest", "swagger", "asyncapi"],
   "model": { "tier": "standard", "rationale": "Schema synthesis against fixed conventions. The resource modeling needs judgment; the conventions bound it. Escalate via ambiguous-input on contested multi-team contracts." }
 }

package/packs/data-analytics/skills/metric-definition/SKILL.md

@@ -1,92 +0,0 @@
----
-name: metric-definition
-description: Write a metric spec precise enough for a semantic layer or dbt metric to implement and for two analysts to get the same number — name, business question, exact numerator and denominator, grain, time window and timezone, filters and exclusions (test accounts, refunds), allowed dimensions, edge cases (NULLs, late data, currency), owner, reference SQL, and the sanity checks that catch it going wrong. Use when the user says "define this metric", "how exactly do we calculate X", "finance and product get different numbers for X", "write the metric spec for our semantic layer", or "what counts as an active user".
----
-
-# metric-definition
-
-Turns a metric name that people already argue about ("active customers", "net revenue", "refund rate") into one written definition that produces one number. Most metric disputes are not about the data: they're two queries with different filters, windows or timezones answering under the same name. This skill pins every one of those choices down, writes the reference SQL, and adds the checks that catch the number drifting. It defines **how a metric is computed**. Choosing **which metric** judges a feature is `success-metrics`; that skill picks the primary, guardrails and decision rule, and this one makes any of those metrics exact.
-
-## How to respond
-
-**Four rules come before the steps and outrank them:**
-
-- **Answer what was asked, first.** Open with the answer, the decision or the artifact, in plain words. Scores, matrices, frameworks and tags come after it, and anything that doesn't change the answer is cut.
-- **Use only what you were given.** Don't add facts, names, numbers, incidents, history, steps or sections the input doesn't contain. What you need and don't have is left out of the artifact and listed once at the end under "To confirm".
-- **Deliver from what you have.** When the request gives you something to work on, state your assumptions in a line and produce the result. When it gives you nothing to work on, ask for it in one or two plain sentences and say what you will do once you have it.
-- **Write for someone who has never heard of this skill.** No skill names, no paths or scripts from this folder, no internal terms, and nothing about how the run was set up. A next step is one plain sentence at the end that describes the work.
-- **For this skill:** Give one definition. Check the SQL against the warehouse the user named: each function against the column's type, and a calendar period against a rolling one. A parameter the user has to fill in is listed under "To confirm", not left in the query.
-
-1. **Pin the question and the sources, asking once.** Ask at most 2 questions in one message: *"What decision does this number inform, and who reads it?"* and *"Which tables or models hold the data, and is there SQL or a dashboard already computing something under this name?"* Existing SQL is the best input you can get: it shows the definition people actually use today, including its bugs. If the user gave both, don't ask.
-
-**Non-interactive runs** (subagent, CI, headless): derive the business question and sources from the input and tag each `[assumption]`. Choices the input doesn't settle (timezone, exclusions, late-data policy) get a stated default tagged `[assumption]` and are listed under open decisions. No metric name and no business question in the input → emit `BLOCKED: need the metric name and the question it answers`.
-
-2. **Name it so one name means one formula.** `snake_case`, noun phrase, qualified where variants exist: ✅ `net_revenue_usd`, `gross_revenue_usd` — ❌ `revenue` covering both. If two teams compute it differently and both versions are legitimate, they get two names, not one name with a footnote. State the business question in one sentence: ✅ *"What share of last month's orders were refunded, by region?"* — ❌ *"Track refunds."*
-
-3. **Write the exact formula.** Numerator and denominator, each in words and as an aggregation over named columns: ✅ *"Numerator: count of distinct `order_id` with at least one non-reversed refund. Denominator: count of distinct `order_id` created in the window."* Name the metric type (count, sum, distinct count, ratio, average, percentile, cumulative), the unit and the display format (%, USD, decimals). A ratio is always **ratio of sums**, never an average of per-row or per-day ratios. See [`reference.md`](reference.md) for the types and their traps.
-
-4. **Fix the grain and the time.** Write down:
-   - **Entity**: what one unit is (order, customer, account, session).
-   - **Time column**: which timestamp decides membership in a period (created, paid, shipped, event or load time) and why.
-   - **Window**: calendar month, ISO week (Monday start), rolling 28 days, trailing 7 complete days.
-   - **Timezone**: the reporting zone, with the IANA name, e.g. `America/New_York`, not "EST".
-   - **Partial periods**: whether the current period is shown, and how it's marked.
-   - **Additivity**: whether the metric can be summed across days, regions or segments. Distinct counts and ratios can't (four weekly active-user counts don't add up to monthly active users), so say how it rolls up: recompute from the base, don't sum.
-
-5. **List every filter and exclusion with its predicate and reason.** Always ask about the usual suspects: test and internal accounts, refunds and cancellations, fraud, deleted or merged records, free or zero-value transactions, and staff discounts. ✅ *"Exclude test accounts: `NOT EXISTS (SELECT 1 FROM test_accounts t WHERE t.customer_id = o.customer_id)`. Reason: QA places real orders in production."* An exclusion without a predicate gets implemented three different ways.
-
-6. **Name the dimensions it can be sliced by, and the ones it can't.** For each allowed dimension, give the source column, the join path and whether the join is one-to-one. A dimension that fans out (product category on order-level revenue, when an order has many categories) is either disallowed or comes with an allocation rule. Say which.
-
-7. **Settle the edge cases explicitly.** NULLs in each column the formula uses (counted, excluded or defaulted), zero denominators (show NULL, not 0), late-arriving data (how many days a closed period may still change, and when it locks), currency (rate source and which date's rate), DST days, duplicates and replays, backfills, and timezone changes. Each gets a one-line rule, not a "be careful".
-
-8. **Assign an owner and a change policy.** The owner is a role and a team (✅ *"Finance analytics lead"*), not "data team". Status: `draft` or `certified`. Changing the formula is a new version with a change log entry and a dated cutover, never a silent edit, because a silent edit breaks every trend line that crosses the change date.
-
-9. **Write the reference SQL** in the user's dialect: one CTE per step (base population, exclusions, numerator, denominator), half-open time windows (`>= start AND < end`), boundaries converted to the reporting timezone, and `NULLIF` on the denominator. The reference SQL is the tie-breaker when the prose and an implementation disagree. Recommend the user runs `sql-review` on it before it's certified.
-
-10. **Add the sanity checks** that would catch the metric being wrong, each runnable: reconciliation with a system of record (the finance ledger, the billing system), hard bounds (a rate stays within 0 to 1), additivity (regions sum to the total, for additive metrics only), join row counts (the base population's count doesn't change after dimension joins), a period-over-period alert threshold, and a hand-computed fixture of 5–10 rows with the expected answer.
-
-11. **Emit with [`templates/metric-spec.md`](templates/metric-spec.md)** in one message, ending with **open decisions**: each choice made by default, with the person who should confirm it.
-
-## Useful references in this skill
-
-- [`reference.md`](reference.md) — metric types and their traps, additivity rules, the exclusion and edge-case checklist, the sanity-check catalogue, and how the spec's fields map to a semantic layer (dbt MetricFlow and similar)
-- [`templates/metric-spec.md`](templates/metric-spec.md) — the spec skeleton
-- [`examples/refund-rate.md`](examples/refund-rate.md) — worked example: an order refund rate disputed between finance and support, defined end to end
-
-## Quality bar
-
-- **One name, one formula.** The numerator and denominator are written as aggregations over named columns, so two analysts would write the same SQL.
-- **Grain, time column, window and timezone are all explicit**, with an IANA timezone name and a half-open window.
-- **Every exclusion has a predicate and a reason.** No "exclude test data" without the SQL for it.
-- **Additivity is stated**, with the roll-up rule for non-additive metrics.
-- **Every allowed dimension has a join path and its cardinality**, and fan-out dimensions are disallowed or carry an allocation rule.
-- **Edge cases get one-line rules**, including late data with a lock date and zero denominators.
-- **The reference SQL runs as written** in the named dialect and matches the prose.
-- **At least three runnable sanity checks**, including one reconciliation with a system of record where one exists.
-- **Nothing is invented.** Table names, columns and business rules not given are marked `[assumption]` and listed in open decisions.
-
-## When to use this skill
-
-- ✅ Two teams report different numbers under the same metric name
-- ✅ Putting a metric into a semantic layer, dbt metrics or a BI tool's model, and it needs one definition
-- ✅ "What counts as an active user / a churned customer / net revenue?"
-- ✅ Certifying a metric before it goes on an exec dashboard or into a board pack
-
-## When NOT to use this skill
-
-- ❌ Choosing which metric judges a feature, with targets, guardrails and a decision rule — that's `success-metrics`
-- ❌ Checking that an existing query computes its number correctly — that's `sql-review`
-- ❌ Deciding which charts and metrics go on a dashboard — that's `dashboard-spec`
-- ❌ Agreeing a dataset's schema, freshness and quality guarantees with its consumers — that's `data-contract`
-- ❌ Service health indicators, SLOs and error budgets — that's `observability-plan`
-
-## Anti-patterns to avoid
-
-- ❌ **The footnoted metric.** One name, three formulas, and a footnote on each dashboard. Split it into named variants.
-- ❌ **Average of ratios.** `AVG(daily_refund_rate)` weights a quiet Sunday like Black Friday. Divide the sums.
-- ❌ **"Monthly" with no timezone.** The UTC month and the New York month differ by hours of orders at each boundary, and the number won't match finance's.
-- ❌ **Summing distinct counts.** Adding weekly active users to get monthly active users counts every returning user four times.
-- ❌ **Exclusions in prose only.** "Excludes test accounts" with no predicate gets implemented three different ways.
-- ❌ **Silent redefinition.** Changing the formula in place, so last quarter's trend line now compares two different metrics.
-- ❌ **No owner.** A metric "owned by the data team" is owned by nobody when finance and product disagree about it.
-- ❌ **Specs with no checks.** A definition that nobody tests drifts the first time an upstream table changes.