agentpool-cli 0.1.9__tar.gz → 0.1.10__tar.gz

{agentpool_cli-0.1.9 → agentpool_cli-0.1.10}/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 0.1.10 - 2026-06-03
+
+- Add an AI-agent start section to root help pointing agents at bundled skill
+  guidance before they infer workflows from flags.
+- Add `agentpool skills` with `list`, `get`, and `path` so agents can load
+  version-matched AgentPool usage guidance from the installed CLI.
+- Include examples with packaged docs so `agentpool skills get core --full`
+  returns both the skill and copy-paste CLI flows.
+
 ## 0.1.9 - 2026-06-02
 
 - Harden agent-facing CLI recovery with examples on root/group help, structured

{agentpool_cli-0.1.9 → agentpool_cli-0.1.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentpool-cli
-Version: 0.1.9
+Version: 0.1.10
 Summary: Make full use of every coding-agent subscription you pay for: a local CLI + MCP server that surfaces live usage limits and offloads work to providers with headroom.
 Author: AgentPool contributors
 License-Expression: MIT
@@ -103,6 +103,13 @@ notes.
 
 ## Quickstart
 
+For AI agents, start by loading the bundled version-matched skill:
+
+```bash
+agentpool skills get agentpool
+agentpool skills get core --full
+```
+
 ```bash
 agentpool init
 agentpool setup cursor
@@ -312,6 +319,9 @@ summary, provider models, preferences, spawn, observe, send, interrupt,
 collect, artifact manifest, transcript paging, and terminate. Add opt-in
 toolsets with `agentpool mcp --toolsets default,stats,sessions,leases,worktrees`.
 
+Shell-capable agents can use `agentpool skills get agentpool` instead of MCP
+resources to load the same core usage guidance from the installed CLI.
+
 Coding agents with shell access should prefer the CLI path. It is more
 token-efficient because large worker output stays in artifact files and
 `observe`/`collect` return compact manifests by default. MCP remains first-class

{agentpool_cli-0.1.9 → agentpool_cli-0.1.10}/README.md

@@ -82,6 +82,13 @@ notes.
 
 ## Quickstart
 
+For AI agents, start by loading the bundled version-matched skill:
+
+```bash
+agentpool skills get agentpool
+agentpool skills get core --full
+```
+
 ```bash
 agentpool init
 agentpool setup cursor
@@ -291,6 +298,9 @@ summary, provider models, preferences, spawn, observe, send, interrupt,
 collect, artifact manifest, transcript paging, and terminate. Add opt-in
 toolsets with `agentpool mcp --toolsets default,stats,sessions,leases,worktrees`.
 
+Shell-capable agents can use `agentpool skills get agentpool` instead of MCP
+resources to load the same core usage guidance from the installed CLI.
+
 Coding agents with shell access should prefer the CLI path. It is more
 token-efficient because large worker output stays in artifact files and
 `observe`/`collect` return compact manifests by default. MCP remains first-class

{agentpool_cli-0.1.9 → agentpool_cli-0.1.10}/docs/examples.md

@@ -1,5 +1,12 @@
 # Examples
 
+Load agent guidance from the installed CLI:
+
+```bash
+agentpool skills get agentpool
+agentpool skills get core --full
+```
+
 Spawn a fake question worker:
 
 ```bash

{agentpool_cli-0.1.9 → agentpool_cli-0.1.10}/docs/quickstart.md

@@ -7,6 +7,14 @@ plane, not a router: you pick the provider and model explicitly.
 
 ## 1. Verify the environment
 
+AI agents should load the bundled version-matched skill before inferring flows
+from flags:
+
+```bash
+agentpool skills get agentpool
+agentpool skills get core --full
+```
+
 ```bash
 agentpool init
 agentpool doctor --deep --privacy
@@ -58,6 +66,7 @@ Use `--isolation worktree` instead of `read_only` for tasks that edit files.
 
 ## Next
 
+- CLI agent guidance: `agentpool skills get agentpool`
 - Full agent guidance: `agentpool://skill.md`
 - Setup and privacy detail: `agentpool://onboarding`
 - User delegation preferences: `agentpool://preferences.md`

{agentpool_cli-0.1.9 → agentpool_cli-0.1.10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentpool-cli"
-version = "0.1.9"
+version = "0.1.10"
 description = "Make full use of every coding-agent subscription you pay for: a local CLI + MCP server that surfaces live usage limits and offloads work to providers with headroom."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -54,5 +54,6 @@ include = [
 
 [tool.hatch.build.targets.wheel.force-include]
 "docs/agentpool-skill.md" = "agentpool/docs/agentpool-skill.md"
+"docs/examples.md" = "agentpool/docs/examples.md"
 "docs/onboarding.md" = "agentpool/docs/onboarding.md"
 "docs/quickstart.md" = "agentpool/docs/quickstart.md"

{agentpool_cli-0.1.9 → agentpool_cli-0.1.10}/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.sidduHERE/agentpool",
   "title": "AgentPool",
   "description": "See each coding-agent subscription's live limits and offload work to one with headroom.",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "repository": {
     "url": "https://github.com/sidduHERE/agentpool",
     "source": "github"
@@ -13,7 +13,7 @@
     {
       "registryType": "pypi",
       "identifier": "agentpool-cli",
-      "version": "0.1.9",
+      "version": "0.1.10",
       "transport": {
         "type": "stdio"
       },

{agentpool_cli-0.1.9 → agentpool_cli-0.1.10}/src/agentpool/__init__.py

@@ -1,3 +1,3 @@
 """AgentPool local agent control plane."""
 
-__version__ = "0.1.9"
+__version__ = "0.1.10"

{agentpool_cli-0.1.9 → agentpool_cli-0.1.10}/src/agentpool/cli.py

@@ -4,6 +4,7 @@ import json
 import os
 import shutil
 import sys
+from importlib import resources
 from pathlib import Path
 from typing import Annotated, Any, Callable
 
@@ -196,6 +197,14 @@ app = AgentPoolTyper(
     cls=AgentPoolGroup,
     help=(
         "Use every coding-agent subscription you pay for: see live usage limits and offload work to providers with headroom.\n\n"
+        "Start here (for AI agents):\n"
+        "  agentpool skills get agentpool\n\n"
+        "  Skills ship with the CLI, stay version-matched, and include workflow patterns, safety boundaries, "
+        "and copy-paste examples. Prefer this over guessing from flag docs alone.\n\n"
+        "  skills \\[list]              List available skills\n"
+        "  skills get agentpool       Core CLI + MCP delegation guide\n"
+        "  skills get core --full     Include quickstart and examples\n"
+        "  skills path \\[name]         Print bundled skill/docs path\n\n"
         "Examples:\n"
         "  agentpool inventory --json\n"
         "  cat task.md | agentpool spawn --provider codex-cli --repo . --task-stdin\n"
@@ -206,6 +215,19 @@ app = AgentPoolTyper(
     invoke_without_command=True,
     no_args_is_help=True,
 )
+skills_app = AgentPoolTyper(
+    cls=AgentPoolGroup,
+    help=(
+        "List and retrieve bundled AgentPool skill content.\n\n"
+        "Examples:\n"
+        "  agentpool skills\n"
+        "  agentpool skills get agentpool\n"
+        "  agentpool skills get core --full\n"
+        "  agentpool skills path agentpool"
+    ),
+    invoke_without_command=True,
+    no_args_is_help=False,
+)
 config_app = AgentPoolTyper(
     cls=AgentPoolGroup,
     help=(
@@ -242,12 +264,26 @@ worktrees_app = AgentPoolTyper(
         "  agentpool worktrees cleanup --session-id <session-id> --dry-run --json"
     ),
 )
+app.add_typer(skills_app, name="skills")
 app.add_typer(config_app, name="config")
 app.add_typer(leases_app, name="leases")
 app.add_typer(session_app, name="session")
 app.add_typer(worktrees_app, name="worktrees")
 console = Console()
 
+SKILL_DEFINITIONS: dict[str, dict[str, Any]] = {
+    "agentpool": {
+        "aliases": ["core"],
+        "filename": "agentpool-skill.md",
+        "description": "Core AgentPool CLI + MCP delegation guide. Read this before spawning workers.",
+        "references": ["quickstart.md", "examples.md"],
+    }
+}
+SKILL_ALIASES = {
+    alias: name for name, definition in SKILL_DEFINITIONS.items() for alias in [name, *definition["aliases"]]
+}
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
+
 
 @app.callback()
 def root(
@@ -265,6 +301,158 @@ def print_data(data: object, json_output: bool) -> None:
         console.print(data)
 
 
+def _docs_resource(filename: str | None = None) -> Any:
+    docs = resources.files("agentpool").joinpath("docs")
+    return docs.joinpath(filename) if filename else docs
+
+
+def _read_packaged_doc(filename: str) -> str:
+    packaged = _docs_resource(filename)
+    if packaged.is_file():
+        return packaged.read_text(encoding="utf-8")
+    return (PROJECT_ROOT / "docs" / filename).read_text(encoding="utf-8")
+
+
+def _resource_display_path(filename: str | None = None) -> str:
+    packaged = _docs_resource(filename)
+    if packaged.is_file() or (filename is None and packaged.is_dir()):
+        return str(packaged)
+    fallback_docs = PROJECT_ROOT / "docs"
+    return str(fallback_docs / filename) if filename else str(fallback_docs)
+
+
+def _skill_entry(name: str) -> dict[str, Any]:
+    definition = SKILL_DEFINITIONS[name]
+    return {
+        "name": name,
+        "aliases": definition["aliases"],
+        "description": definition["description"],
+        "full_available": bool(definition.get("references")),
+    }
+
+
+def _resolve_skill_name(name: str) -> str:
+    normalized = name.strip().lower()
+    if normalized in SKILL_ALIASES:
+        return SKILL_ALIASES[normalized]
+    raise ToolError(
+        "INVALID_REQUEST",
+        f"Unknown skill {name!r}.",
+        {"example": "agentpool skills list"},
+    )
+
+
+def _skill_text(name: str, *, full: bool = False) -> str:
+    definition = SKILL_DEFINITIONS[name]
+    chunks = [_read_packaged_doc(definition["filename"])]
+    if full:
+        for filename in definition.get("references") or []:
+            title = filename.removesuffix(".md").replace("-", " ").title()
+            chunks.append(f"\n\n# Reference: {title}\n\n{_read_packaged_doc(filename)}")
+    return "".join(chunks)
+
+
+def _print_skills_list(json_output: bool) -> None:
+    data = {"skills": [_skill_entry(name) for name in sorted(SKILL_DEFINITIONS)]}
+    if json_output:
+        console.print_json(json.dumps(data, default=str))
+        return
+    for skill in data["skills"]:
+        aliases = f" (aliases: {', '.join(skill['aliases'])})" if skill["aliases"] else ""
+        console.print(f"  {skill['name']:<12} {skill['description']}{aliases}")
+
+
+@skills_app.callback(invoke_without_command=True)
+def skills_root(
+    ctx: typer.Context,
+    json_output: Annotated[bool, typer.Option("--json", help="Emit JSON.")] = False,
+) -> None:
+    """List bundled skills when no subcommand is provided."""
+    if ctx.invoked_subcommand is None:
+        _print_skills_list(json_output)
+        raise typer.Exit()
+
+
+@skills_app.command("list")
+def skills_list(json_output: Annotated[bool, typer.Option("--json", help="Emit JSON.")] = False) -> None:
+    """List bundled skills.
+
+    Examples:
+      agentpool skills list
+      agentpool skills list --json
+    """
+    _print_skills_list(json_output)
+
+
+@skills_app.command("get")
+def skills_get(
+    name: Annotated[str | None, typer.Argument(help="Skill name, for example: agentpool or core.")] = None,
+    full: Annotated[bool, typer.Option("--full", help="Include quickstart and examples with the core skill.")] = False,
+    all_skills: Annotated[bool, typer.Option("--all", help="Output every bundled skill.")] = False,
+    json_output: Annotated[bool, typer.Option("--json", help="Emit JSON.")] = False,
+) -> None:
+    """Output bundled skill content.
+
+    Examples:
+      agentpool skills get agentpool
+      agentpool skills get core --full
+      agentpool skills get --all --json
+    """
+    try:
+        if all_skills:
+            names = sorted(SKILL_DEFINITIONS)
+        elif name:
+            names = [_resolve_skill_name(name)]
+        else:
+            raise ToolError(
+                "INVALID_REQUEST",
+                "Provide a skill name or --all.",
+                {"example": "agentpool skills get agentpool"},
+            )
+        skills = [
+            {
+                **_skill_entry(skill_name),
+                "full": full,
+                "path": _resource_display_path(SKILL_DEFINITIONS[skill_name]["filename"]),
+                "text": _skill_text(skill_name, full=full),
+            }
+            for skill_name in names
+        ]
+        if json_output:
+            console.print_json(json.dumps({"skills": skills}, default=str))
+            return
+        console.print("\n\n".join(skill["text"] for skill in skills), markup=False)
+    except ToolError as exc:
+        handle_tool_error(exc, json_output)
+
+
+@skills_app.command("path")
+def skills_path(
+    name: Annotated[str | None, typer.Argument(help="Optional skill name, for example: agentpool or core.")] = None,
+    json_output: Annotated[bool, typer.Option("--json", help="Emit JSON.")] = False,
+) -> None:
+    """Print bundled skill/docs path.
+
+    Examples:
+      agentpool skills path
+      agentpool skills path agentpool
+      agentpool skills path core --json
+    """
+    try:
+        if name:
+            skill_name = _resolve_skill_name(name)
+            path = _resource_display_path(SKILL_DEFINITIONS[skill_name]["filename"])
+            data = {"name": skill_name, "path": path}
+        else:
+            data = {"path": _resource_display_path()}
+        if json_output:
+            console.print_json(json.dumps(data, default=str))
+            return
+        console.print(data["path"], markup=False)
+    except ToolError as exc:
+        handle_tool_error(exc, json_output)
+
+
 def _env_flag(name: str) -> bool:
     return os.environ.get(name, "").strip().lower() in {"1", "true", "yes", "on"}
 

{agentpool_cli-0.1.9 → agentpool_cli-0.1.10}/tests/unit/test_cli.py

@@ -264,6 +264,7 @@ def test_root_and_group_help_have_examples() -> None:
     runner = CliRunner()
     for args in (
         ["--help"],
+        ["skills", "--help"],
         ["config", "--help"],
         ["leases", "--help"],
         ["session", "--help"],
@@ -274,6 +275,54 @@ def test_root_and_group_help_have_examples() -> None:
         assert "Examples:" in result.output
 
 
+def test_root_help_points_agents_to_bundled_skills() -> None:
+    result = CliRunner().invoke(app, ["--help"])
+
+    assert result.exit_code == 0
+    assert "Start here (for AI agents):" in result.output
+    assert "agentpool skills get agentpool" in result.output
+    assert "skills [list]" in result.output
+    assert "skills path [name]" in result.output
+    assert "Skills ship with the CLI" in result.output
+
+
+def test_skills_list_get_path_and_json() -> None:
+    runner = CliRunner()
+
+    listed = runner.invoke(app, ["skills"])
+    listed_json = runner.invoke(app, ["skills", "list", "--json"])
+    skill = runner.invoke(app, ["skills", "get", "agentpool"])
+    full = runner.invoke(app, ["skills", "get", "core", "--full"])
+    path = runner.invoke(app, ["skills", "path", "core"])
+    skill_json = runner.invoke(app, ["skills", "get", "agentpool", "--json"])
+
+    assert listed.exit_code == 0
+    assert "agentpool" in listed.output
+    assert "aliases: core" in listed.output
+    assert listed_json.exit_code == 0
+    assert json.loads(listed_json.output)["skills"][0]["name"] == "agentpool"
+    assert skill.exit_code == 0
+    assert "# AgentPool Skill" in skill.output
+    assert "Typical CLI Flow" in skill.output
+    assert full.exit_code == 0
+    assert "# Reference: Quickstart" in full.output
+    assert "# Examples" in full.output
+    assert path.exit_code == 0
+    assert "agentpool-skill.md" in path.output
+    assert skill_json.exit_code == 0
+    payload = json.loads(skill_json.output)
+    assert payload["skills"][0]["name"] == "agentpool"
+    assert "# AgentPool Skill" in payload["skills"][0]["text"]
+
+
+def test_skills_get_unknown_returns_recovery_hint() -> None:
+    result = CliRunner().invoke(app, ["skills", "get", "missing"])
+
+    assert result.exit_code == 1
+    assert "INVALID_REQUEST" in result.output
+    assert "try: agentpool skills list" in result.output
+
+
 def test_missing_parameter_errors_include_copy_pasteable_examples() -> None:
     runner = CliRunner()
 
@@ -555,6 +604,7 @@ def test_core_help_has_examples() -> None:
         "preferences",
         "smoke",
         "providers",
+        "skills",
         "models",
         "stats",
         "sessions",
@@ -580,6 +630,9 @@ def test_nested_help_has_examples() -> None:
     runner = CliRunner()
     for command in (
         ("session", "show"),
+        ("skills", "list"),
+        ("skills", "get"),
+        ("skills", "path"),
         ("config", "path"),
         ("config", "print"),
         ("config", "validate"),

{agentpool_cli-0.1.9 → agentpool_cli-0.1.10}/uv.lock

@@ -3,7 +3,7 @@ requires-python = ">=3.11"
 
 [[package]]
 name = "agentpool-cli"
-version = "0.1.9"
+version = "0.1.10"
 source = { editable = "." }
 dependencies = [
     { name = "certifi" },