reask 0.1.0__tar.gz

reask-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
+  "name": "reask",
+  "owner": {
+    "name": "Mikhail Nezhinsky",
+    "url": "https://github.com/Nezhinskiy"
+  },
+  "description": "Install reask as a Claude Code plugin.",
+  "plugins": [
+    {
+      "name": "reask",
+      "source": "./",
+      "description": "Re-ask a pending question as a self-contained briefing: context, a live example, options with pros and cons, a recommendation, one question.",
+      "license": "MIT",
+      "keywords": ["questions", "decisions", "clarification", "briefing"]
+    }
+  ]
+}

reask-0.1.0/.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "reask",
+  "description": "Re-ask a pending question as a self-contained briefing: context, a live example, options with pros and cons, a recommendation, one question.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Mikhail Nezhinsky",
+    "url": "https://github.com/Nezhinskiy"
+  },
+  "homepage": "https://github.com/Nezhinskiy/reask",
+  "repository": "https://github.com/Nezhinskiy/reask",
+  "license": "MIT",
+  "keywords": ["questions", "decisions", "clarification", "briefing"]
+}

reask-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+.mypy_cache/
+.ruff_cache/
+build/

reask-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+Newest first. Every entry is written for users: a release's section becomes its GitHub Release
+notes.
+
+## 0.1.0 (2026-09-29)
+
+First release.
+
+- The `/reask` skill: re-asks a pending question as a five-part briefing (where we are, a live
+  example, options with pros and cons, a recommendation, one question) in under 500 words and in
+  the user's language, or as a short form when the question is a simple yes or no.
+- Install it with the Skills CLI (`npx skills add Nezhinskiy/reask`), as a Claude Code plugin,
+  with the `reask` Python package, as a zip for claude.ai, or by copying `SKILL.md`.
+- `reask install`, `reask uninstall` and `reask print`. Neither `install` nor `uninstall`
+  replaces or deletes a copy you have edited without `--force`, and neither follows a symbolic
+  link inside the skills directory.
+- Every release is built in CI from its tag and carries build provenance attestations.

reask-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikhail Nezhinsky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

reask-0.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.5
+Name: reask
+Version: 0.1.0
+Summary: An agent skill that re-asks a pending question as a self-contained briefing
+Project-URL: Homepage, https://github.com/Nezhinskiy/reask
+Project-URL: Source, https://github.com/Nezhinskiy/reask
+Project-URL: Changelog, https://github.com/Nezhinskiy/reask/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/Nezhinskiy/reask/issues
+Author: Mikhail Nezhinsky
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-skills,ai-agents,claude,claude-code,llm,skill
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# reask
+
+[![ci](https://github.com/Nezhinskiy/reask/actions/workflows/ci.yml/badge.svg)](https://github.com/Nezhinskiy/reask/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/reask)](https://pypi.org/project/reask/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/Nezhinskiy/reask/blob/main/LICENSE)
+
+**Your agent asked you something and you cannot answer it.** You lost the context, the options
+are jargon, or you cannot see what actually differs between them. Type `/reask`.
+
+The agent asks the same question again, written for someone who just walked in: where the work
+stands, one real example carried through every option, the pros *and* cons of each (the one it
+recommends included), its recommendation, and one question you can answer. Under 500 words, in
+your language.
+
+reask is an [Agent Skill](https://agentskills.io): one file,
+[`SKILL.md`](https://github.com/Nezhinskiy/reask/blob/main/skills/reask/SKILL.md), that Claude
+Code, Codex, Cursor, Gemini CLI and other agents that read the format can load.
+
+## Install
+
+**Any agent, with the [Skills CLI](https://github.com/vercel-labs/skills):**
+
+```bash
+npx skills add Nezhinskiy/reask --global
+```
+
+It asks which agents to install into; `--agent claude-code` (or `--agent '*'`) skips the
+question, and leaving off `--global` installs into the current project.
+
+**Claude Code plugin:**
+
+```text
+/plugin marketplace add Nezhinskiy/reask
+/plugin install reask@reask
+```
+
+A plugin's skills are namespaced, so this one answers to `/reask:reask`. Updates arrive with
+`/plugin marketplace update reask`.
+
+**Python**, for Claude Code:
+
+```bash
+uvx reask install
+```
+
+or `pipx run reask install`. This writes `~/.claude/skills/reask/SKILL.md` (under
+`$CLAUDE_CONFIG_DIR` if you set it); `--project` writes `./.claude/skills` instead and
+`--skills-dir PATH` any other location. `reask print` prints the skill and `reask uninstall`
+removes it. Neither command overwrites or deletes a copy you have edited unless you pass `--force`.
+
+**claude.ai and Claude Desktop:** download `reask-skill.zip` from the
+[latest release](https://github.com/Nezhinskiy/reask/releases/latest) and upload it under
+Settings > Capabilities > Skills.
+
+**By hand:** copy `skills/reask/SKILL.md` into a `reask/` folder in your agent's skills
+directory.
+
+## Example
+
+Mid-task, the agent asks:
+
+> Should the price cache key include the locale, or should we normalise currency at read time?
+
+You type `/reask`, and get:
+
+> **Where we are and why this comes up.** We are putting a cache in front of the pricing API so
+> product pages stop taking 800 ms. The cache works; what is open is what each entry is keyed
+> on, and nothing merges until that is decided. The pricing API already returns a
+> country-specific price for 3 SKUs. *Decided:* Redis, 10-minute expiry. *My assumption:* the 40
+> locales we ship today are the ones to plan for.
+>
+> **A live example.** SKU `B-2210`, one of those 3, costs €49 in Germany and €45 in Austria.
+> Viewed from Berlin (`de-DE`) and then from Vienna (`de-AT`):
+>
+> | | Key per locale | Normalise at read |
+> |---|---|---|
+> | Cache entries | 2 | 1 |
+> | API calls on first views | 2 | 1 |
+> | Price shown in Vienna | €45 | €49 |
+>
+> **Options.**
+> *Key per locale*: one entry per SKU per locale.
+> Pros: every country sees its own price; no conversion code.
+> Cons: 40 times the entries; 40 cold-cache API calls per SKU instead of one.
+> *Normalise at read*: one entry per SKU in euros, converted when read.
+> Pros: 40 times fewer entries; one warm-up per SKU.
+> Cons: shows the wrong price for those 3 SKUs today; a rate-table lookup on every read.
+>
+> **What I recommend.** Key per locale. Normalising shows Vienna €49 for `B-2210` today, not
+> someday; 40 entries per SKU is about 2 MB at our catalogue size. I would change my mind if
+> those 3 prices turn out to be a data error.
+>
+> **The question.** Key the cache per locale (recommended), or normalise currency at read time?
+
+In Claude Code the question arrives with both answers as options to pick, the recommended one
+first. This example was written by hand to show the format; a real briefing is built from your
+session's facts.
+
+## Why it works
+
+Agents ask good questions in the wrong register: they have the whole session in context and
+you do not. reask fixes the register, not the question. It keeps the decision yours (it never
+starts on its default), states each option's downside at full strength, and ties the
+recommendation to facts from your work, so you can overrule it with one reply.
+
+## Contributing and security
+
+Behaviour reports with a transcript are the most useful contribution; see
+[CONTRIBUTING.md](https://github.com/Nezhinskiy/reask/blob/main/CONTRIBUTING.md). Report
+vulnerabilities privately, as described in
+[SECURITY.md](https://github.com/Nezhinskiy/reask/blob/main/SECURITY.md). Every release is built
+in CI and carries a
+[build provenance attestation](https://github.com/Nezhinskiy/reask/blob/main/SECURITY.md#verifying-what-you-installed).
+
+## License
+
+[MIT](https://github.com/Nezhinskiy/reask/blob/main/LICENSE)

reask-0.1.0/README.md

@@ -0,0 +1,117 @@
+# reask
+
+[![ci](https://github.com/Nezhinskiy/reask/actions/workflows/ci.yml/badge.svg)](https://github.com/Nezhinskiy/reask/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/reask)](https://pypi.org/project/reask/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/Nezhinskiy/reask/blob/main/LICENSE)
+
+**Your agent asked you something and you cannot answer it.** You lost the context, the options
+are jargon, or you cannot see what actually differs between them. Type `/reask`.
+
+The agent asks the same question again, written for someone who just walked in: where the work
+stands, one real example carried through every option, the pros *and* cons of each (the one it
+recommends included), its recommendation, and one question you can answer. Under 500 words, in
+your language.
+
+reask is an [Agent Skill](https://agentskills.io): one file,
+[`SKILL.md`](https://github.com/Nezhinskiy/reask/blob/main/skills/reask/SKILL.md), that Claude
+Code, Codex, Cursor, Gemini CLI and other agents that read the format can load.
+
+## Install
+
+**Any agent, with the [Skills CLI](https://github.com/vercel-labs/skills):**
+
+```bash
+npx skills add Nezhinskiy/reask --global
+```
+
+It asks which agents to install into; `--agent claude-code` (or `--agent '*'`) skips the
+question, and leaving off `--global` installs into the current project.
+
+**Claude Code plugin:**
+
+```text
+/plugin marketplace add Nezhinskiy/reask
+/plugin install reask@reask
+```
+
+A plugin's skills are namespaced, so this one answers to `/reask:reask`. Updates arrive with
+`/plugin marketplace update reask`.
+
+**Python**, for Claude Code:
+
+```bash
+uvx reask install
+```
+
+or `pipx run reask install`. This writes `~/.claude/skills/reask/SKILL.md` (under
+`$CLAUDE_CONFIG_DIR` if you set it); `--project` writes `./.claude/skills` instead and
+`--skills-dir PATH` any other location. `reask print` prints the skill and `reask uninstall`
+removes it. Neither command overwrites or deletes a copy you have edited unless you pass `--force`.
+
+**claude.ai and Claude Desktop:** download `reask-skill.zip` from the
+[latest release](https://github.com/Nezhinskiy/reask/releases/latest) and upload it under
+Settings > Capabilities > Skills.
+
+**By hand:** copy `skills/reask/SKILL.md` into a `reask/` folder in your agent's skills
+directory.
+
+## Example
+
+Mid-task, the agent asks:
+
+> Should the price cache key include the locale, or should we normalise currency at read time?
+
+You type `/reask`, and get:
+
+> **Where we are and why this comes up.** We are putting a cache in front of the pricing API so
+> product pages stop taking 800 ms. The cache works; what is open is what each entry is keyed
+> on, and nothing merges until that is decided. The pricing API already returns a
+> country-specific price for 3 SKUs. *Decided:* Redis, 10-minute expiry. *My assumption:* the 40
+> locales we ship today are the ones to plan for.
+>
+> **A live example.** SKU `B-2210`, one of those 3, costs €49 in Germany and €45 in Austria.
+> Viewed from Berlin (`de-DE`) and then from Vienna (`de-AT`):
+>
+> | | Key per locale | Normalise at read |
+> |---|---|---|
+> | Cache entries | 2 | 1 |
+> | API calls on first views | 2 | 1 |
+> | Price shown in Vienna | €45 | €49 |
+>
+> **Options.**
+> *Key per locale*: one entry per SKU per locale.
+> Pros: every country sees its own price; no conversion code.
+> Cons: 40 times the entries; 40 cold-cache API calls per SKU instead of one.
+> *Normalise at read*: one entry per SKU in euros, converted when read.
+> Pros: 40 times fewer entries; one warm-up per SKU.
+> Cons: shows the wrong price for those 3 SKUs today; a rate-table lookup on every read.
+>
+> **What I recommend.** Key per locale. Normalising shows Vienna €49 for `B-2210` today, not
+> someday; 40 entries per SKU is about 2 MB at our catalogue size. I would change my mind if
+> those 3 prices turn out to be a data error.
+>
+> **The question.** Key the cache per locale (recommended), or normalise currency at read time?
+
+In Claude Code the question arrives with both answers as options to pick, the recommended one
+first. This example was written by hand to show the format; a real briefing is built from your
+session's facts.
+
+## Why it works
+
+Agents ask good questions in the wrong register: they have the whole session in context and
+you do not. reask fixes the register, not the question. It keeps the decision yours (it never
+starts on its default), states each option's downside at full strength, and ties the
+recommendation to facts from your work, so you can overrule it with one reply.
+
+## Contributing and security
+
+Behaviour reports with a transcript are the most useful contribution; see
+[CONTRIBUTING.md](https://github.com/Nezhinskiy/reask/blob/main/CONTRIBUTING.md). Report
+vulnerabilities privately, as described in
+[SECURITY.md](https://github.com/Nezhinskiy/reask/blob/main/SECURITY.md). Every release is built
+in CI and carries a
+[build provenance attestation](https://github.com/Nezhinskiy/reask/blob/main/SECURITY.md#verifying-what-you-installed).
+
+## License
+
+[MIT](https://github.com/Nezhinskiy/reask/blob/main/LICENSE)

reask-0.1.0/pyproject.toml

@@ -0,0 +1,82 @@
+[project]
+name = "reask"
+dynamic = ["version"]
+description = "An agent skill that re-asks a pending question as a self-contained briefing"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Mikhail Nezhinsky" }]
+requires-python = ">=3.11"
+keywords = ["claude", "claude-code", "agent-skills", "skill", "ai-agents", "llm"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development",
+]
+
+[project.urls]
+Homepage = "https://github.com/Nezhinskiy/reask"
+Source = "https://github.com/Nezhinskiy/reask"
+Changelog = "https://github.com/Nezhinskiy/reask/blob/main/CHANGELOG.md"
+Issues = "https://github.com/Nezhinskiy/reask/issues"
+
+[project.scripts]
+reask = "reask.cli:main"
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+# SKILL.md's metadata.version is the package version, so the skill and the package cannot disagree.
+[tool.hatch.version]
+path = "skills/reask/SKILL.md"
+pattern = 'version: "(?P<version>[^"]+)"'
+
+# skills/reask/SKILL.md is the single source; the wheel carries a copy inside the package.
+[tool.hatch.build.targets.wheel.force-include]
+"skills/reask/SKILL.md" = "reask/SKILL.md"
+
+# What building and testing need; the repository's CI and community files stay on GitHub.
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/skills", "/scripts", "/tests", "/.claude-plugin", "/CHANGELOG.md"]
+
+[tool.uv]
+# The release attests whatever the build backend produces, so the backend is pinned too.
+build-constraint-dependencies = ["hatchling==1.32.4"]
+
+[dependency-groups]
+dev = ["pytest>=9", "pytest-cov>=7", "ruff>=0.16", "mypy>=2.3"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF", "PT", "C4", "PL"]
+ignore = ["PLR2004"]  # magic values: tests compare against literal exit codes and limits
+
+[tool.mypy]
+strict = true
+files = ["src", "scripts", "tests"]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+addopts = ["--strict-markers", "--strict-config"]
+
+[tool.coverage.run]
+source = ["reask", "scripts"]
+branch = true
+
+[tool.coverage.report]
+fail_under = 100
+show_missing = true
+skip_covered = true
+exclude_also = ['if __name__ == "__main__":']

reask-0.1.0/scripts/check_skill.py

@@ -0,0 +1,123 @@
+"""Check the skill package: one skill folder, its frontmatter, the plugin manifests, one version.
+
+The version is written in three places: SKILL.md's metadata.version (which is also the Python
+package's version, through pyproject.toml's [tool.hatch.version]), .claude-plugin/plugin.json,
+and CHANGELOG.md's newest release heading. When given, the release tag is a fourth. All must agree.
+Run with no arguments in CI and with `--tag vX.Y.Z` in the release workflow.
+
+The frontmatter is read with regular expressions rather than a YAML parser, to keep the project
+free of dependencies. That is why the description must be one double-quoted line.
+"""
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+from scripts import release_notes
+
+ROOT = Path(__file__).resolve().parent.parent
+NAME = "reask"
+SKILL = Path("skills") / NAME / "SKILL.md"
+DESCRIPTION_LIMIT = 1024  # the Agent Skills specification's cap
+IGNORED = {".git", ".venv", "build", "dist"}
+
+
+def _frontmatter(skill: str) -> str | None:
+    match = re.match(r"\A---\n(.*?)\n---\n", skill, re.S)
+    return match.group(1) if match else None
+
+
+def _field(frontmatter: str, pattern: str) -> str | None:
+    match = re.search(pattern, frontmatter, re.M)
+    return match.group(1) if match else None
+
+
+def _json(root: Path, name: str) -> dict[str, Any]:
+    data: dict[str, Any] = json.loads((root / ".claude-plugin" / name).read_text("utf-8"))
+    return data
+
+
+def versions(root: Path) -> dict[str, str | None]:
+    frontmatter = _frontmatter((root / SKILL).read_text(encoding="utf-8")) or ""
+    return {
+        "SKILL.md metadata.version": _field(frontmatter, r'^\s+version:\s*"([^"]+)"\s*$'),
+        ".claude-plugin/plugin.json": _json(root, "plugin.json").get("version"),
+        "CHANGELOG.md's newest release": release_notes.latest(
+            (root / "CHANGELOG.md").read_text(encoding="utf-8")
+        ),
+    }
+
+
+def structure(root: Path) -> list[str]:
+    problems = []
+    skills = sorted(
+        p.relative_to(root).as_posix()
+        for p in root.rglob("SKILL.md")
+        if not IGNORED & set(p.relative_to(root).parts)
+    )
+    if skills != [SKILL.as_posix()]:
+        problems.append(f"expected exactly one skill, {SKILL.as_posix()}; found {skills}")
+        if not (root / SKILL).is_file():
+            return problems
+    frontmatter = _frontmatter((root / SKILL).read_text(encoding="utf-8"))
+    if frontmatter is None:
+        return [*problems, "SKILL.md must begin with YAML frontmatter"]
+    if _field(frontmatter, r"^name:\s*(\S+)\s*$") != NAME:
+        problems.append(f"SKILL.md name must be {NAME!r}")
+    description = _field(frontmatter, r'^description:\s*"((?:[^"\\]|\\.)*)"\s*$')
+    if description is None:
+        problems.append("SKILL.md description must be one double-quoted line")
+    elif len(description) > DESCRIPTION_LIMIT:
+        problems.append(
+            f"SKILL.md description is {len(description)} chars, over {DESCRIPTION_LIMIT}"
+        )
+    # The plugin finds the skill through the default skills/ directory; a "skills" override
+    # would load something else.
+    plugin = _json(root, "plugin.json")
+    if plugin.get("name") != NAME or "skills" in plugin:
+        problems.append(f'plugin.json must be named {NAME!r} and must not override "skills"')
+    market = _json(root, "marketplace.json")
+    entries = [(p.get("name"), p.get("source")) for p in market.get("plugins", [])]
+    if entries != [(NAME, "./")]:
+        problems.append(f'marketplace.json must list one plugin {NAME!r} with source "./"')
+    return problems
+
+
+def check(root: Path, tag: str | None = None) -> list[str]:
+    problems = structure(root)
+    if not (root / SKILL).is_file():
+        return problems
+    found = versions(root)
+    expected = found["SKILL.md metadata.version"]
+    if tag is not None:
+        found["tag"] = tag[1:] if tag.startswith("v") else None
+    problems += [
+        f"{name}: {value!r} != SKILL.md's {expected!r}"
+        for name, value in found.items()
+        if value != expected
+    ]
+    changelog = (root / "CHANGELOG.md").read_text(encoding="utf-8")
+    if expected is not None and release_notes.notes(changelog, expected) is None:
+        problems.append(f"CHANGELOG.md has no release notes for {expected}")
+    return problems
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--tag", help="the release tag, vX.Y.Z")
+    parser.add_argument("--root", type=Path, default=ROOT)
+    args = parser.parse_args(argv)
+    problems = check(args.root, args.tag)
+    for problem in problems:
+        print(f"::error::{problem}", file=sys.stderr)
+    if not problems:
+        version = versions(args.root)["SKILL.md metadata.version"]
+        print(f"skill package ok, one version everywhere: {version}")
+    return 1 if problems else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

reask-0.1.0/scripts/release_notes.py

@@ -0,0 +1,45 @@
+"""Read CHANGELOG.md: its newest release, and a release's section as the GitHub Release notes.
+
+A release heading is `## X.Y.Z (YYYY-MM-DD)`; `## Unreleased` and anything else is not one. Both
+check_skill.py and the release workflow read the changelog through this module, so a heading one
+of them accepts the other cannot reject.
+"""
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+HEADING = r"^## (?P<version>\d+\.\d+\.\d+) \(\d{4}-\d{2}-\d{2}\)$"
+
+
+def latest(changelog: str) -> str | None:
+    """Return the newest release's version: the first release heading."""
+    match = re.search(HEADING, changelog, re.M)
+    return match["version"] if match else None
+
+
+def notes(changelog: str, version: str) -> str | None:
+    """Return the body of `version`'s section, or None if it has no section or an empty one."""
+    for match in re.finditer(rf"{HEADING}\n(?P<body>.*?)(?=^## |\Z)", changelog, re.M | re.S):
+        if match["version"] == version:
+            return match["body"].strip() or None
+    return None
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("tag", help="the release tag, vX.Y.Z")
+    parser.add_argument("--changelog", type=Path, default=ROOT / "CHANGELOG.md")
+    args = parser.parse_args(argv)
+    found = notes(args.changelog.read_text(encoding="utf-8"), args.tag.removeprefix("v"))
+    if found is None:
+        print(f"::error::{args.changelog.name} has no section for {args.tag}", file=sys.stderr)
+        return 1
+    print(found)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

reask-0.1.0/scripts/skill_zip.py

@@ -0,0 +1,38 @@
+"""Build the skill zip that claude.ai accepts: a `reask/` folder holding the skill and LICENSE.
+
+Entries carry zipfile's fixed default timestamp rather than the files' mtimes, so the same
+sources always give the same bytes.
+"""
+
+import argparse
+import zipfile
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+SKILL = ROOT / "skills" / "reask"
+
+
+def build(destination: Path) -> None:
+    # The whole skill folder, as the other channels ship it, plus the licence it names.
+    files = (p for p in SKILL.rglob("*") if p.is_file())
+    entries = {f"reask/{p.relative_to(SKILL).as_posix()}": p for p in files}
+    entries["reask/LICENSE"] = ROOT / "LICENSE"
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    with zipfile.ZipFile(destination, "w", zipfile.ZIP_DEFLATED) as archive:
+        for name in sorted(entries):
+            info = zipfile.ZipInfo(name)
+            info.compress_type = zipfile.ZIP_DEFLATED
+            archive.writestr(info, entries[name].read_bytes())
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("destination", type=Path)
+    args = parser.parse_args(argv)
+    build(args.destination)
+    print(f"wrote {args.destination}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

reask-0.1.0/skills/reask/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: reask
+description: "Use when the user asks for a pending question to be asked again or explained — /reask, \"ask again\", \"I don't get the question\", \"explain the options\", \"what are you asking me\" (in any language) — or when they answer a question of yours with confusion rather than with a choice."
+license: MIT
+metadata:
+  version: "0.1.0"
+---
+
+# /reask
+
+Ask the question you are already waiting on again, written for someone who just walked in and
+remembers nothing. Make that decision answerable: do not decide it for the user, and do not swap
+it for a different question.
+
+Write in the language the user writes in, headings included; the English headings below are a
+template.
+
+## First, which case is this
+
+- **Nothing is pending.** Say so in one line and ask what they want to decide.
+- **The user has already chosen.** Confirm the choice in one line and carry on.
+- **A yes/no question, or two options that differ in one fact.** The short form, under 100 words:
+  what is being decided and what waits on it, the fact that separates the answers, your
+  recommendation, then the question.
+- **Anything else.** The full briefing below.
+
+## The briefing
+
+| Part | Contents | Budget |
+|---|---|---|
+| **1. "Where we are and why this comes up"** | What we are building in terms of what it does for the user; where the work stands; what stops until this is answered. Then one line of what is already **decided**, and one line, named as yours, of what you **carry over as an assumption** (a dimension copied from a neighbouring table, a component you expect to reuse), so the user can overturn it now instead of meeting it later as a decision they never made. | 3-5 sentences |
+| **2. "A live example"** | One concrete case with real values from this work (an actual record, an actual query, an actual number) carried through every option, so the difference is something the user sees rather than infers. | ~120 words, usually a table |
+| **3. "Options"** | Per option: one line of what it is in plain words, then **Pros** and **Cons**. At most three options in full; name any others in one line each. | up to 3 pros and 3 cons, one line each |
+| **4. "What I recommend"** | Which one, and why from the facts of *this* situation: numbers, existing code, what already ships. Then what would change your mind. | up to 5 lines |
+| **5. "The question"** | The decision as one answerable question. Ask it with your harness's structured-question tool if it has one (`AskUserQuestion` in Claude Code): short labels, recommended first. Otherwise ask it as plain text. | 1 question |
+| | | **under 500 words total** |
+
+The word total binds before any part's budget. A briefing that costs more to read than the
+question costs to answer has failed.
+
+## Rules
+
+**Say it once.** Each fact lives in one part; later parts point back at the example instead of
+re-describing it. The fact that settles the decision appears by part 2: part 4 argues from it and
+never reveals it. Cut every sentence that restates the previous one, and every clause that adds
+emphasis rather than information.
+
+**Plain words.** A term the user would have to look up gets a short gloss at first use:
+`HNSW (a kind of index: slower to build, but never needs retraining)`. A term that does not carry
+the decision is dropped, not glossed.
+
+**Fair to every option.** Every option in part 3 gets both lists, the one you recommend included,
+and every con stands at full strength, written as its strongest critic would write it. Your case
+for or against an option goes in part 4, where the user can overrule it.
+
+**Decided means decided.** Only what was actually settled goes in the decided line. Anything you
+inferred is an assumption, and is labelled as yours.
+
+**End on the question**, never on an intention: no "otherwise I'll take B", no starting on your
+default.
+
+**A better question is an aside.** If you now think a different question should be asked, the
+briefing still covers the original. Add one line after part 5 naming the better question and why,
+and let the user choose which to answer.
+
+## When a picture is faster than prose
+
+Some differences cost more words than they are worth: screen layout and flow, what the user ends
+up seeing, how components connect. When one of those *is* the subject and you can show the user a
+rendered file (in Claude Code, `SendUserFile` with `display: "render"`), write one small
+self-contained HTML file outside the user's project, in a scratch or temporary directory. Use the
+user's language, one screen, no scrolling, the options side by side, inline CSS; no scripts, no
+external URLs or images, no forms. Then cut part 2 to one line pointing at it, so the briefing
+gets shorter.
+
+Skip it when the difference is a property of data or behaviour rather than something visible, or
+when you cannot show a file: then the example stays in prose.
+
+## Before you send
+
+- The short form, or all five parts in order, in the user's language.
+- Under 500 words (under 100 for the short form).
+- In the full briefing, every option has pros and cons, the recommended one included, and the
+  deciding fact appears before part 4.
+- The last thing is the question, with no default action attached.

reask-0.1.0/src/reask/__init__.py

@@ -0,0 +1,18 @@
+"""reask: an agent skill that re-asks a pending question as a self-contained briefing."""
+
+from importlib.metadata import version
+from importlib.resources import files
+from pathlib import Path
+
+__version__ = version("reask")
+
+# skills/reask/SKILL.md is the one copy; the wheel carries it as reask/SKILL.md
+# (pyproject.toml, force-include). An editable install has no such copy, so it reads the source.
+_CHECKOUT_SKILL = Path(__file__).resolve().parents[2] / "skills" / "reask" / "SKILL.md"
+
+
+def skill_text() -> str:
+    """Return the bundled SKILL.md."""
+    bundled = files("reask").joinpath("SKILL.md")
+    source = bundled if bundled.is_file() else _CHECKOUT_SKILL
+    return source.read_text(encoding="utf-8")

reask-0.1.0/src/reask/cli.py

@@ -0,0 +1,125 @@
+"""Command line: install, print or remove the reask skill."""
+
+import argparse
+import os
+import sys
+from collections.abc import Callable
+from pathlib import Path
+
+from reask import __version__, skill_text
+
+NAME = "reask"
+
+
+class RefusedError(Exception):
+    """An operation reask will not perform; the message says why and what to do instead."""
+
+
+def _default_skills_dir() -> Path:
+    config = os.environ.get("CLAUDE_CONFIG_DIR")
+    return (Path(config).expanduser() if config else Path.home() / ".claude") / "skills"
+
+
+def _locate(args: argparse.Namespace) -> tuple[Path, Path]:
+    """Return the directory the user named, and the SKILL.md reask manages below it."""
+    if args.project:
+        base = Path.cwd()
+        return base, base / ".claude" / "skills" / NAME / "SKILL.md"
+    base = args.skills_dir.expanduser() if args.skills_dir else _default_skills_dir()
+    return base, base / NAME / "SKILL.md"
+
+
+def _refuse_links(base: Path, target: Path) -> None:
+    # Everything under a project is whatever the cloned repository put there, so a link below
+    # the named directory could aim a write or a delete anywhere. Below it, reask follows none.
+    path = base
+    for part in target.relative_to(base).parts:
+        path /= part
+        if path.is_symlink():
+            raise RefusedError(
+                f"{path} is a symbolic link, and reask does not write or delete through links. "
+                "If another tool installed the skill there (the Skills CLI links its folders), "
+                "manage it with that tool."
+            )
+
+
+def _refuse_edited(target: Path, data: bytes, force: bool, verb: str) -> None:
+    if not target.is_file():
+        raise RefusedError(f"{target} is not a file")
+    if not force and target.read_bytes() != data:
+        raise RefusedError(
+            f"{target} differs from reask {__version__}'s copy (edited, or another version); "
+            f"pass --force to {verb} it"
+        )
+
+
+def _install(args: argparse.Namespace) -> int:
+    base, target = _locate(args)
+    _refuse_links(base, target)
+    data = skill_text().encode("utf-8")
+    if target.exists():
+        _refuse_edited(target, data, args.force, "replace")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_bytes(data)
+    print(f"installed {target}")
+    return 0
+
+
+def _uninstall(args: argparse.Namespace) -> int:
+    base, target = _locate(args)
+    _refuse_links(base, target)
+    if not target.exists():
+        raise RefusedError(f"{target} not found; nothing to remove")
+    _refuse_edited(target, skill_text().encode("utf-8"), args.force, "remove")
+    target.unlink()
+    folder = target.parent
+    if any(folder.iterdir()):
+        print(f"removed {target}; kept {folder}, which holds other files")
+    else:
+        folder.rmdir()
+        print(f"removed {folder}")
+    return 0
+
+
+def _print(_: argparse.Namespace) -> int:
+    # Bytes, not text: the console's encoding (cp1252 on Windows) and newline translation must
+    # not change the skill on its way to `reask print > SKILL.md`.
+    sys.stdout.flush()
+    sys.stdout.buffer.write(skill_text().encode("utf-8"))
+    sys.stdout.buffer.flush()
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="reask", description=__doc__)
+    parser.add_argument("--version", action="version", version=__version__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    for name, func, help_text, force_help in (
+        ("install", _install, "write SKILL.md into a skills directory", "replace an edited copy"),
+        ("uninstall", _uninstall, "remove the installed SKILL.md", "remove an edited copy"),
+    ):
+        cmd = sub.add_parser(name, help=help_text)
+        where = cmd.add_mutually_exclusive_group()
+        where.add_argument("--project", action="store_true", help="use ./.claude/skills")
+        where.add_argument(
+            "--skills-dir",
+            type=Path,
+            help="skills directory (default: $CLAUDE_CONFIG_DIR/skills, else ~/.claude/skills)",
+        )
+        cmd.add_argument("--force", action="store_true", help=force_help)
+        cmd.set_defaults(func=func)
+
+    sub.add_parser("print", help="print SKILL.md to stdout").set_defaults(func=_print)
+
+    args = parser.parse_args(argv)
+    command: Callable[[argparse.Namespace], int] = args.func
+    try:
+        return command(args)
+    except (RefusedError, OSError) as error:
+        print(f"reask: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

reask-0.1.0/tests/test_check_skill.py

@@ -0,0 +1,147 @@
+import shutil
+from pathlib import Path
+
+import pytest
+
+from scripts import check_skill
+
+ROOT = Path(__file__).resolve().parent.parent
+FILES = (
+    "CHANGELOG.md",
+    "skills/reask/SKILL.md",
+    ".claude-plugin/plugin.json",
+    ".claude-plugin/marketplace.json",
+)
+SKILL = "skills/reask/SKILL.md"
+
+
+@pytest.fixture
+def tree(tmp_path: Path) -> Path:
+    for name in FILES:
+        (tmp_path / name).parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy(ROOT / name, tmp_path / name)
+    return tmp_path
+
+
+def _version(root: Path) -> str:
+    version = check_skill.versions(root)["SKILL.md metadata.version"]
+    assert version is not None
+    return version
+
+
+def _edit(path: Path, old: str, new: str) -> None:
+    text = path.read_text(encoding="utf-8")
+    assert old in text
+    path.write_text(text.replace(old, new, 1), encoding="utf-8")
+
+
+def _problems(root: Path, prefix: str, tag: str | None = None) -> list[str]:
+    return [p for p in check_skill.check(root, tag) if p.startswith(prefix)]
+
+
+def test_repository_passes() -> None:
+    assert check_skill.check(ROOT) == []
+
+
+def test_matching_tag_passes(tree: Path) -> None:
+    assert check_skill.check(tree, f"v{_version(tree)}") == []
+
+
+@pytest.mark.parametrize("tag", ["v9.9.9", "0.1.0", "v0.1.0rc1"])
+def test_wrong_tag_fails(tree: Path, tag: str) -> None:
+    assert _problems(tree, "tag:", tag)
+
+
+@pytest.mark.parametrize(
+    ("path", "old", "new", "prefix"),
+    [
+        ("CHANGELOG.md", "## {v} (", "## 0.0.9 (", "CHANGELOG.md's newest release"),
+        (".claude-plugin/plugin.json", '"version": "{v}"', '"version": "0.0.9"', ".claude-plugin"),
+        (SKILL, 'version: "{v}"', 'version: "0.0.9"', ".claude-plugin"),
+    ],
+)
+def test_a_stale_version_source_fails(
+    tree: Path, path: str, old: str, new: str, prefix: str
+) -> None:
+    _edit(tree / path, old.format(v=_version(tree)), new)
+    assert _problems(tree, prefix)
+
+
+def test_a_release_heading_without_a_date_fails(tree: Path) -> None:
+    # The release workflow reads the notes through the same parser, after the tag is pushed.
+    _edit(tree / "CHANGELOG.md", f"## {_version(tree)} (", f"## {_version(tree)}\n\n(")
+    assert _problems(tree, "CHANGELOG.md has no release notes")
+
+
+def test_a_release_with_empty_notes_fails(tree: Path) -> None:
+    changelog = tree / "CHANGELOG.md"
+    heading = next(
+        line
+        for line in changelog.read_text(encoding="utf-8").splitlines()
+        if line.startswith(f"## {_version(tree)} ")
+    )
+    changelog.write_text(f"# Changelog\n\n{heading}\n", encoding="utf-8")
+    assert _problems(tree, "CHANGELOG.md has no release notes")
+
+
+def test_a_second_skill_fails(tree: Path) -> None:
+    (tree / "nested").mkdir()
+    shutil.copy(tree / SKILL, tree / "nested" / "SKILL.md")
+    assert _problems(tree, "expected exactly one skill")
+
+
+def test_a_skill_at_the_root_fails(tree: Path) -> None:
+    # The Skills CLI copies the folder holding SKILL.md, so a root skill ships the whole repository.
+    (tree / SKILL).rename(tree / "SKILL.md")
+    assert _problems(tree, "expected exactly one skill")
+
+
+def test_a_renamed_skill_fails(tree: Path) -> None:
+    _edit(tree / SKILL, "name: reask", "name: re-ask")
+    assert _problems(tree, "SKILL.md name")
+
+
+def test_an_overlong_description_fails(tree: Path) -> None:
+    _edit(tree / SKILL, 'description: "', 'description: "' + "x" * 1024)
+    assert _problems(tree, "SKILL.md description is")
+
+
+def test_a_plugin_overriding_the_skills_directory_fails(tree: Path) -> None:
+    _edit(tree / ".claude-plugin/plugin.json", '"license"', '"skills": ["./"],\n  "license"')
+    assert _problems(tree, "plugin.json")
+
+
+def test_a_marketplace_pointing_elsewhere_fails(tree: Path) -> None:
+    _edit(tree / ".claude-plugin/marketplace.json", '"source": "./"', '"source": "./other"')
+    assert _problems(tree, "marketplace.json")
+
+
+def test_missing_frontmatter_fails(tree: Path) -> None:
+    (tree / SKILL).write_text("# reask\n", encoding="utf-8")
+    assert _problems(tree, "SKILL.md must begin with YAML frontmatter")
+
+
+def test_a_multiline_description_fails(tree: Path) -> None:
+    _edit(tree / SKILL, 'description: "', "description: >\n  ")
+    assert _problems(tree, "SKILL.md description must be one double-quoted line")
+
+
+def test_main_reports_success(capsys: pytest.CaptureFixture[str]) -> None:
+    assert check_skill.main([]) == 0
+    assert f"one version everywhere: {_version(ROOT)}" in capsys.readouterr().out
+
+
+def test_main_reports_each_problem_as_a_ci_error(
+    tree: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    assert check_skill.main(["--root", str(tree), "--tag", "v9.9.9"]) == 1
+    assert "::error::tag:" in capsys.readouterr().err
+
+
+def test_an_unreleased_section_above_the_release_is_allowed(tree: Path) -> None:
+    _edit(
+        tree / "CHANGELOG.md",
+        f"## {_version(tree)} (",
+        f"## Unreleased\n\n- Next.\n\n## {_version(tree)} (",
+    )
+    assert check_skill.check(tree) == []

reask-0.1.0/tests/test_cli.py

@@ -0,0 +1,187 @@
+import os
+from pathlib import Path
+
+import pytest
+
+from reask import skill_text
+from reask.cli import main
+
+
+def _installed(skills_dir: Path) -> Path:
+    return skills_dir / "reask" / "SKILL.md"
+
+
+def _symlink(link: Path, target: Path) -> None:
+    link.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        link.symlink_to(target, target_is_directory=target.is_dir())
+    except OSError:  # Windows without the symlink privilege
+        pytest.skip("cannot create symbolic links here")
+
+
+def test_install_writes_the_skill_byte_for_byte(tmp_path: Path) -> None:
+    assert main(["install", "--skills-dir", str(tmp_path)]) == 0
+    assert _installed(tmp_path).read_bytes() == skill_text().encode("utf-8")
+
+
+def test_install_is_idempotent_over_an_identical_copy(tmp_path: Path) -> None:
+    assert main(["install", "--skills-dir", str(tmp_path)]) == 0
+    assert main(["install", "--skills-dir", str(tmp_path)]) == 0
+
+
+def test_install_project_writes_under_the_working_directory(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.chdir(tmp_path)
+    assert main(["install", "--project"]) == 0
+    assert _installed(tmp_path / ".claude" / "skills").read_text(encoding="utf-8") == skill_text()
+
+
+def test_the_default_directory_follows_claude_config_dir(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(tmp_path / "config"))
+    assert main(["install"]) == 0
+    assert _installed(tmp_path / "config" / "skills").is_file()
+
+
+def test_the_default_directory_is_under_the_home_directory(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.delenv("CLAUDE_CONFIG_DIR", raising=False)
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+    assert main(["install"]) == 0
+    assert _installed(tmp_path / ".claude" / "skills").is_file()
+
+
+def test_a_quoted_tilde_in_skills_dir_means_home(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("USERPROFILE", str(tmp_path))
+    assert main(["install", "--skills-dir", "~/skills"]) == 0
+    assert _installed(tmp_path / "skills").is_file()
+
+
+def test_install_refuses_to_replace_an_edited_copy_without_force(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    target = _installed(tmp_path)
+    target.parent.mkdir()
+    target.write_text("local edits", encoding="utf-8")
+    assert main(["install", "--skills-dir", str(tmp_path)]) == 1
+    assert "pass --force to replace it" in capsys.readouterr().err
+    assert target.read_text(encoding="utf-8") == "local edits"
+    assert main(["install", "--skills-dir", str(tmp_path), "--force"]) == 0
+    assert target.read_text(encoding="utf-8") == skill_text()
+
+
+def test_a_directory_where_the_skill_goes_is_an_error_not_a_traceback(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    _installed(tmp_path).mkdir(parents=True)
+    assert main(["install", "--skills-dir", str(tmp_path), "--force"]) == 1
+    assert "is not a file" in capsys.readouterr().err
+
+
+def test_a_file_where_the_skills_directory_goes_is_an_error_not_a_traceback(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    (tmp_path / "file").write_text("", encoding="utf-8")
+    assert main(["install", "--skills-dir", str(tmp_path / "file")]) == 1
+    assert capsys.readouterr().err.startswith("reask: ")
+
+
+def test_uninstall_removes_the_skill_and_its_empty_folder(tmp_path: Path) -> None:
+    main(["install", "--skills-dir", str(tmp_path)])
+    assert main(["uninstall", "--skills-dir", str(tmp_path)]) == 0
+    assert not (tmp_path / "reask").exists()
+    assert main(["uninstall", "--skills-dir", str(tmp_path)]) == 1
+
+
+def test_uninstall_keeps_an_edited_copy_without_force(tmp_path: Path) -> None:
+    target = _installed(tmp_path)
+    target.parent.mkdir()
+    target.write_text("local edits", encoding="utf-8")
+    assert main(["uninstall", "--skills-dir", str(tmp_path)]) == 1
+    assert target.read_text(encoding="utf-8") == "local edits"
+    assert main(["uninstall", "--skills-dir", str(tmp_path), "--force"]) == 0
+    assert not target.parent.exists()
+
+
+def test_uninstall_never_deletes_files_it_did_not_write(tmp_path: Path) -> None:
+    main(["install", "--skills-dir", str(tmp_path)])
+    notes = tmp_path / "reask" / "NOTES.md"
+    notes.write_text("mine", encoding="utf-8")
+    assert main(["uninstall", "--skills-dir", str(tmp_path), "--force"]) == 0
+    assert not _installed(tmp_path).exists()
+    assert notes.read_text(encoding="utf-8") == "mine"
+
+
+@pytest.mark.parametrize("command", ["install", "uninstall"])
+@pytest.mark.parametrize("linked", [".claude", ".claude/skills", ".claude/skills/reask"])
+def test_project_commands_refuse_a_linked_folder(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    command: str,
+    linked: str,
+) -> None:
+    # A cloned repository can ship any of these folders as a link out of the project.
+    outside = tmp_path / "outside"
+    (outside / "skills" / "reask").mkdir(parents=True)
+    (outside / "skills" / "reask" / "SKILL.md").write_text(skill_text(), encoding="utf-8")
+    (outside / "skills" / "reask" / "other").write_text("keep", encoding="utf-8")
+    project = tmp_path / "project"
+    depth = linked.count("/")
+    _symlink(project / linked, outside / ["", "skills", "skills/reask"][depth])
+    monkeypatch.chdir(project)
+    assert main([command, "--project", "--force"]) == 1
+    assert "symbolic link" in capsys.readouterr().err
+    assert sorted(p.name for p in (outside / "skills" / "reask").iterdir()) == ["SKILL.md", "other"]
+
+
+@pytest.mark.parametrize("dangling", [False, True])
+def test_install_refuses_a_linked_skill_file(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, dangling: bool
+) -> None:
+    victim = tmp_path / "home" / ".zshrc"
+    victim.parent.mkdir()
+    if not dangling:
+        victim.write_text("export PATH", encoding="utf-8")
+    _symlink(tmp_path / "project" / ".claude" / "skills" / "reask" / "SKILL.md", victim)
+    monkeypatch.chdir(tmp_path / "project")
+    assert main(["install", "--project", "--force"]) == 1
+    assert victim.exists() is not dangling
+    if not dangling:
+        assert victim.read_text(encoding="utf-8") == "export PATH"
+
+
+def test_a_skills_cli_install_is_left_to_the_skills_cli(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    # `npx skills add` for several agents links ~/.claude/skills/reask to one shared folder.
+    shared = tmp_path / "agents" / "reask"
+    shared.mkdir(parents=True)
+    (shared / "SKILL.md").write_text(skill_text(), encoding="utf-8")
+    _symlink(tmp_path / "claude" / "reask", shared)
+    assert main(["uninstall", "--skills-dir", str(tmp_path / "claude")]) == 1
+    assert "manage it with that tool" in capsys.readouterr().err
+    assert (shared / "SKILL.md").is_file()
+
+
+def test_print_writes_the_skill_as_utf8_bytes(capsysbinary: pytest.CaptureFixture[bytes]) -> None:
+    assert main(["print"]) == 0
+    assert capsysbinary.readouterr().out == skill_text().encode("utf-8")
+
+
+def test_the_symlink_check_does_not_follow_links_above_the_named_directory(
+    tmp_path: Path,
+) -> None:
+    # A dotfiles setup often links ~/.claude itself; that is the user's choice, not a trap.
+    real = tmp_path / "dotfiles" / "claude"
+    real.mkdir(parents=True)
+    _symlink(tmp_path / "home" / ".claude", real)
+    assert main(["install", "--skills-dir", str(tmp_path / "home" / ".claude" / "skills")]) == 0
+    assert _installed(real / "skills").is_file()
+    assert os.path.islink(tmp_path / "home" / ".claude")

reask-0.1.0/tests/test_release_artifacts.py

@@ -0,0 +1,62 @@
+import zipfile
+from pathlib import Path
+
+import pytest
+
+from scripts import release_notes, skill_zip
+
+ROOT = Path(__file__).resolve().parent.parent
+
+CHANGELOG = """# Changelog
+
+## Unreleased
+
+- Next.
+
+## 0.2.0 (2026-10-01)
+
+- Second.
+
+## 0.1.0 (2026-09-29)
+
+- First.
+"""
+
+
+def test_latest_is_the_first_release_heading() -> None:
+    assert release_notes.latest(CHANGELOG) == "0.2.0"
+    assert release_notes.latest("# Changelog\n\n## Unreleased\n") is None
+
+
+def test_notes_are_the_section_body_without_its_heading() -> None:
+    assert release_notes.notes(CHANGELOG, "0.2.0") == "- Second."
+    assert release_notes.notes(CHANGELOG, "0.1.0") == "- First."
+
+
+@pytest.mark.parametrize("version", ["0.3.0", "0.1", "Unreleased"])
+def test_notes_for_anything_but_a_release_are_none(version: str) -> None:
+    assert release_notes.notes(CHANGELOG, version) is None
+
+
+def test_a_heading_at_the_end_of_the_file_is_no_release() -> None:
+    assert release_notes.notes("## 0.1.0 (2026-09-29)", "0.1.0") is None
+
+
+def test_release_notes_main_prints_or_refuses(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    changelog = tmp_path / "CHANGELOG.md"
+    changelog.write_text(CHANGELOG, encoding="utf-8")
+    assert release_notes.main(["v0.2.0", "--changelog", str(changelog)]) == 0
+    assert capsys.readouterr().out.strip() == "- Second."
+    assert release_notes.main(["v9.9.9", "--changelog", str(changelog)]) == 1
+    assert "::error::" in capsys.readouterr().err
+
+
+def test_skill_zip_holds_the_skill_folder_and_licence(tmp_path: Path) -> None:
+    destination = tmp_path / "out" / "reask-skill.zip"
+    assert skill_zip.main([str(destination)]) == 0
+    with zipfile.ZipFile(destination) as archive:
+        assert archive.namelist() == ["reask/LICENSE", "reask/SKILL.md"]
+        assert archive.read("reask/SKILL.md") == (ROOT / "skills/reask/SKILL.md").read_bytes()
+        assert archive.read("reask/LICENSE") == (ROOT / "LICENSE").read_bytes()