reask 0.1.0__py3-none-any.whl

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/__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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+reask/__init__.py,sha256=5vdgnBNeGP1kwypjf7Qv9eOjNt20-CHsI3UMyXRurws,716
+reask/cli.py,sha256=HClhYjzlQe93OAkNuNyMIKn1W8pIkt9cP8WeYT_045M,4557
+reask/SKILL.md,sha256=lnz0A70v_Bv79MQyD3swgxMnx6W_PiGS24OidpnR0jk,5207
+reask-0.1.0.dist-info/METADATA,sha256=NflQmL3xZiJhk3BDr2JOmtfCkU45ZZiJpsBve9pGAt0,6240
+reask-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+reask-0.1.0.dist-info/entry_points.txt,sha256=H2C4TvGhWmgAR7bbSqmB2vuX7wxK9ujRoxDkWNepuXw,41
+reask-0.1.0.dist-info/licenses/LICENSE,sha256=UfUIUnkfCOqg0V5JlJDIQbuBiJBWFKQJiWWnbztpfS8,1074
+reask-0.1.0.dist-info/RECORD,,

reask-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

reask-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+reask = reask.cli:main

reask-0.1.0.dist-info/licenses/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.