Agent CLI: build a full custom terminal wrapper for skill execution

[zzap]

Problem

This project has useful skill definitions in .agents/skills, but today they depend on a specific agent environment to be discovered and executed. That means contributors and users cannot rely on a standard, open-source terminal workflow to run skills like generate-static-docs, create-changelog, or create-github-issues.

Because this tool is intended to be free and open source for broad public use, we should not assume a specific editor, hosted agent product, operating system setup, or preinstalled developer stack beyond what the project itself can document and validate. We need a portable CLI workflow that works as the public entrypoint for skill-based task execution.

Solution

Build a first-party agent CLI wrapper for Doc2Me that can run from the terminal, load repo skills from .agents/skills, expose a safe execution model, and orchestrate project tasks through a consistent interface.

The CLI should:

• discover available skills from the repository
• load and apply SKILL.md instructions
• execute bounded local tools such as shell commands, file reads, and file writes
• support approvals for risky or destructive actions
• provide clear setup instructions for users with unknown tech stacks
• work as an open-source reference implementation rather than depending on a proprietary IDE integration

The goal is a user experience closer to doc2me-agent run create-changelog than “copy this prompt into a chat tool and hope the environment supports it.”

Execution

1. Define the CLI contract.
   Create a command surface for listing skills, running a skill, passing arguments, and previewing planned actions. Include a non-interactive mode and an approval-aware interactive mode.

2. Design the runtime architecture.
   Add a small agent runtime that can:

• load skill metadata and instructions from .agents/skills
• map a user request to a selected skill
• build prompt/context input for the model
• expose tool adapters for shell, filesystem, and git-aware repo inspection
• capture outputs and stream progress back to the terminal

3. Implement safe tool execution.
   Add explicit rules for what commands can run automatically, what requires confirmation, and how file edits are applied. The runtime should avoid assuming platform-specific package managers or shells beyond documented minimum support.

4. Add environment validation.
   Before running a skill, check required tools and report actionable setup guidance. This should be capability-based rather than stack-assumptive, so users get “missing tool / version / install guidance” instead of silent failure.

5. Add skill discovery and help output.
   Implement list-skills, show-skill, and run commands so users can inspect available skills and understand what each one does before execution.

6. Make execution reproducible.
   Log the selected skill, commands run, files changed, and any approvals requested. This should make agent runs auditable and easier to debug in an open-source setting.

7. Document the public workflow.
   Update the README with terminal-first usage examples, setup steps, auth requirements where relevant, and examples for running skills end to end.

8. Validate with existing skills.
   Use generate-static-docs, create-changelog, and create-github-issues as initial acceptance cases to prove the wrapper can load repo skills and execute realistic multi-step tasks.