Merge branch 'main' into copilot/add-no-hook-flag-to-tools

nathanjmcdougall · web-flow · commit e71e9a56aade · 2026-03-27T16:57:40.000+13:00
diff --git a/.agents/skills/usethis-cli-modify/SKILL.md b/.agents/skills/usethis-cli-modify/SKILL.md
@@ -4,7 +4,7 @@ description: Modify the usethis CLI layer (commands, options, help text) and kee
 compatibility: usethis, Python, typer, markdown
 license: MIT
 metadata:
-  version: "1.0"
+  version: "1.1"
 ---
 
 # Modifying the CLI
@@ -34,6 +34,20 @@ After making CLI changes, review and update each of the following as needed:
 
 The command reference page documents every command with its full description, supported options, and behavior. Update it to match any changes you made to commands, options, defaults, or descriptions.
 
+Keep descriptions **factual and concise**. The reference is not the place for extended rationale, usage tips, or explanations of why an option exists. If important context is needed, put it in a separate documentation page and link to it from the reference.
+
+Good — factual, concise:
+
+```markdown
+- `--output-file` to write the output to a file instead of stdout.
+```
+
+Bad — excessive rationale embedded in the reference:
+
+```markdown
+- `--output-file` to write the output to a file instead of stdout. This is useful to avoid issues when shell redirects (e.g. `> file.txt`) create the file before the command runs, which can influence the behaviour of `usethis show`.
+```
+
 ### Command overview
 
 The command overview page lists all commands organized by category with brief descriptions. Update it if you added, removed, renamed, or recategorized a command.
diff --git a/.agents/skills/usethis-qa-static-checks/SKILL.md b/.agents/skills/usethis-qa-static-checks/SKILL.md
@@ -4,7 +4,7 @@ description: Perform static code checks
 compatibility: usethis, Python, prek, basedpyright
 license: MIT
 metadata:
-  version: "1.4"
+  version: "1.5"
 ---
 
 # Static Checks
@@ -21,3 +21,7 @@ Note that we are interested in both errors and warnings from these tools - we sh
 ## When to run these checks
 
 Before submitting changes for review, **always** run these static checks. This should be done every time, even for small changes, to avoid slowing down the code review process unnecessarily.
+
+## What to do when prek checks fail
+
+It's quite common for minor cosmetic changes to be made automatically when running the prek checks, even by linters such as Ruff and mkdownlint-cli2. Since auto-fixes may have been applied during the first run, if checks fail, you should re-run a second time to see if any issues remain. Only then should you proceed to fix any remaining issues manually.
diff --git a/.agents/skills/usethis-skills-external-add/SKILL.md b/.agents/skills/usethis-skills-external-add/SKILL.md
@@ -4,7 +4,7 @@ description: Add an external (community) skill to the project from a third-party
 compatibility: usethis, agent skills, npx, markdown
 license: MIT
 metadata:
-  version: "1.1"
+  version: "1.2"
 ---
 
 # Adding External Skills
@@ -14,10 +14,10 @@ External skills are sourced from third-party repositories rather than written lo
 ## Procedure
 
 1. Set the line-ending environment variables (see "Line endings and reproducible hashes" below).
-2. Install the skills using `npx skills add <source> --skill '*' --agent github-copilot --yes` (e.g. `npx skills add CodSpeedHQ/codspeed --skill '*' --agent github-copilot --yes`).
+2. Install the skill(s) — see "Installing the skill" below for the correct `--skill` flag.
 3. Note the skill name(s) added to `skills-lock.json`.
 4. Add each new skill to the external skills registry in `AGENTS.md`.
-5. Verify the hook passes: `python hooks/check-skills-documented.py`.
+5. Verify the hook passes: `uv run prek check-skills-documented`.
 
 ## Line endings and reproducible hashes
 
@@ -29,13 +29,19 @@ Due to a [bug in the skills CLI](https://github.com/vercel-labs/skills/issues/78
 
 ## Installing the skill
 
-To **add a new** external skill, run from the repository root (with the line-ending environment variables set as described above):
+To **add a specific skill** from a source, run from the repository root (with the line-ending environment variables set as described above):
+
+```commandline
+npx skills add <github-org>/<repo> --skill '<skill-name>' --agent github-copilot --yes
+```
+
+To **add all skills** from a source (only when you want every skill the source offers):
 
 ```commandline
 npx skills add <github-org>/<repo> --skill '*' --agent github-copilot --yes
 ```
 
-This adds the skill entry to `skills-lock.json`. Multiple skills may be added from a single source.
+**Warning:** `--skill '*'` installs _every_ skill from the source repository, which can be hundreds of unwanted skills. Always prefer `--skill '<skill-name>'` unless you genuinely want all of them.
 
 ## Documenting in AGENTS.md
 
diff --git a/AGENTS.md b/AGENTS.md
@@ -43,14 +43,20 @@ The `.agents/skills` directory contains agent skills.
 
 External skills can be installed if they are not present — see the `usethis-skills-external-install` skill.
 
-| Skill                    | Source                | Description                                                             |
-| ------------------------ | --------------------- | ----------------------------------------------------------------------- |
-| `codspeed-optimize`      | `CodSpeedHQ/codspeed` | Optimize code for performance using CodSpeed benchmarks and flamegraphs |
-| `codspeed-setup-harness` | `CodSpeedHQ/codspeed` | Set up performance benchmarks and the CodSpeed harness for a project    |
+| Skill                    | Source                | Description                                                                           |
+| ------------------------ | --------------------- | ------------------------------------------------------------------------------------- |
+| `codspeed-optimize`      | `CodSpeedHQ/codspeed` | Optimize code for performance using CodSpeed benchmarks and flamegraphs               |
+| `codspeed-setup-harness` | `CodSpeedHQ/codspeed` | Set up performance benchmarks and the CodSpeed harness for a project                  |
+| `find-skills`            | `vercel-labs/skills`  | Discover and install agent skills from the open skills ecosystem for new capabilities |
 
 ### Important Instructions about Skills usage
 
 - ALWAYS use possibly relevant agent skills when they are available. Eagerly use skills, if in doubt, assume a skill is relevant.
+- ALWAYS use `find-skills` to research new skill capabilities if there are difficult tasks, tasks in an unfamiliar domain, if you believe there is a lack of clarity or direction around precisely how to proceed, or if you get stuck or find something surprisingly challenging. When using this skill, please be sure to use the `usethis-skills-external-install` skill when deciding to install a new external skill.
 - ALWAYS consider the `usethis-qa-static-checks` to be relevant: if you think your task
   is complete, always run this skill to check for any issues before finishing.
 - ALWAYS mention which skills you've used after completing any task, in PR descriptions, and comments.
+
+## Lessons
+
+When you are working on a problem, you are almost always going to encounter a difficulty. This is great - it's an opportunity for learning. ALWAYS make a note explicitly of what lessons you are drawing as you complete a task or when receiving user feedback. Try and keep this structured: consider the root cause of the difficulty, and how you overcame it. After finishing work on a task, report back all your lessons. Finally, try and update the relevant skills with any new insights you've drawn, to help future agents, and/or create a new skill.
diff --git a/docs/cli/reference.md b/docs/cli/reference.md
@@ -457,7 +457,28 @@ Currently supported subcommands:
 
 - `usethis show backend` to show the inferred project manager backend, e.g. 'uv' or 'none'. This is the default backend used, i.e. when `--backend=auto` is specified.
 - `usethis show name` to show the name of the project.
-- `usethis show sonarqube` to show appropriate contents of a `sonar-projects.properties` file for SonarQube analysis.
+- `usethis show sonarqube` to show appropriate contents of a `sonar-project.properties` file for SonarQube analysis.
+
+### `usethis show sonarqube`
+
+Show the contents of a `sonar-project.properties` file for SonarQube analysis.
+
+If a `sonar-project.properties` file already exists in the project root, its contents are returned as-is. In this case, the `--project-key` option and `tool.usethis.sonarqube.project-key` in `pyproject.toml` are both ignored.
+
+If no `sonar-project.properties` file exists, the contents are constructed from `pyproject.toml` configuration. In this case, a project key is required:
+
+- If `--project-key` is provided, it is used.
+- Otherwise, `tool.usethis.sonarqube.project-key` from `pyproject.toml` is used.
+
+Additional configuration in `pyproject.toml`:
+
+- `tool.usethis.sonarqube.verbose` (bool, default `false`) — sets `sonar.verbose`.
+- `tool.usethis.sonarqube.exclusions` (list of strings, default `[]`) — sets `sonar.exclusions`.
+- `tool.coverage.xml.output` (string, required) — sets `sonar.python.coverage.reportPaths`.
+
+Supported options:
+
+- `--output-file` to write the output to a file instead of stdout.
 
 ## `usethis browse pypi <package>`
 
diff --git a/skills-lock.json b/skills-lock.json
@@ -10,6 +10,11 @@
       "source": "CodSpeedHQ/codspeed",
       "sourceType": "github",
       "computedHash": "587a58bc7498635347ee7a7eba66ac17c75430db7543be4af7eaab74533a6714"
+    },
+    "find-skills": {
+      "source": "vercel-labs/skills",
+      "sourceType": "github",
+      "computedHash": "d31e234f0c90694a670222cdd1dafa853e051d7066beda389f1097c22dadd461"
     }
   }
 }
diff --git a/src/usethis/_core/show.py b/src/usethis/_core/show.py
@@ -1,18 +1,36 @@
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 from usethis._backend.dispatch import get_backend
 from usethis._console import plain_print
 from usethis._integrations.project.name import get_project_name
 from usethis._integrations.sonarqube.config import get_sonar_project_properties
 
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def show_backend(*, output_file: Path | None = None) -> None:
+    _output(get_backend().value, output_file=output_file)
+
 
-def show_backend() -> None:
-    plain_print(get_backend().value)
+def show_name(*, output_file: Path | None = None) -> None:
+    _output(get_project_name(), output_file=output_file)
 
 
-def show_name() -> None:
-    plain_print(get_project_name())
+def show_sonarqube_config(
+    *, project_key: str | None = None, output_file: Path | None = None
+) -> None:
+    _output(
+        get_sonar_project_properties(project_key=project_key), output_file=output_file
+    )
 
 
-def show_sonarqube_config(*, project_key: str | None = None) -> None:
-    plain_print(get_sonar_project_properties(project_key=project_key))
+def _output(content: str, *, output_file: Path | None = None) -> None:
+    if output_file is not None:
+        if not content.endswith("\n"):
+            content += "\n"
+        output_file.write_text(content, encoding="utf-8")
+    else:
+        plain_print(content)
diff --git a/src/usethis/_ui/interface/show.py b/src/usethis/_ui/interface/show.py
@@ -1,7 +1,9 @@
+from pathlib import Path
+
 import typer
 
 from usethis._config import usethis_config
-from usethis._ui.options import offline_opt, quiet_opt
+from usethis._ui.options import offline_opt, output_file_opt, quiet_opt
 
 app = typer.Typer(
     help="Show information about the current project.", add_completion=False
@@ -19,6 +21,7 @@
 def backend(
     offline: bool = offline_opt,
     quiet: bool = quiet_opt,
+    output_file: Path | None = output_file_opt,
 ) -> None:
     from usethis._config_file import files_manager
     from usethis._console import err_print
@@ -27,7 +30,7 @@ def backend(
 
     with usethis_config.set(offline=offline, quiet=quiet), files_manager():
         try:
-            show_backend()
+            show_backend(output_file=output_file)
         except UsethisError as err:
             err_print(err)
             raise typer.Exit(code=1) from None
@@ -37,6 +40,7 @@ def backend(
 def name(
     offline: bool = offline_opt,
     quiet: bool = quiet_opt,
+    output_file: Path | None = output_file_opt,
 ) -> None:
     from usethis._config_file import files_manager
     from usethis._console import err_print
@@ -45,7 +49,7 @@ def name(
 
     with usethis_config.set(offline=offline, quiet=quiet), files_manager():
         try:
-            show_name()
+            show_name(output_file=output_file)
         except UsethisError as err:
             err_print(err)
             raise typer.Exit(code=1) from None
@@ -59,6 +63,7 @@ def sonarqube(
     offline: bool = offline_opt,
     quiet: bool = quiet_opt,
     project_key: str | None = project_key_opt,
+    output_file: Path | None = output_file_opt,
 ) -> None:
     from usethis._config_file import files_manager
     from usethis._console import err_print
@@ -67,7 +72,7 @@ def sonarqube(
 
     with usethis_config.set(offline=offline, quiet=quiet), files_manager():
         try:
-            show_sonarqube_config(project_key=project_key)
+            show_sonarqube_config(project_key=project_key, output_file=output_file)
         except UsethisError as err:
             err_print(err)
             raise typer.Exit(code=1) from None
diff --git a/src/usethis/_ui/options.py b/src/usethis/_ui/options.py
@@ -109,6 +109,13 @@
 # status command options
 status_arg = typer.Argument(default=..., help="Docstring style to enforce.")
 
+# show command options
+output_file_opt = typer.Option(
+    None,
+    "--output-file",
+    help="Write output to this file instead of stdout.",
+)
+
 # ruff command options
 linter_opt = typer.Option(
     True,
diff --git a/tests/usethis/_ui/interface/test_show.py b/tests/usethis/_ui/interface/test_show.py
@@ -32,6 +32,22 @@ def test_none_backend(self, tmp_path: Path):
         assert result.exit_code == 0, result.output
         assert result.output == "none\n"
 
+    def test_output_file(self, tmp_path: Path):
+        # Arrange
+        (tmp_path / "uv.lock").touch()
+        output_file = tmp_path / "backend.txt"
+
+        # Act
+        runner = CliRunner()
+        with change_cwd(tmp_path):
+            result = runner.invoke_safe(
+                app, ["backend", "--output-file", str(output_file)]
+            )
+
+        # Assert
+        assert result.exit_code == 0, result.output
+        assert output_file.read_text(encoding="utf-8") == "uv\n"
+
 
 class TestName:
     def test_output(self, tmp_path: Path):
@@ -60,6 +76,23 @@ def test_invalid_pyproject(self, tmp_path: Path):
         # Assert
         assert result.exit_code == 1, result.output
 
+    def test_output_file(self, tmp_path: Path):
+        # Arrange
+        path = tmp_path / "fun"
+        path.mkdir()
+        output_file = path / "name.txt"
+
+        # Act
+        runner = CliRunner()
+        with change_cwd(path):
+            result = runner.invoke_safe(
+                app, ["name", "--output-file", str(output_file)]
+            )
+
+        # Assert
+        assert result.exit_code == 0, result.output
+        assert output_file.read_text(encoding="utf-8") == "fun\n"
+
 
 class TestSonarqube:
     def test_runs(self, tmp_path: Path):
@@ -162,3 +195,64 @@ def test_invalid_pyproject(self, tmp_path: Path):
 
         # Assert
         assert result.exit_code == 1, result.output
+
+    def test_output_file(self, tmp_path: Path):
+        # Arrange
+        (tmp_path / "pyproject.toml").write_text(
+            """
+[tool.usethis.sonarqube]
+project-key = "fun"
+
+[tool.coverage.xml.output]
+"""
+        )
+        output_file = tmp_path / "sonar-project.properties"
+
+        # Act
+        runner = CliRunner()
+        with change_cwd(tmp_path):
+            result = runner.invoke_safe(
+                app, ["sonarqube", "--output-file", str(output_file)]
+            )
+
+        # Assert
+        assert result.exit_code == 0, result.output
+        content = output_file.read_text(encoding="utf-8")
+        assert "sonar.projectKey=fun" in content
+
+    def test_output_file_not_detected_as_existing(self, tmp_path: Path):
+        """Using --output-file avoids the redirect problem.
+
+        When using shell redirect (`> file`), the file is created empty before
+        the command runs, which causes sonarqube to read that empty file.
+        With --output-file, the file is written after generation.
+        """
+        # Arrange
+        (tmp_path / "pyproject.toml").write_text(
+            """
+[tool.usethis.sonarqube]
+project-key = "fun"
+
+[tool.coverage.xml.output]
+"""
+        )
+        # Simulate what happens with shell redirect: an empty file pre-exists
+        output_file = tmp_path / "sonar-project.properties"
+        output_file.write_text("", encoding="utf-8")
+
+        # Act
+        # Despite sonar-project.properties existing (empty), --output-file
+        # still causes the config to be read from that file (by design of
+        # get_sonar_project_properties), then overwrites it with that content.
+        runner = CliRunner()
+        with change_cwd(tmp_path):
+            result = runner.invoke_safe(
+                app, ["sonarqube", "--output-file", str(output_file)]
+            )
+
+        # Assert
+        assert result.exit_code == 0, result.output
+        content = output_file.read_text(encoding="utf-8")
+        # With --output-file, the file is written after content generation,
+        # so even if it was previously empty, it will have the content now
+        assert content != ""

Original file line number	Diff line number	Diff line change
`@@ -10,6 +10,11 @@`
`10`	`10`	`"source": "CodSpeedHQ/codspeed",`
`11`	`11`	`"sourceType": "github",`
`12`	`12`	`"computedHash": "587a58bc7498635347ee7a7eba66ac17c75430db7543be4af7eaab74533a6714"`
	`13`	`+ },`
	`14`	`+ "find-skills": {`
	`15`	`+ "source": "vercel-labs/skills",`
	`16`	`+ "sourceType": "github",`
	`17`	`+ "computedHash": "d31e234f0c90694a670222cdd1dafa853e051d7066beda389f1097c22dadd461"`
`13`	`18`	`}`
`14`	`19`	`}`
`15`	`20`	`}`