lov-cli-creator skill

CLI 工坊 · CLI Studio

Turn a real local project into an installable command-line interface that both people and agents can operate. The generated CLI exposes the project's actual backend, emits stable JSON, documents its contract, and carries executable tests.

Triggers

Activate when

• “给这个项目做一个 CLI”“把当前应用变成命令行”“为这个仓库生成 Agent CLI”。
• “从这个项目路径输出一个可安装的命令行工具”。
• “Build a CLI for this project” or “make this application agent-accessible”.
• The user wants to refine or validate a CLI previously generated by this Skill.

Do not activate when

• The user only wants a new Web/Tauri application; use an app-generation workflow.
• The user only needs one shell alias or a single ad-hoc command, not a maintained CLI.
• The user asks to publish a package or release; this Skill stops at a locally installed and verified CLI.
• The target is a closed binary with no callable API, scripting surface, protocol, or native file format. Diagnose the missing backend boundary before generating.

User Profile (cross-session)

Read skill.yaml on every invocation. Resolve values in this order: the current request, project context, skills.lov-cli-creator.records, shared preferences, the shared user/workspace Profile, then safe defaults. Project path defaults to the directory in which the Skill is invoked; output defaults to agent-harness/ inside that project.

Persist only a directly stated durable preference, such as a user's long-term command prefix or output-directory convention:

python3 "$SKILL_DIR/scripts/profile_store.py" record \
  --skill-id lov-cli-creator \
  --path records.command_prefix \
  --value '"lov-cli"' \
  --confirm

Report the saved Profile path. Never persist inferred paths, credentials, or tokens. See the Profile contract.

Skill Group Composition

Read the composition record before invoking an adjacent Skill. lov-cli-creator owns the finished CLI; other Skills are optional artifact-level handoffs and never hidden runtime dependencies.

Workflow (MANDATORY)

Follow these steps in order. Do not report a scaffold as a completed CLI.

Step 0: Resolve the Skill and target project

1. Resolve SKILL_DIR from the active Skill context.
2. Resolve the target from the user's path; if omitted, use the Skill invocation working directory, not the installed Skill directory.
3. Resolve symlinks, confirm the directory exists, and read applicable AGENTS.md, CLAUDE.md, repository instructions, and dirty-worktree state.
4. Preserve unrelated files and changes. Never overwrite an occupied output directory with the scaffold helper.

Manual helper invocation:

python3 "$SKILL_DIR/scripts/inspect_project.py" . --format markdown

Step 1: Analyze the real callable surface

Run the inspector and then verify its signals against source code:

python3 "$SKILL_DIR/scripts/inspect_project.py" PROJECT \
  --format json --output PROJECT_ANALYSIS.json

Identify the product domains, existing commands, public APIs, native data model, state lifecycle, export/render path, and external runtime dependencies. Map user actions to real callable functions or executables. Prefer, in order:

1. an existing project CLI or scripting API;
2. the project's public library/service API;
3. direct manipulation of its documented native format followed by its real renderer or runtime;
4. a narrow subprocess or protocol adapter.

Do not rebuild the product in the harness. For GUI/media applications, rendering must use the real engine. For services, use the real local service/API boundary. For libraries, call the public API rather than copying implementation logic. Read project analysis rules.

Step 2: Design the CLI contract before generating files

Define command groups around user tasks, not source filenames. Every CLI must include doctor, info, and capabilities, plus at least one project-specific command. Every command must work in human-readable mode and with global --json.

Write a lov-cli-plan/v1 JSON plan. For existing executables, declare fixed argv prefixes and typed parameters so the generated bridge can be complete without shell evaluation. For an in-process library or protocol, use the plan to scaffold the command contract, then implement the adapter in generated source.

Read the plan schema and the CLI contract. Include:

• command name, description, inputs, output, mutability, and exit behavior;
• state persistence, concurrency, undo/redo, and idempotency rules when relevant;
• real backend dependency and install diagnostics;
• output verification for every export or mutation with a material artifact.

Step 3: Scaffold the harness

Generate into PROJECT/agent-harness unless the request or Profile supplies a different output directory:

python3 "$SKILL_DIR/scripts/scaffold_cli.py" PROJECT \
  --plan CLI_PLAN.json

The helper creates a Python package, console entry point, JSON contract, backend bridge, README, test plan, and tests. It rejects occupied output paths. Use --output only when a separate location is required. The default console command is lov-cli-PROJECT_SLUG, unless the plan declares another safe kebab-case name.

If an existing generated harness is present, inspect and refine it in place. Never discard working commands merely to rerun the scaffold.

Step 4: Complete the real backend adapter

The generated subprocess bridge is production-usable when the plan fully maps an existing executable. Otherwise implement the missing adapter in src/PACKAGE/backend.py and register its typed command handler in cli.py.

Requirements:

• use argument arrays with shell=False; never concatenate untrusted shell text;
• resolve executables explicitly and return actionable dependency errors;
• make read-before-write introspection cheap;
• return stable JSON envelopes and nonzero exit codes on failure;
• verify postconditions instead of trusting exit status alone;
• auto-save one-shot state mutations unless --dry-run is set;
• lock persistent session files when concurrent writes are possible;
• keep secrets out of argv echoes, logs, JSON, and generated source.

For stateful tools, support both one-shot commands and a REPL only when a REPL adds genuine value. Do not force statefulness onto a stateless project.

Step 5: Test the installed command through real workflows

Complete TEST.md as a plan before adding test code. Keep fast unit tests and real end-to-end tests. The E2E suite must invoke the installed console command from outside the harness directory, exercise at least one project-specific workflow, and verify resulting state or artifacts programmatically.

Install into an isolated environment or the project-approved environment:

python3 -m pip install -e PROJECT/agent-harness
python3 -m unittest discover -s PROJECT/agent-harness/tests -v

When a Python 3.9 venv bundles pip older than 21.3, install the generated requirements.txt and run python3 setup.py develop from the harness as the local editable-install fallback. Do not require a network-only pip upgrade.

If the backend dependency is unavailable, the real-backend E2E test fails with installation guidance; it must not silently skip or replace the backend. Read the testing requirements.

Step 6: Mark ready and validate

Set status in lov-cli.json to ready only after the domain commands and E2E tests pass. Then run:

python3 "$SKILL_DIR/scripts/validate_cli.py" PROJECT/agent-harness \
  --run-tests --require-installed

Validation must confirm the package entry point, source/module invocation, JSON envelopes, built-in introspection, at least one domain command, unit/E2E tests, and the installed command from a neutral working directory.

Step 7: Report the finished artifact

Report the target project, harness path, installed command, command groups, backend used, tests and validation results, and any verified limitation. Clearly separate local readiness from package publication; publication is outside scope.

Dependencies

• Python 3.9+ to run the helpers and generated standard-library CLI.
• The target project's real runtime or executable for backend validation.
• PyYAML only for validating this Skill source with scripts/validate_skill.py.

Provenance

This workflow adapts the CLI-Anything agent-harness methodology while broadening it from GUI applications to local projects and replacing legacy packaging rules with a small PEP 621 harness. See upstream research for the source, license, and deliberate differences.

Runtime context (shared)

运行前读取本 Skill 包的 skill.yaml。只使用 Manifest 声明的字段；Profile 保存用户和工作区长期偏好，skills.lov-cli-creator.records 保存本 Skill 的持久 记录。报错提供可复制的 context_id、字段路径与来源，诊断不得泄露秘密。