help2skill 0.1.0__tar.gz

help2skill-0.1.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: monthly

help2skill-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run mypy
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        deps: ["latest"]
+        include:
+          # Oldest supported Click/Typer (before Typer vendored Click).
+          - { os: ubuntu-latest, python: "3.10", deps: "click==8.1.7 typer==0.12.5" }
+          # Typer just after vendoring Click.
+          - { os: ubuntu-latest, python: "3.12", deps: "click==8.2.1 typer==0.26.0" }
+          - { os: windows-latest, python: "3.13", deps: "latest" }
+          - { os: macos-latest, python: "3.13", deps: "latest" }
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Test
+        shell: bash
+        run: |
+          if [ "${{ matrix.deps }}" = "latest" ]; then
+            uv run --group dev pytest --cov=help2skill --cov-report=term-missing
+          else
+            uv run --no-dev --with pytest $(printf -- '--with %s ' ${{ matrix.deps }}) pytest
+          fi

help2skill-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,53 @@
+name: Publish
+
+# Runs when a GitHub release is published. Uses PyPI trusted publishing:
+# configure the "pypi" environment and the trusted publisher on pypi.org first.
+#
+# PyPI never accepts the same version twice, so nothing is uploaded unless the
+# checks pass and the release tag (e.g. v0.1.0) matches the package version.
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - name: Lint and test
+        run: |
+          uv run --locked ruff check .
+          uv run --locked ruff format --check .
+          uv run --locked mypy
+          uv run --locked pytest -q
+      - run: uv build
+      - name: Release tag must match the package version
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          version="${TAG#v}"
+          if [ ! -f "dist/help2skill-${version}-py3-none-any.whl" ]; then
+            echo "::error::Release tag '$TAG' does not match the built package: $(ls dist)"
+            exit 1
+          fi
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

help2skill-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.coverage
+.mypy_cache/
+.ruff_cache/

help2skill-0.1.0/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes are listed here. The generated Markdown format is part of the
+public interface: any change to it is called out under **Output**.
+
+## Unreleased
+
+## 0.1.0 (2026-11-07)
+- Introspect Click, Typer (including Typer ≥ 0.26 with vendored Click) and argparse
+  into one model.
+- `render_markdown`, `render_skill` (Agent Skills frontmatter validation).
+- `--llms` flag: Click decorator, `add_llms_option`, Typer `LlmsOption` and
+  `help2skill.typer.command`.
+- Drift check: stale generated block, unknown subcommands/options and options at the
+  wrong level in hand-written examples; default-command groups.
+- `help2skill` command (`markdown`, `skill`, `check`) and
+  `help2skill.testing.assert_skill_in_sync`.
+- Large CLIs: `--llms` falls back to an index above 20,000 characters
+  (`HELP2SKILL_LLMS_MAX_CHARS`); `SKILL.md` splits the full reference into
+  `references/commands.md` above 30,000 characters (`--max-chars`).
+- Drift check understands `uv run`, `uvx`, `uv tool run`, `pipx run`, `poetry run`,
+  `pdm run`, `hatch run`, `rye run`, `python -m` and `VAR=value` prefixes.
+- Home directory written as `~` in generated files; warning for other
+  machine-specific paths.
+- Lazy commands: `materialize()` placeholders resolved by default; `resolve=` /
+  `--resolve` for custom patterns.
+- Changes from testing as a new user, before the first release:
+  - Typer integration works without the `click` package (Typer ≥ 0.26).
+  - **Output**: counting flags (`-vv`), choices of arguments and tuple values, numeric
+    ranges, case-insensitive choices, prompts, optional values, argparse aliases,
+    `nargs`, mutually exclusive groups and epilogs are shown; the default command is
+    marked; "deprecated" appears once; commands are sorted and type names normalised
+    so the output is the same on every Click/Typer version; options repeated in three
+    or more commands are listed once; `references/commands.md` no longer repeats the
+    index.
+  - Program name taken from `--program`, the stored setting, the console script or
+    the CLI's own name before the skill name; `markdown` warns when it is unknown.
+  - Settings (program, `--max-chars`, `--hide-default`) stored in the begin marker
+    and reused by `check`, refreshes and `assert_skill_in_sync` (which also accepts
+    `max_chars`, `resolve` and `hide_defaults`).
+  - `--hide-default NAME` for defaults computed at run time; the stale-block message
+    says when only defaults differ.
+  - Drift check: continued lines, short option clusters, values given to flags, invalid
+    choices, options moved to a subcommand, hidden commands, "did you mean".
+  - Command line: one-line errors (exit 2) instead of tracebacks, `--app-dir`,
+    `module:func()` targets, functions not called unless named like a parser, `skill`
+    refresh without `--name`, `check` prints a success line and the fix command.

help2skill-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing
+
+Thanks for helping! Bug reports, new framework adapters and real-world drift cases
+are especially welcome.
+
+## Setup
+```console
+uv sync
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+uv run mypy
+```
+
+## Pull requests
+- One topic per PR, with a test that fails without the change.
+- The generated Markdown format is a public contract (users commit it and the drift
+  check compares it verbatim). If your change alters output, say so in the PR and add a
+  `CHANGELOG.md` entry.
+- Keep runtime dependencies at zero.
+
+## Sign-off (DCO)
+By contributing you agree that your contribution is licensed under the project's
+[MIT license](LICENSE) and that you have the right to submit it, as described in the
+[Developer Certificate of Origin](https://developercertificate.org/).
+Sign each commit with `git commit -s`, which adds a `Signed-off-by:` line.
+
+## AI-assisted contributions
+AI tools are welcome. Mention them in the PR description, and make sure you have read
+and understood every line you submit. This project itself was built with AI assistance
+(Claude).

help2skill-0.1.0/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.

help2skill-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,184 @@
+# 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/SECURITY.md

@@ -0,0 +1,29 @@
+# Security policy
+
+## Supported versions
+help2skill is in alpha. Only the latest release receives fixes.
+
+## Reporting a vulnerability
+Please report privately through GitHub:
+**Security → Report a vulnerability** on https://github.com/huysonmind/help2skill
+(private vulnerability reporting). Do not open a public issue.
+
+You should get a first answer within 7 days.
+
+## What help2skill executes
+- `help2skill markdown|skill|check <module:attr>` **imports your module** to read the
+  command tree, exactly like running your CLI would. Only point it at code you trust.
+- If `attr` is a plain function (for example `build_parser`), it is **called** to obtain
+  the parser.
+- The `--llms` flag only reads the command tree that is already loaded; it does not run
+  any command callback.
+
+## Data in generated files
+Generated Markdown copies your CLI's help text verbatim. If help text is computed at
+runtime (for example a default path under your home directory), that value ends up in
+the output. Review `SKILL.md` before committing it.
+
+## Releases
+Releases are published to PyPI from GitHub Actions with
+[trusted publishing](https://docs.pypi.org/trusted-publishers/); no long-lived API
+token is stored anywhere.

help2skill-0.1.0/SPEC.md

@@ -0,0 +1,40 @@
+# help2skill: short spec (v0.1)
+
+## Problem
+Coding agents call CLIs constantly but learn them from stale training data or by
+guessing. In 2026 large Python CLIs started shipping agent docs by hand:
+Hugging Face (`hf skills`, generated from the Click tree), Modal (`modal skills`),
+SkyPilot (`agent/scripts/generate_references.py`), AWS CLI (`aws configure agent-toolkit`),
+dbt-charts, Keboola. Each wrote its own generator; smaller projects copy-paste
+`gen_skill.py` scripts. Typer ≥ 0.26 vendors Click, which silently breaks those
+scripts' `isinstance(cmd, click.Group)` checks.
+
+## Scope of v0.1
+1. **Introspection** of Click, Typer (old and vendored-Click) and argparse into one
+   neutral model (`Command`, `Param`). Duck-typed; zero runtime dependencies.
+2. **Markdown reference** (`render_markdown`): full path in every heading, an index
+   of all commands at the root, per-param type / required / repeatable / default /
+   env var / help. Deterministic output.
+3. **`--llms` flag**: Click decorator, `add_llms_option` for any built tree,
+   Typer `LlmsOption` (root) and `help2skill.typer.command(app)` (every level).
+4. **SKILL.md**: frontmatter validated against Agent Skills rules (name ≤ 64,
+   `[a-z0-9-]`, description ≤ 1024, no angle brackets); generated block between
+   markers, hand-written text preserved on refresh.
+5. **Drift check**: stale block; hand-written examples that use a missing subcommand,
+   a missing option, or an option at the wrong level. Handles default-command groups.
+   CLI `help2skill check` (exit 1) and `help2skill.testing.assert_skill_in_sync`.
+
+6. **Size budget**: `--llms` index above 20,000 characters; SKILL.md index plus
+   `references/commands.md` above 30,000 characters.
+7. **Portability**: home directory written as `~`; warnings for other machine paths;
+   launcher prefixes (`uv run`, `python -m`, …) understood by the drift check;
+   pluggable `resolve` for lazy placeholder commands.
+
+## Non-goals (v0.1)
+- Installing skills into agent folders (use library-skills).
+- Detecting the calling agent / auto JSON output (planned, via existing detectors).
+- Static analysis without importing the CLI (claude-skill-forge does that).
+
+## Output contract
+Markdown output is a public interface: changes to it are noted in the changelog,
+because users commit generated blocks and the drift check compares them verbatim.