help2skill 0.1.0__py3-none-any.whl

help2skill-0.1.0.dist-info/METADATA

@@ -0,0 +1,206 @@
+Metadata-Version: 2.5
+Name: help2skill
+Version: 0.1.0
+Summary: Make Python CLIs ready for LLM agents: --llms output, SKILL.md generation and drift checks for Click, Typer and argparse.
+Project-URL: Homepage, https://github.com/huysonmind/help2skill
+Project-URL: Issues, https://github.com/huysonmind/help2skill/issues
+Project-URL: Changelog, https://github.com/huysonmind/help2skill/blob/main/CHANGELOG.md
+Author-email: huysonmind <350970572+huysonmind@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-skills,agents,argparse,cli,click,llm,llms-txt,skill-md,typer
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# help2skill
+
+> **Status: alpha.** The output format may still change before 1.0.
+
+`--help` for LLM agents. Make a Click, Typer or argparse CLI easy for coding agents
+(Claude Code, Codex, Cursor, Gemini CLI…) to use correctly:
+
+- **`--llms` flag**: prints a compact Markdown reference of the command tree (every
+  subcommand, argument, option, choice, default and env var), generated from the CLI
+  itself, so it never goes stale.
+- **`SKILL.md` export**: writes an [Agent Skills](https://agentskills.io) file whose
+  reference block is regenerated from the CLI while your hand-written guidance is kept.
+- **Drift check for CI**: fails when the generated block is stale, or when hand-written
+  examples mention a subcommand or option that does not exist (or an option placed at
+  the wrong level, e.g. a group option after the subcommand).
+
+No runtime dependencies. Works with Typer ≥ 0.26 (vendored Click), where code that does
+`isinstance(cmd, click.Group)` silently finds nothing.
+
+## Quick start
+
+### Click
+
+```python
+import click
+from help2skill.click import llms_option
+
+
+@click.group()
+@llms_option()
+def cli(): ...
+```
+
+```console
+$ mytool --llms
+```
+
+`llms_option()` adds the flag to the root only, which prints the whole tree. To get
+`--llms` on every subcommand too (`mytool db --llms` prints just that subtree):
+
+```python
+from help2skill.click import add_llms_option
+
+add_llms_option(cli)
+```
+
+### Typer
+
+Root flag, no change to your entry point:
+
+```python
+import typer
+from help2skill.typer import LlmsOption
+
+app = typer.Typer()
+
+
+@app.callback()
+def main(llms: LlmsOption = False): ...
+```
+
+Or `--llms` at every level: build the command once and make it your console script.
+
+```python
+# mytool/cli.py
+import help2skill.typer
+
+main = help2skill.typer.command(app, name="mytool")
+```
+
+```toml
+# pyproject.toml
+[project.scripts]
+mytool = "mytool.cli:main"
+```
+
+No `click` package is needed with Typer ≥ 0.26, which ships its own copy.
+
+### argparse
+
+argparse has no hook for an extra flag, so use the command line (or the Python API):
+
+```console
+$ help2skill markdown mytool.cli:parser
+$ help2skill markdown "mytool.cli:build_parser()"   # a function that returns the parser
+```
+
+### Large CLIs
+
+`--llms` prints the full reference when it fits in 20,000 characters (about 5k tokens).
+Above that it prints the top-level help plus an index of every command, and tells the
+agent how to ask for one command (`mytool <command> --llms`, or `--help` when only the
+root has the flag). Set `HELP2SKILL_LLMS_MAX_CHARS=0` for everything. Options repeated
+identically in three or more commands are described once, under "Shared options".
+
+### Lazy commands
+
+Click's documented `LazyGroup` pattern works as is. Placeholder commands with a
+`materialize()` method are loaded automatically; for anything else pass
+`resolve=` (Python API) or `--resolve module:func` (command line).
+
+## SKILL.md and drift checks
+
+```console
+$ help2skill skill mytool.cli:app --name mytool --description "Use mytool to ..." \
+    -o src/mytool/.agents/skills/mytool/SKILL.md
+$ help2skill check mytool.cli:app src/mytool/.agents/skills/mytool/SKILL.md
+```
+
+`skill` creates the file, or refreshes only the block between
+`<!-- help2skill:begin … -->` and `<!-- help2skill:end -->` if it already exists
+(`--name` is then optional). Write your own guidance above or below the block.
+
+**Program name.** Commands are written with the name users type. help2skill uses
+`--program` if given, else the installed console script that points at the target,
+else the CLI's own name (`@click.group(name="mytool")`, `ArgumentParser(prog="mytool")`),
+else the skill name. `markdown` warns when it can only guess.
+
+**Settings are stored in the file.** The begin marker records the program name,
+`--max-chars` and `--hide-default`, so `check`, a refresh and the pytest helper reuse
+them without repeating any option.
+
+**Stable in CI.** The output does not depend on the machine or on the Click/Typer
+version: commands are sorted, type names are normalised and your home directory is
+written as `~` (other machine-specific paths trigger a warning). A default computed at
+run time (CPU count, today's date) would still differ, so leave it out:
+
+```console
+$ help2skill skill mytool.cli:app -o SKILL.md --hide-default workers --hide-default --since
+```
+
+When the reference is longer than 30,000 characters, `SKILL.md` keeps an index and the
+full reference goes to `references/commands.md` beside it (fully generated; agents read
+it on demand). Change the limit with `--max-chars` (0 = never split).
+
+**What the check catches** in code spans and fenced blocks of your hand-written text:
+unknown subcommands and options (with "did you mean"), options at the wrong level,
+values not among an option's or argument's choices, values given to flags, and
+single-letter clusters such as `-fq`. Lines continued with `\` are joined, and lines
+are recognised with launchers in front: `uv run [--with …] mytool …`, `uvx`,
+`pipx run`, `poetry run`, `python -m mytool`, `VAR=value mytool …`.
+
+Shipping the skill inside your package under `.agents/skills/<name>/` makes it
+installable with [library-skills](https://github.com/tiangolo/library-skills). With
+setuptools, add the folder to `package-data`; hatchling includes it by default.
+
+In pytest (build the path from `__file__` so the test runs from any directory):
+
+```python
+from pathlib import Path
+
+from help2skill.testing import assert_skill_in_sync
+from mytool.cli import app
+
+SKILL = Path(__file__).parents[1] / "src/mytool/.agents/skills/mytool/SKILL.md"
+
+
+def test_skill_in_sync():
+    assert_skill_in_sync(app, SKILL)
+```
+
+With a `src/` layout that is not installed, pass `--app-dir src` to the command line.
+
+## Python API
+
+```python
+import help2skill
+
+tree = help2skill.introspect(app, "mytool")  # Click, Typer or argparse
+print(help2skill.render_markdown(tree))
+help2skill.write_skill(app, "SKILL.md", name="mytool")
+problems = help2skill.check_skill_file(app, "SKILL.md")
+```
+
+## Security
+
+`help2skill` imports the module you point it at, the same as running your CLI. It calls
+a function only when you write `module:func()` or the function's name contains
+"parser"; it never calls your `main()`. Generated files copy your help text verbatim, so review them
+for machine-specific values before committing. See [SECURITY.md](https://github.com/huysonmind/help2skill/blob/main/SECURITY.md).
+
+## License
+
+[MIT](https://github.com/huysonmind/help2skill/blob/main/LICENSE). Built with AI assistance (Claude).

help2skill-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+help2skill/__init__.py,sha256=Bqc3NtdXN1EqOc2cqps5b9AWZwu1f969MlNJ8a9-Xuw,8687
+help2skill/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+help2skill/_argparse.py,sha256=x58Yc7Dzc9WRp4e64JpsyXfvP3jLe_r-6l5K4xhWWrM,6262
+help2skill/_click.py,sha256=BbpK2BercOkat9Y98m_F7vGxXBg2u5-3huO8dCcug94,8945
+help2skill/cli.py,sha256=0Fn6nmtFLq1TEIBWPdwJ7JdwqaAxaZr9KQmkZDGf6qE,10030
+help2skill/click.py,sha256=0TWSFvzgY2d2SXpoG9TjdV5kdPzj1K5wnykF0mbLmcw,2968
+help2skill/model.py,sha256=aVmDl-fp4EtZSC8bxpswSedduxDlmnQi2TvOzXbjD54,3021
+help2skill/privacy.py,sha256=OdeL59R2E7ltWaPug0Z0u3SkMpy_dHhRYqPKym1YKLM,1234
+help2skill/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+help2skill/render.py,sha256=hZpruGwot5pjoOzCUh_flTpCpPVpCFb0AnlAgj6ZfWs,9933
+help2skill/sync.py,sha256=0Jccq8UHNrCH-gJ1uVp5eFybQNTdlAG9PsMLdR0-VAA,17391
+help2skill/testing.py,sha256=66f0LeEyihN9a0FnMbIWIPHq0fDzedXGD8h-amVhwPs,1235
+help2skill/typer.py,sha256=dieYYFdtz14qPevPrrs0TBOpvt9Z3UaCsZq1OzOYpyE,1034
+help2skill-0.1.0.dist-info/METADATA,sha256=UBLJ2RqGsxVjIadNRPEiKo_BIkb4l3RZ4k_QAzOaPpQ,7569
+help2skill-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+help2skill-0.1.0.dist-info/entry_points.txt,sha256=ozWOfUQCiT1o6LodAg9x8Z6Bwoh4u8-HXHowgi_wbCk,51
+help2skill-0.1.0.dist-info/licenses/LICENSE,sha256=6sVsij8RLQMer7EYynJVovhnk1ESme1Eh5KokDX0Gg8,1067
+help2skill-0.1.0.dist-info/RECORD,,

help2skill-0.1.0.dist-info/WHEEL

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

help2skill-0.1.0.dist-info/entry_points.txt

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

help2skill-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 huysonmind
+
+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.