cli-creator-skill 0.1.0__py3-none-any.whl

cli_creator_skill/__init__.py

@@ -0,0 +1,3 @@
+"""Installer package for the cli-creator skill."""
+
+__version__ = "0.1.0"

cli_creator_skill/__main__.py

@@ -0,0 +1,5 @@
+from .installer import main
+
+
+if __name__ == "__main__":
+    main()

cli_creator_skill/installer.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import argparse
+import shutil
+import sys
+from pathlib import Path
+
+
+SKILL_NAME = "cli-creator"
+
+
+def default_target() -> Path:
+    return Path.home() / ".codex" / "skills"
+
+
+def skill_source() -> Path:
+    return Path(__file__).resolve().parent / "skills" / SKILL_NAME
+
+
+def install(target: Path, force: bool = False) -> Path:
+    src = skill_source()
+    if not src.exists():
+        raise FileNotFoundError(f"Skill files were not found in the package: {src}")
+
+    dest = target.expanduser().resolve() / SKILL_NAME
+    if dest.exists():
+        if not force:
+            raise FileExistsError(
+                f"{dest} already exists. Re-run with --force to overwrite it."
+            )
+        shutil.rmtree(dest)
+
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copytree(src, dest)
+    return dest
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="cli-creator-skill",
+        description="Install the cli-creator agent skill.",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    install_parser = subparsers.add_parser("install", help="Install the skill locally.")
+    install_parser.add_argument(
+        "--target",
+        type=Path,
+        default=default_target(),
+        help="Directory that contains skill folders. Default: ~/.codex/skills",
+    )
+    install_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite an existing cli-creator skill directory.",
+    )
+
+    args = parser.parse_args(argv)
+    if args.command in (None, "install"):
+        try:
+            dest = install(args.target, force=args.force)
+        except Exception as exc:
+            print(f"Install failed: {exc}", file=sys.stderr)
+            return 1
+        print(f"Installed {SKILL_NAME} to {dest}")
+        return 0
+
+    parser.print_help()
+    return 0

cli_creator_skill/skills/cli-creator/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: cli-creator
+description: Use when designing, scaffolding, refactoring, or auditing a Python CLI tool, especially Typer + Rich + questionary CLIs with interactive flows, data fetching, caching, LLM integration, structured output, local memory, and multi-channel delivery.
+---
+
+# CLI Creator
+
+Use this skill to create a high-quality CLI from zero, or to review an existing CLI and produce actionable fixes. Prefer it for interactive, data-driven, LLM-assisted, multi-turn command line products.
+
+## Trigger Conditions
+
+Use this skill when the user asks to:
+
+- Create a Python CLI, command line app, interactive assistant, research assistant, data tool, or automation CLI.
+- Improve a CLI's UX, command surface, onboarding, config flow, model setup, caching, or release process.
+- Audit an existing CLI for maintainability, reliability, packaging, PyPI installability, or user experience.
+- Add Typer, Rich, questionary, litellm, instructor, Pydantic, SQLite, config, profile memory, or provider setup to a CLI.
+- Diagnose symptoms such as "command not found", "model returns empty", "refresh shows same results", "users do not know how to configure", "interactive flow feels rigid", or "report quality is shallow".
+
+## Core Philosophy
+
+Build the CLI as a product, not as a thin script.
+
+1. Start from the user's job, not the command list. The first screen must help users decide what to do next.
+2. Separate command routing, conversation flow, data access, LLM reasoning, persistence, and delivery channels.
+3. Make every external dependency visible and diagnosable: model provider, base URL, model name, auth state, cache age, and output path.
+4. Prefer progressive interaction. Ask one natural question at a time, summarize what you learned, and allow correction.
+5. Ground data-driven recommendations in evidence. Show source, time window, freshness, and confidence.
+6. Treat local memory as a user-controlled feature. Provide inspect, update, export, and clear commands.
+7. Optimize for recovery. Every error should explain what happened, why it likely happened, and what command fixes it.
+
+Balance UX and functionality by making the default path friendly and the expert path scriptable. Interactive commands should guide; non-interactive flags should reproduce the same workflow for automation.
+
+## First Response Pattern
+
+When starting a CLI creation task:
+
+1. Restate the target user, core workflow, and delivery format in one short paragraph.
+2. Identify whether this is a new CLI, a refactor, or an audit.
+3. Inspect the repository before proposing architecture when code already exists.
+4. Create or update files directly unless the user explicitly asks for a plan only.
+5. Verify the installed command, the help output, and at least one end-to-end smoke path.
+
+When starting a CLI review task:
+
+1. Run a quick structure scan: `rg --files`, `pyproject.toml`, entry points, package layout, tests, README.
+2. Run the CLI help and one representative command when safe.
+3. Report findings by severity first, with file and line references.
+4. Suggest fixes that preserve the existing architecture unless the structure itself is the problem.
+
+## Creation Workflow
+
+Follow this workflow for a new CLI.
+
+### 1. Define The Product Surface
+
+Clarify:
+
+- Primary job: what valuable outcome should the user get in one session?
+- First-run path: what does a brand-new user see before any config exists?
+- Expert path: what command can be scripted in CI, cron, or automations?
+- State model: what is ephemeral, cached, remembered, or user-owned?
+- External integrations: models, APIs, browser tools, Feishu/Lark, GitHub, file outputs.
+
+Design no more than 5 top-level commands for v1. Prefer:
+
+- `run` for the main interactive flow.
+- `setup` for guided first-run configuration.
+- `config` for inspect/update/reset.
+- `doctor` for diagnostics and auto-fixes.
+- `history` or `profile` only when persistent memory is a core feature.
+
+### 2. Choose The Stack
+
+Use this default stack unless the repo has a strong existing convention:
+
+- Typer for command routing, type hints, and shell completion.
+- Rich for panels, tables, markdown rendering, progress, and friendly errors.
+- questionary for interactive prompts, with non-TTY fallbacks.
+- Pydantic v2 for domain models and validation.
+- pydantic-settings plus `.env` for config.
+- SQLite for cache, history, and user profile memory.
+- httpx for HTTP clients with timeouts, retries, and clear user-agent.
+- litellm for multi-provider model calls.
+- instructor for structured LLM output when compatible; provide a JSON-schema fallback.
+
+### 3. Design Modules Before Files
+
+Keep these boundaries:
+
+- `cli`: parse commands and flags only.
+- `app` or `flows`: orchestrate user journeys.
+- `models`: define Pydantic request, result, profile, and report schemas.
+- `settings`: load env/config and validate provider setup.
+- `store`: own SQLite schema, cache, history, and profile memory.
+- `services`: fetch data from external sources.
+- `llm`: call models and normalize structured output.
+- `renderers`: terminal, markdown, JSON, or file rendering.
+- `integrations`: Feishu/Lark, DingTalk, WeChat, GitHub, email, etc.
+
+Do not let prompt strings, HTTP calls, database SQL, and Rich tables live in the same module.
+
+### 4. Build The Interaction Loop
+
+For conversational CLIs, model the flow as stages:
+
+1. Explore intent with one open question.
+2. Build a lightweight user profile through natural conversation.
+3. Run data-driven opportunity scanning.
+4. Rank and refine options with the user.
+5. Generate a durable output artifact.
+6. Offer one useful next action.
+
+Use state objects, not scattered booleans. Track:
+
+- Current stage.
+- User goal and constraints.
+- Known profile fields and confidence.
+- Evidence queries already used.
+- Candidate items already shown.
+- User rejections and "do not ask again" preferences.
+
+### 5. Make Data And LLMs Observable
+
+For every model-backed or web-backed recommendation, preserve:
+
+- Query text.
+- Time window.
+- Source name and URL.
+- Fetch timestamp.
+- Cache key and cache age.
+- Model provider, base URL, model name, and response mode.
+- Structured validation errors.
+
+Show concise evidence to the user, and save full evidence beside generated artifacts.
+
+### 6. Ship The CLI As An Installable Product
+
+Ensure:
+
+- `pyproject.toml` defines a `console_scripts` entry point.
+- The command name users type is the command that gets installed.
+- `--help` works before config exists.
+- `setup` guides users through provider, base URL, model name, API key, and verification.
+- `doctor` detects stale entry points, Python version mismatch, missing optional tools, auth state, and config mistakes.
+- README includes install, first run, config, examples, troubleshooting, and extension points.
+
+## Review Workflow
+
+Audit an existing CLI with this order:
+
+1. Inspect package metadata, command entry points, Python version, dependencies, and README.
+2. Run `--help`, `setup --help`, `config --help`, and the main command help.
+3. Trace the main flow from CLI command to app orchestration, services, LLM, persistence, rendering, and output.
+4. Check first-run behavior with no config.
+5. Check invalid config behavior, especially model provider/base URL/model name/API key combinations.
+6. Check cache refresh semantics and whether "refresh" can repeat stale results.
+7. Check non-TTY behavior and scriptability.
+8. Check tests for entry point, config, cache, LLM fallback, and smoke flows.
+9. Score with `references/review-rubric.md`.
+10. Return findings first, then a prioritized repair plan.
+
+## Pitfalls To Watch
+
+Before implementing or reviewing, read `references/pitfalls-and-solutions.md` when the task involves:
+
+- Interactive flows.
+- LLM provider setup.
+- Data caching or refresh.
+- Profile memory.
+- Packaging and PyPI entry points.
+- Feishu/Lark or other delivery channels.
+
+High-frequency pitfalls include:
+
+- Asking form-like questions instead of having a natural conversation.
+- Hiding required model settings behind a single API key prompt.
+- Treating OpenAI-compatible endpoints as interchangeable without checking path, model name, and response schema.
+- Returning empty lists when the real problem is model/config failure.
+- Letting refresh reuse identical cache keys.
+- Saving user profile memory without inspect and clear commands.
+- Publishing a package whose installed command differs from README examples.
+
+## Project Structure Template
+
+Use or adapt this structure:
+
+```text
+my-cli/
+  pyproject.toml
+  README.md
+  .env.example
+  src/my_cli/
+    __init__.py
+    __main__.py
+    cli.py
+    app.py
+    console.py
+    errors.py
+    models.py
+    settings.py
+    store.py
+    prompts.py
+    renderers/
+      __init__.py
+      terminal.py
+      markdown.py
+      json.py
+    services/
+      __init__.py
+      evidence.py
+      search.py
+    llm/
+      __init__.py
+      client.py
+      schemas.py
+    integrations/
+      __init__.py
+      base.py
+      lark.py
+      dingtalk.py
+      wechat.py
+  tests/
+    test_cli_help.py
+    test_config.py
+    test_store.py
+    test_flow_smoke.py
+```
+
+Read `references/creation-playbook.md` for a fuller scaffold and implementation sequence.
+
+## Interactive Design Rules
+
+Use these rules for conversational or assistant-like CLIs:
+
+- Ask one question at a time.
+- Make each question sound like a helpful collaborator, not an application form.
+- Stop asking when enough signal exists; use defaults and say they can be changed later.
+- Never repeat a question whose semantic field was already answered.
+- Summarize the profile before using it for recommendations.
+- Accept natural language commands such as "换一个方向", "再细一点", "这个太难", "保守一点", "直接生成".
+- Treat refresh as a new search intent with exclusions from previously shown candidates.
+- Always let the user inspect and clear remembered profile data.
+
+For profile-building flows, internally collect background, goal, resources, constraints, risk preference, and output preference, but phrase questions naturally:
+
+- "先聊聊你的背景吧，你之前主要在哪些方向做过研究、写作或项目？"
+- "这次你更想得到什么结果？发论文、写长文、系统学习、职业准备，还是单纯好奇？"
+- "你有没有别人不太容易有的视角、经历或资源？"
+- "有没有什么方向你明确不想碰，或者现在比较顾虑？"
+
+## LLM Integration Rules
+
+When adding model support:
+
+1. Require provider, base URL, model name, and API key as separate visible fields when using OpenAI-compatible third-party providers.
+2. Provide presets for common providers, but let users override every field.
+3. Verify configuration with a small structured-output call.
+4. Detect and explain common failures: wrong endpoint path, unsupported JSON schema, invalid model name, expired key, proxy issue, timeout, and content filter.
+5. Fall back from instructor tool/function mode to JSON mode or plain JSON parsing when provider compatibility is partial.
+6. Cache only successful data fetches and validated LLM outputs. Do not cache empty results from failed calls as if they were valid.
+
+## Output Standards
+
+For a new CLI task, deliver:
+
+- Project structure.
+- Core Pydantic models.
+- Main commands and help text.
+- First-run setup flow.
+- End-to-end smoke command.
+- README updates.
+- Known limitations and next steps.
+
+For a review task, deliver:
+
+- Findings ordered by severity.
+- File and line references.
+- Reproduction steps.
+- Recommended fixes.
+- Test gaps.
+- A short implementation plan if changes are requested.
+
+## References
+
+- Read `references/pitfalls-and-solutions.md` for common failure modes and repairs.
+- Read `references/creation-playbook.md` for the full build sequence.
+- Read `references/review-rubric.md` for scoring and audit format.

cli_creator_skill/skills/cli-creator/references/creation-playbook.md

@@ -0,0 +1,267 @@
+# CLI Creation Playbook
+
+Use this playbook to build a modern Python CLI that is friendly for first-time users, scriptable for power users, and maintainable for future contributors.
+
+## Phase 0: Product Framing
+
+Define:
+
+- Target user: who uses this CLI and in what context?
+- Job to be done: what useful artifact or decision should the CLI produce?
+- First-run success: what can a user achieve within five minutes?
+- Repeat-run success: what should the CLI remember or automate?
+- Failure model: what can fail, and how should the CLI recover?
+
+Write a one-paragraph product promise before writing code.
+
+## Phase 1: Command Surface
+
+Keep v1 small:
+
+```text
+my-cli run                 # main interactive flow
+my-cli setup               # guided first-run setup
+my-cli config show         # inspect config safely
+my-cli config set          # update config
+my-cli config reset        # reset config
+my-cli doctor              # diagnose environment
+```
+
+Add optional commands only when they expose real user value:
+
+```text
+my-cli profile show
+my-cli profile clear
+my-cli cache clear
+my-cli history list
+my-cli export
+```
+
+Rules:
+
+- Prefer verbs users understand.
+- Keep aliases only when they reduce friction.
+- Ensure every interactive prompt has an equivalent flag for automation.
+
+## Phase 2: Project Bootstrap
+
+Recommended tooling:
+
+- `uv` for project and lock management when available.
+- `src/` layout to prevent import confusion.
+- `pytest` for tests.
+- `ruff` for linting and formatting.
+- `typer`, `rich`, `questionary`, `pydantic`, `pydantic-settings`, `python-dotenv`, `httpx`, `litellm`, `instructor`.
+
+Minimal `pyproject.toml` shape:
+
+```toml
+[project]
+name = "my-cli"
+version = "0.1.0"
+requires-python = ">=3.10"
+dependencies = [
+  "typer>=0.12",
+  "rich>=13",
+  "questionary>=2",
+  "pydantic>=2",
+  "pydantic-settings>=2",
+  "python-dotenv>=1",
+  "httpx>=0.27",
+]
+
+[project.scripts]
+my-cli = "my_cli.cli:main"
+```
+
+## Phase 3: Domain Models
+
+Define Pydantic models before implementing long flows.
+
+Common models:
+
+- `UserProfile`: background, goals, resources, constraints, risk preference, output preference, updated_at, confidence.
+- `ConversationState`: current stage, known facts, pending question, rejected items, shown candidates.
+- `EvidenceItem`: source, title, url, published_at, metric, snippet, reliability.
+- `Candidate`: title, summary, evidence, scores, novelty, user_fit.
+- `Brief`: final structured artifact.
+- `ModelConfig`: provider, base_url, model, api_key_ref, mode, timeout.
+- `CacheEntry`: key, status, payload, created_at, expires_at, error_summary.
+
+Keep fields explicit enough that invalid LLM output fails early.
+
+## Phase 4: Interaction Design
+
+For multi-turn assistant CLIs:
+
+1. Ask one open question.
+2. Interpret intent.
+3. Ask the next most useful missing question.
+4. Summarize the profile.
+5. Confirm or let the user correct.
+6. Fetch evidence.
+7. Show a ranked table.
+8. Allow selection, refresh, refinement, or free-text challenge.
+9. Generate an output file.
+10. Offer delivery or next analysis.
+
+State machine fields:
+
+```python
+class Stage(str, Enum):
+    EXPLORE = "explore"
+    PROFILE = "profile"
+    SCAN = "scan"
+    REFINE = "refine"
+    OUTPUT = "output"
+```
+
+Do not hard-code long question chains. Decide the next prompt from missing fields and the user's latest answer.
+
+## Phase 5: Persistence And Cache
+
+Use SQLite for:
+
+- Query cache.
+- Evidence cache.
+- LLM structured output cache.
+- User profile memory.
+- Run history.
+
+Cache key should include:
+
+- Normalized query.
+- Time window.
+- Source or provider.
+- Filters.
+- Schema version.
+
+Cache entry should include:
+
+- Status.
+- Created time.
+- Expiry time.
+- Payload hash.
+- Error summary for failed calls.
+
+Commands:
+
+```text
+my-cli cache stats
+my-cli cache clear
+my-cli profile show
+my-cli profile clear
+```
+
+Do not cache failed empty results as valid recommendations.
+
+## Phase 6: LLM Integration
+
+Support model providers through a normalized client:
+
+- OpenAI.
+- Anthropic.
+- OpenAI-compatible providers.
+- Ark or other provider-specific endpoints.
+- Local Ollama when useful.
+
+Configuration rules:
+
+- Provider, base URL, model name, and API key must be separate.
+- Presets should help, not hide fields.
+- Verification must call the configured model.
+- Store capability probes: plain chat, JSON mode, instructor/tool mode.
+
+Structured output strategy:
+
+1. Try instructor with provider-compatible mode.
+2. Fall back to JSON mode.
+3. Fall back to plain text with strict JSON extraction.
+4. Validate with Pydantic.
+5. Retry once with validation errors summarized.
+6. Fail clearly with a diagnostic command.
+
+## Phase 7: External Integrations
+
+Use adapter interfaces:
+
+```python
+class DeliveryChannel(Protocol):
+    name: str
+    def is_configured(self) -> bool: ...
+    def verify(self) -> VerificationResult: ...
+    def send_file(self, file_path: Path, message: str) -> DeliveryResult: ...
+```
+
+Keep integration-specific auth, CLI calls, and error mapping inside adapters.
+
+For Feishu/Lark:
+
+- Detect whether `lark-cli` exists.
+- Check `auth status` for user or bot.
+- Check configured chat ID.
+- Guide users to install/auth only when missing.
+- Do not block report generation if delivery is not configured.
+
+## Phase 8: Error Handling
+
+Define user-facing exceptions:
+
+- `ConfigError`
+- `ModelVerificationError`
+- `DataFetchError`
+- `CacheError`
+- `DeliveryError`
+- `UserCancelled`
+
+Each error should include:
+
+- Message.
+- Likely cause.
+- Suggested command.
+- Whether retry is safe.
+
+Show tracebacks only with `--debug`.
+
+## Phase 9: Testing
+
+Minimum tests:
+
+- Import package.
+- Run `--help`.
+- Run every command's `--help`.
+- Load default settings with temp home.
+- Save, show, and clear profile.
+- Cache hit, miss, refresh, and expired behavior.
+- Model config validation without real network.
+- One offline smoke flow using fixture evidence.
+
+Useful commands:
+
+```bash
+python -m pytest
+python -m my_cli --help
+my-cli doctor --json
+```
+
+## Phase 10: Documentation And Release
+
+README must include:
+
+- What the CLI is for.
+- Install command.
+- First-run setup.
+- Main workflow with screenshots or terminal examples.
+- Model provider configuration examples.
+- Config paths.
+- Troubleshooting.
+- Extension guide.
+
+Release checklist:
+
+- Clean venv install works.
+- Console script name matches README.
+- `--help` works without config.
+- Package metadata includes Python version.
+- No secrets in repo.
+- PyPI page renders README.

cli_creator_skill/skills/cli-creator/references/pitfalls-and-solutions.md

@@ -0,0 +1,319 @@
+# CLI Pitfalls And Solutions
+
+Use this reference when creating or auditing a Python CLI, especially an interactive Typer + Rich + questionary application with data fetching, LLM integration, and local persistence.
+
+## 1. Menu-First Design
+
+Problem: The CLI opens with a rigid menu instead of helping the user express intent.
+
+Typical signs:
+
+- The first prompt asks users to choose between internal implementation modes.
+- Users who do not know the domain cannot proceed confidently.
+- Every branch produces similar results, so choices feel fake.
+
+Solution:
+
+- Start with a plain-language question about the user's goal.
+- Offer 2-4 examples, but always allow free text.
+- Route free text through intent detection, not a generic default branch.
+
+Anti-pattern:
+
+```text
+? Choose mode: [Domain mode, Autonomous mode, Config mode]
+```
+
+Better:
+
+```text
+? 你最近想研究什么？可以说一个领域，也可以说“我没思路，帮我找机会”。
+```
+
+## 2. Questionnaire-Like Profile Collection
+
+Problem: The CLI asks a stack of formal questions and makes the user feel they are filling out a grant application.
+
+Typical signs:
+
+- Five or more questions are shown at once.
+- Questions use abstract labels such as "风险偏好" or "输出形式偏好".
+- The CLI repeats similar questions after the user already answered.
+
+Solution:
+
+- Ask one natural question at a time.
+- Maintain a profile state with field confidence.
+- Infer missing fields when confidence is good enough.
+- Allow "没有", "不知道", "跳过", and continue with defaults.
+
+Better:
+
+```text
+先聊聊你的背景吧，你之前主要在哪些方向做过研究、写作或项目？
+```
+
+## 3. No Persistent Profile Memory
+
+Problem: The CLI asks the same background questions every run.
+
+Typical signs:
+
+- Returning users must re-enter goals and constraints.
+- There is no command to inspect or clear memory.
+- Profile data is mixed with cache data.
+
+Solution:
+
+- Store profile memory in SQLite or a dedicated config file.
+- Provide `profile show`, `profile edit`, and `profile clear`.
+- Store timestamps and confidence per field.
+- Ask only for missing or stale information.
+
+## 4. Hidden Model Configuration
+
+Problem: The CLI asks only for an API key, but the provider also requires provider name, base URL, and model name.
+
+Typical signs:
+
+- OpenAI-compatible providers fail silently.
+- Users paste a base URL such as an Ark endpoint but the CLI still calls the OpenAI default.
+- Empty recommendations appear when the real cause is model failure.
+
+Solution:
+
+- Treat provider, base URL, model, API key, timeout, and structured-output mode as explicit settings.
+- Provide presets, then verify with a small call.
+- Display the active provider summary before expensive workflows.
+
+Better commands:
+
+```bash
+my-cli setup model
+my-cli config model show
+my-cli config model verify
+my-cli config model presets
+```
+
+## 5. Provider Compatibility Assumptions
+
+Problem: The CLI assumes all OpenAI-compatible endpoints support the same schema, tool calls, streaming, and JSON mode.
+
+Typical signs:
+
+- Instructor fails on one provider but works on another.
+- `base_url` path is wrong, for example using a coding endpoint for chat completions.
+- Model names require provider-specific IDs.
+
+Solution:
+
+- Implement provider presets with known base URL shape and model examples.
+- Run a capability probe: plain chat, JSON mode, instructor/tool mode.
+- Store capability flags and choose the safest response mode.
+- Provide a manual override.
+
+## 6. Caching Failed Or Empty Results
+
+Problem: A failed fetch or bad LLM response is cached as a valid empty result.
+
+Typical signs:
+
+- Refresh still returns no results.
+- The CLI says "no reliable topics" even after config is fixed.
+- Cache has no status field.
+
+Solution:
+
+- Store cache entries with status: `ok`, `empty-valid`, `error`, `partial`.
+- Do not reuse `error` cache entries unless explicitly requested.
+- Include cache age and source in debug output.
+- Provide `cache clear` and `run --refresh`.
+
+## 7. Refresh Shows The Same Items
+
+Problem: Refresh reuses the same query, same cache key, and same ranking without exclusions.
+
+Typical signs:
+
+- Users see identical suggestions across refreshes.
+- The code only bypasses cache but does not alter the search strategy.
+
+Solution:
+
+- Track shown item IDs, titles, URLs, and embeddings or normalized titles.
+- Add exclusions to ranking.
+- Vary query expansions and time windows.
+- Display "new since last batch" and "hidden duplicates" counts.
+
+## 8. Evidence-Free Recommendations
+
+Problem: The CLI generates attractive topic names without verifiable sources.
+
+Typical signs:
+
+- Tables have no source URLs.
+- "Hot" means the model thinks it is hot.
+- Social chatter is treated as equal to papers, policy, market data, or code activity.
+
+Solution:
+
+- Require evidence objects with source, URL, date, metric, and snippet.
+- Rank topics using transparent dimensions.
+- Mark unsupported claims as hypotheses.
+- Refuse or ask to broaden search when evidence is insufficient.
+
+## 9. Monolithic CLI Modules
+
+Problem: `cli.py` contains command definitions, prompts, HTTP calls, SQL, prompt templates, and rendering.
+
+Typical signs:
+
+- Adding a new command risks breaking the main flow.
+- Tests must mock too much.
+- LLM prompts are hard to reuse.
+
+Solution:
+
+- Keep `cli.py` thin.
+- Move orchestration to `app.py` or `flows/`.
+- Move integrations to `services/` or `integrations/`.
+- Move terminal output to `renderers/terminal.py`.
+
+## 10. Poor Non-TTY Behavior
+
+Problem: The CLI only works interactively and crashes in automation.
+
+Typical signs:
+
+- questionary prompts appear in cron, CI, or piped usage.
+- No flags exist for required inputs.
+- The command cannot run with `--yes`, `--json`, or config values.
+
+Solution:
+
+- Detect `sys.stdin.isatty()`.
+- Provide flags for every required prompt.
+- In non-TTY mode, fail with a clear missing-argument message or use defaults.
+- Keep JSON output free of Rich styling.
+
+## 11. Friendly UI But Weak Errors
+
+Problem: The CLI looks polished but gives vague failure messages.
+
+Typical signs:
+
+- "执行失败" without cause.
+- Stack traces shown to normal users.
+- No suggested command fixes the issue.
+
+Solution:
+
+- Define domain errors with human messages and repair hints.
+- Add `--debug` for tracebacks.
+- Include next commands, for example `my-cli config model verify`.
+
+Error format:
+
+```text
+模型验证失败：Ark 返回 404，通常是 base_url 路径或模型名不匹配。
+建议：运行 my-cli setup model --provider ark，然后选择一个可用模型。
+```
+
+## 12. Packaging Entry Point Drift
+
+Problem: README says `hotspot-research`, package installs `hotspot-research-cli`, or stale scripts remain on PATH.
+
+Typical signs:
+
+- `command not found` after successful install.
+- Help text shows old command names.
+- User must manually create symlinks.
+
+Solution:
+
+- Define the final command in `[project.scripts]`.
+- Add a `doctor --fix-entrypoint` command only for legacy installs.
+- Test install into a clean venv.
+- Keep README examples generated or verified from real commands.
+
+## 13. Secrets In Logs And Config
+
+Problem: API keys, tokens, or bot credentials appear in logs, snapshots, or Git history.
+
+Typical signs:
+
+- Config show prints full API keys.
+- Debug logs include headers.
+- `.env` is committed.
+
+Solution:
+
+- Mask secrets by default.
+- Store keys in OS keychain when available, or protected config files.
+- Keep `.env.example`, never `.env`.
+- Add pre-commit or CI secret scanning when feasible.
+
+## 14. Slow Startup
+
+Problem: Heavy imports, network probes, or model discovery happen before help output.
+
+Typical signs:
+
+- `my-cli --help` is slow.
+- Importing the package triggers HTTP calls.
+- Rich progress starts before command validation.
+
+Solution:
+
+- Keep top-level imports lightweight.
+- Lazy-load LLM, browser, data, and rendering-heavy modules inside commands.
+- Never probe network during import.
+
+## 15. Missing Smoke Tests
+
+Problem: Unit tests pass but the installed CLI is broken.
+
+Typical signs:
+
+- No test runs `python -m package --help`.
+- No test checks `console_scripts`.
+- No test covers first run with empty config.
+
+Solution:
+
+- Test `--help` for all top-level commands.
+- Test config load with temp directories.
+- Test one dry-run or offline smoke flow.
+- Test package build metadata.
+
+## 16. Integration Hard-Coding
+
+Problem: The CLI directly calls one delivery channel or one model provider throughout the app.
+
+Typical signs:
+
+- Feishu logic is embedded in report generation.
+- Adding DingTalk requires editing core flow code.
+- Provider-specific exceptions leak into UI.
+
+Solution:
+
+- Define integration interfaces.
+- Keep provider adapters small.
+- Return normalized result objects.
+- Let the main app depend on abstractions, not concrete CLIs.
+
+## 17. No Diagnostics Command
+
+Problem: Users cannot tell whether the failure is config, network, dependency, auth, or code.
+
+Typical signs:
+
+- Support requests include screenshots instead of diagnostic output.
+- The README has long manual troubleshooting sections.
+
+Solution:
+
+- Implement `doctor`.
+- Check Python version, package version, command path, config path, model provider, cache DB, optional CLIs, auth state, network reachability, and write permissions.
+- Provide `doctor --json` for bug reports.

cli_creator_skill/skills/cli-creator/references/review-rubric.md

@@ -0,0 +1,217 @@
+# CLI Review Rubric
+
+Use this rubric to audit an existing CLI. Score each category from 0 to 3 and mark urgent issues as P0/P1/P2.
+
+## Scoring
+
+- 0: Missing or actively harmful.
+- 1: Present but fragile or confusing.
+- 2: Mostly solid with clear improvement areas.
+- 3: Strong, tested, and user-friendly.
+
+## Severity
+
+- P0: Prevents normal use, risks data loss, leaks secrets, or breaks installation.
+- P1: Major UX, correctness, reliability, or maintainability issue.
+- P2: Improvement that reduces friction or future risk.
+
+## 1. Command Surface And First Run
+
+Check:
+
+- Does the installed command match the README?
+- Does `--help` work before config exists?
+- Is there a guided `setup`?
+- Is the main command obvious?
+- Are expert flags available for automation?
+
+Red flags:
+
+- Command not found after successful install.
+- First run immediately fails on missing config.
+- Users must read source code to configure providers.
+
+## 2. Interactive UX
+
+Check:
+
+- Does the CLI ask one natural question at a time?
+- Does it support free text, correction, refresh, and cancel?
+- Does refresh produce genuinely new options?
+- Does it avoid repeating questions?
+- Does it summarize before committing to a recommendation?
+
+Red flags:
+
+- Menus expose internal architecture.
+- All choices lead to the same output.
+- Profile collection feels like a form.
+
+## 3. Architecture And Modularity
+
+Check:
+
+- Is `cli.py` thin?
+- Are flows, services, LLM, persistence, rendering, and integrations separated?
+- Are Pydantic models used for structured data?
+- Can integrations be added without editing core flows?
+
+Red flags:
+
+- One large file owns everything.
+- Prompt strings, SQL, Rich rendering, and HTTP calls are mixed.
+
+## 4. Configuration And Secrets
+
+Check:
+
+- Are provider, base URL, model, and API key represented separately?
+- Are secrets masked in `config show`?
+- Are config paths documented?
+- Can users reset config safely?
+
+Red flags:
+
+- Full API keys printed to terminal.
+- Provider setup silently falls back to a wrong default.
+
+## 5. LLM Integration
+
+Check:
+
+- Is configuration verified with the actual model?
+- Are provider compatibility differences handled?
+- Is structured output validated?
+- Is there a fallback when instructor/tool mode is unsupported?
+- Are validation errors retried or explained?
+
+Red flags:
+
+- Empty user-facing results hide model failures.
+- All OpenAI-compatible providers are treated as identical.
+
+## 6. Data Fetching And Evidence
+
+Check:
+
+- Are recommendations grounded in source objects?
+- Are source URLs, dates, and metrics preserved?
+- Are fetch failures distinguishable from no results?
+- Are rate limits and timeouts handled?
+
+Red flags:
+
+- "Hot" topics have no evidence.
+- Social buzz is treated as fact without corroboration.
+
+## 7. Cache And Persistence
+
+Check:
+
+- Is cache keyed by query, window, source, filters, and schema version?
+- Are failed calls excluded from normal cache hits?
+- Can users clear cache?
+- Is profile memory separate from fetch cache?
+
+Red flags:
+
+- Refresh returns identical cached results.
+- Empty failures are cached as valid.
+- No clear profile command.
+
+## 8. Error Handling
+
+Check:
+
+- Are errors actionable?
+- Is `--debug` available?
+- Are likely causes and suggested commands shown?
+- Are cancellations graceful?
+
+Red flags:
+
+- Raw tracebacks in normal mode.
+- Generic "failed" messages.
+
+## 9. Performance
+
+Check:
+
+- Is startup fast?
+- Are heavy imports lazy?
+- Are network calls bounded by timeouts?
+- Are progress indicators used for slow operations?
+
+Red flags:
+
+- `--help` imports LLM/browser modules or probes network.
+- No timeout on HTTP calls.
+
+## 10. Testing
+
+Check:
+
+- Are help commands tested?
+- Is first-run empty config tested?
+- Are cache and profile operations tested?
+- Is there an offline smoke flow?
+- Is package metadata/entry point tested?
+
+Red flags:
+
+- Only utility functions are tested.
+- No installed-command test.
+
+## 11. Documentation
+
+Check:
+
+- Does README explain the product promise?
+- Are install, setup, run, config, doctor, and troubleshooting documented?
+- Are model provider examples included?
+- Are extension points documented?
+
+Red flags:
+
+- README examples do not match real commands.
+- No explanation of required model fields.
+
+## 12. Release And Maintenance
+
+Check:
+
+- Is Python version realistic for target users?
+- Are optional integrations optional dependencies?
+- Is release automation documented?
+- Are migrations handled for SQLite/config schema?
+
+Red flags:
+
+- Package requires a Python version unavailable on target machines without guidance.
+- Breaking config changes lack migrations.
+
+## Audit Output Format
+
+Use this format:
+
+```markdown
+**Findings**
+
+- [P0] Installed command does not match README
+  - Evidence: `pyproject.toml` defines `x`, README says `y`.
+  - Impact: users cannot start the CLI after install.
+  - Fix: change `[project.scripts]` or README and test clean install.
+
+**Scores**
+
+| Area | Score | Notes |
+|---|---:|---|
+| First run | 1/3 | Missing setup |
+| LLM config | 0/3 | Provider/base_url/model collapsed |
+
+**Recommended Repair Order**
+
+1. Fix entry point and first-run help.
+2. Add model setup verification.
+3. Separate cache failures from empty results.
+```

cli_creator_skill-0.1.0.dist-info/METADATA

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: cli-creator-skill
+Version: 0.1.0
+Summary: Installable cli-creator agent skill for designing and auditing Python CLI tools.
+Project-URL: Homepage, https://github.com/AdvancingTitans/cli-creator-skill
+Project-URL: Repository, https://github.com/AdvancingTitans/cli-creator-skill
+Project-URL: Issues, https://github.com/AdvancingTitans/cli-creator-skill/issues
+Author: yjw
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE.md
+Keywords: agent-skill,cli,codex,llm,questionary,rich,typer
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# cli-creator
+
+`cli-creator` is a reusable agent skill for designing, building, and auditing high-quality Python CLI tools.
+
+It is especially useful for Typer + Rich + questionary projects with interactive flows, data fetching, caching, LLM provider setup, structured output, local profile memory, and multi-channel delivery.
+
+## Install As A Codex Skill
+
+Clone this repository and copy the skill directory into your Codex skills folder:
+
+```bash
+git clone https://github.com/AdvancingTitans/cli-creator-skill.git
+mkdir -p ~/.codex/skills
+cp -R cli-creator-skill/skills/cli-creator ~/.codex/skills/cli-creator
+```
+
+Then ask your agent to use `cli-creator` when creating or reviewing CLI tools.
+
+## Install From PyPI
+
+```bash
+pip install cli-creator-skill
+cli-creator-skill install
+```
+
+By default this installs the skill to `~/.codex/skills/cli-creator`.
+
+Install to a custom directory:
+
+```bash
+cli-creator-skill install --target ~/.agents/skills
+```
+
+## PyPI Trusted Publisher
+
+This repository is ready for tag-driven PyPI publishing through GitHub Actions.
+
+Configure a pending publisher on PyPI with these exact values:
+
+```text
+PyPI project name: cli-creator-skill
+Owner: AdvancingTitans
+Repository name: cli-creator-skill
+Workflow name: publish.yml
+Environment name: pypi
+```
+
+After the pending publisher is configured, publishing is:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+## What This Skill Helps With
+
+- Design a new Python CLI from scratch.
+- Review an existing CLI for UX, packaging, errors, model setup, caching, and maintainability.
+- Structure Typer + Rich + questionary applications.
+- Build natural multi-turn CLI flows without making users feel like they are filling out a form.
+- Add robust model provider configuration for OpenAI, Anthropic, Ark/OpenAI-compatible endpoints, and local models.
+- Add cache, profile memory, diagnostics, and first-run setup flows.
+
+## Repository Structure
+
+```text
+cli-creator-skill/
+  skills/cli-creator/
+    SKILL.md
+    references/
+      creation-playbook.md
+      pitfalls-and-solutions.md
+      review-rubric.md
+  src/cli_creator_skill/
+    installer.py
+    __main__.py
+  pyproject.toml
+  README.md
+  LICENSE
+```
+
+## Usage
+
+Use this skill when you ask:
+
+- "帮我从零设计一个 Python CLI"
+- "帮我审查这个 Typer CLI"
+- "这个 CLI 的交互很别扭，帮我重构"
+- "帮我设计模型配置、缓存、doctor、profile memory"
+- "帮我发布一个可 pip install 的 CLI"
+
+## Sources And Design Influences
+
+This skill distills practical lessons from building interactive Python CLIs and from studying mature CLI projects and documentation patterns, including:
+
+- [larksuite/cli](https://github.com/larksuite/cli)
+- [soongenwong/claudecode](https://github.com/soongenwong/claudecode)
+- [Astral uv](https://github.com/astral-sh/uv)
+- [Astral ruff](https://github.com/astral-sh/ruff)
+- Typer, Rich, questionary, Pydantic, litellm, and instructor project practices
+
+## License
+
+MIT

cli_creator_skill-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+cli_creator_skill/__init__.py,sha256=7tSbeov-Nzm1Y499GNsAEqJUftdzMfNdOPET4esn_Cw,74
+cli_creator_skill/__main__.py,sha256=Cnfu30AwCdIIm7aEj0BASh8PFoVyJsQcOewAbkmrtGU,68
+cli_creator_skill/installer.py,sha256=QIInZSxgPBJ2Xz7cTF9psmrqSlfD7g38K9wGRxjUhew,1901
+cli_creator_skill/skills/cli-creator/SKILL.md,sha256=5XAtMcFZAOXQtpDJFLLObKGITGw9DdWksfaEinEJc5o,11807
+cli_creator_skill/skills/cli-creator/references/creation-playbook.md,sha256=IEwI_9zmmtc6REMuzcOlkINjXEGJfNduOXk0LF49Kjw,6444
+cli_creator_skill/skills/cli-creator/references/pitfalls-and-solutions.md,sha256=Gg7FWHFbFKzzZw-W3J81qaNSz0sE2jDAhE-K5ICGUp4,9324
+cli_creator_skill/skills/cli-creator/references/review-rubric.md,sha256=Hd5Tr-cehdD0GK2S4EZmDy8H1LB_j5M7VrDWfsEsYPQ,5204
+cli_creator_skill-0.1.0.dist-info/METADATA,sha256=CCppR9bpaqWruLEXu3tWjxgtcS3PT4mJ-e7o14btaKU,4014
+cli_creator_skill-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+cli_creator_skill-0.1.0.dist-info/entry_points.txt,sha256=bH_N0foJtwUyJQ2XYXhQQ5EqFy6dhnA7efWxQWacuHc,71
+cli_creator_skill-0.1.0.dist-info/licenses/LICENSE,sha256=Tp84I2PKkZjKSunDQaJIH1fm6iLWSluvk-ejVBiYWq0,1060
+cli_creator_skill-0.1.0.dist-info/licenses/NOTICE.md,sha256=SBDg7TQ9EpYtzo-bFUtJV0mmOwZRGb9Z7JteUd3IE1I,213
+cli_creator_skill-0.1.0.dist-info/RECORD,,

cli_creator_skill-0.1.0.dist-info/WHEEL

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

cli_creator_skill-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cli-creator-skill = cli_creator_skill.installer:main

cli_creator_skill-0.1.0.dist-info/licenses/LICENSE

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

cli_creator_skill-0.1.0.dist-info/licenses/NOTICE.md

@@ -0,0 +1,5 @@
+# Notice
+
+`cli-creator` is a reusable skill authored from practical CLI development experience.
+
+External design references are credited in `README.md`. No code from those projects is vendored in this repository.