Review and refinement of AI agent support in AgentPM

CHANGELOG.md

@@ -8,7 +8,13 @@ This repo uses a simple release workflow:
 - each release-facing cycle bumps the workspace package versions together
 - changelog and version bumps should land in the same commit when practical
 
-## [0.9.1] - 2026-06-29
+## [0.9.1] - 2026-06-30
+
+
+### Added
+
+- Added a README prompt and command recipe for AI agents to install and operate AgentPM without TTY menus, using explicit selectors, `--yes`, `--all`, and `--json`.
+- Updated quickstart command recipes so `agentpm quickstart --json` returns non-interactive, agent-safe commands.
 
 ### Fixed
 

README.md

@@ -91,6 +91,56 @@ agentpm pull --from my-skills
 
 Add `--target codex,claude,generic` to control which runtimes receive pulled skills.
 
+## For AI Agents
+
+AgentPM is safe to drive from another coding agent when the agent avoids prompt-driven flows. Use explicit selectors, explicit targets, `--yes` for confirmations, `--all` for bulk push, and `--json` whenever output will be parsed.
+
+Copy this prompt into an AI coding agent that has shell access:
+
+```text
+You are organizing this machine's AI coding skills with AgentPM. Work non-interactively: never rely on TTY menus, pickers, or confirmation prompts. Prefer commands with --json for inspection, and use explicit flags such as --from, --skill, --target, --yes, --all, --project, or --global.
+
+Goal:
+- Install AgentPM if it is missing.
+- Inspect the current AgentPM state.
+- Adopt existing local skills from Codex, Claude, and generic agent folders into AgentPM's canonical library.
+- Optionally sync the canonical library to the configured Git target.
+- Leave the system in a recoverable state and report exactly what changed.
+
+Rules:
+- Before changing anything, run `agentpm --version`, `agentpm --help`, `agentpm quickstart --json`, `agentpm target list --json`, `agentpm source list --json`, `agentpm list --json`, and `agentpm doctor --json`.
+- If `agentpm` is not installed, install it with `npm install -g @travelhawk/agentpm`, then rerun the inspection commands.
+- Do not run commands that open selection menus. If a command would need a choice, rerun it with explicit names, paths, `--from`, `--skill`, `--target codex,claude,generic`, `--yes`, or `--all`.
+- Adopt local skills one explicit path at a time, for example `agentpm adopt ~/.claude/skills/my-skill --target codex,generic --yes --json`.
+- When pulling a shared library, use `agentpm pull --from <target-id-or-repo> --target codex,claude,generic --yes --json`.
+- When pushing a local canonical library, use `agentpm push --all --to <target-id-or-repo> --message "Sync skills" --json`.
+- After changes, run `agentpm doctor --json`; if safe fixes are reported, run `agentpm doctor --fix --yes --json`.
+- Never delete or overwrite unmanaged skill folders unless AgentPM explicitly confirms they are managed links or the user has approved that exact path.
+- Finish with a concise report: installed AgentPM version, adopted skills, linked targets, pushed revision if any, doctor status, warnings, and commands run.
+
+Suggested workflow:
+1. Check whether AgentPM exists: `agentpm --version` and `agentpm --help`.
+2. If missing: `npm install -g @travelhawk/agentpm`.
+3. Inspect state with JSON: `agentpm quickstart --json`, `agentpm list --json`, `agentpm target list --json`, `agentpm doctor --json`.
+4. Adopt explicit local skill paths with `agentpm adopt <path> --target codex,claude,generic --yes --json`.
+5. Pull shared skills with `agentpm pull --from <target-id-or-repo> --target codex,claude,generic --yes --json`.
+6. Push the canonical library with `agentpm push --all --to <target-id-or-repo> --message "Sync skills" --json`.
+7. Validate with `agentpm doctor --json` and, if appropriate, `agentpm doctor --fix --yes --json`.
+```
+
+Agent-safe examples:
+
+```bash
+agentpm --version
+agentpm quickstart --json
+agentpm list --json
+agentpm doctor --json
+agentpm adopt ~/.claude/skills/release-helper --target codex,generic --yes --json
+agentpm pull --from my-skills --target codex,claude,generic --yes --json
+agentpm push --all --to my-skills --message "Sync skills" --json
+agentpm doctor --fix --yes --json
+```
+
 ## What AgentPM Does Well
 
 - `📦` Install skills from Git repositories, local folders, static registries, and the public `skills.sh` bridge.

apps/cli/src/index.ts

@@ -52,9 +52,9 @@ const QUICKSTART_GUIDES: Record<
     title: 'Install One Skill',
     goal: 'Find a skill and install it into your current machine or repo.',
     commands: [
-      'agentpm skills search typescript',
-      'agentpm skills install typescript --project',
-      'agentpm list',
+      'agentpm skills search typescript --json',
+      'agentpm skills install wshobson/agents@typescript-advanced-types --project --yes --json',
+      'agentpm list --json',
     ],
     notes: [
       'Use this when you want a one-off skill without managing a shared repo yet.',
@@ -65,10 +65,10 @@ const QUICKSTART_GUIDES: Record<
     title: 'Set Up a Team Repo',
     goal: 'Turn a repository into a reproducible team contract with agentpm.yaml.',
     commands: [
-      'agentpm source add travelhawk/skills-vault',
-      'agentpm install --from travelhawk/skills-vault --skill release-helper --project --add-source',
-      'agentpm init',
-      'agentpm sync',
+      'agentpm source add travelhawk/skills-vault --json',
+      'agentpm install --from travelhawk/skills-vault --skill release-helper --project --add-source --yes --json',
+      'agentpm init --json',
+      'agentpm sync --json',
     ],
     notes: [
       'Use this when your repo should declare required skills for everyone who clones it.',
@@ -79,9 +79,9 @@ const QUICKSTART_GUIDES: Record<
     title: 'Sync Skills Across Machines',
     goal: 'Publish canonical skills to a Git repo and pull them onto another device.',
     commands: [
-      'agentpm target add my-skills travelhawk/skills-vault --default',
-      'agentpm push',
-      'agentpm pull --from my-skills',
+      'agentpm target add my-skills travelhawk/skills-vault --default --json',
+      'agentpm push --all --to my-skills --json',
+      'agentpm pull --from my-skills --target codex,claude,generic --yes --json',
     ],
     notes: [
       'Use this when you want one canonical skill library that fans out to Codex, Claude, and generic agents.',
@@ -132,7 +132,11 @@ function printQuickstart(flow?: QuickstartFlow): void {
     console.log(`  ${style.bold(guide.title)} (${id})`);
     console.log(`    ${guide.goal}`);
     for (const command of guide.commands) {
-      console.log(`    ${symbols.arrow} ${style.cyan(command)}`);
+      // Strip --json and --yes for human readability in terminal output
+      const humanCommand = command
+        .replace(/\s--json(\s|$)/g, '$1')
+        .replace(/\s--yes(\s|$)/g, '$1');
+      console.log(`    ${symbols.arrow} ${style.cyan(humanCommand)}`);
     }
     for (const note of guide.notes) {
       console.log(`    ${symbols.bullet} ${note}`);
@@ -718,7 +722,7 @@ const rawCliArgs = process.argv.slice(2);
 program
   .name('agentpm')
   .description('Git-native skill and agent asset manager')
-  .version('0.9.0')
+  .version('0.9.1')
   .exitOverride()
   .showHelpAfterError(false)
   .addHelpText('beforeAll', brandBlock());

tests/update-and-cli.test.ts

@@ -894,6 +894,44 @@ describe('update and cli flows', () => {
     CI_TEST_TIMEOUT,
   );
 
+  test(
+    'prints agent-safe quickstart commands as JSON',
+    async () => {
+      const { stdout } = await runCli(['quickstart', '--json'], {
+        cwd: path.resolve('.'),
+      });
+      const payload = JSON.parse(stdout) as {
+        guides: Array<{ id: string; commands: string[] }>;
+      };
+      const commands = payload.guides.flatMap((guide) => guide.commands);
+      expect(commands).toContain('agentpm push --all --to my-skills --json');
+      expect(commands).toContain(
+        'agentpm pull --from my-skills --target codex,claude,generic --yes --json',
+      );
+      expect(commands).not.toContain('agentpm push');
+      expect(
+        commands.every(
+          (command) => !command.includes(' --json') || command.endsWith('--json'),
+        ),
+      ).toBe(true);
+    },
+    CI_TEST_TIMEOUT,
+  );
+
+  test(
+    'prints the package version through the CLI',
+    async () => {
+      const packageJson = JSON.parse(
+        await fs.readFile(path.join('apps', 'cli', 'package.json'), 'utf8'),
+      ) as { version: string };
+      const { stdout } = await runCli(['--version'], {
+        cwd: path.resolve('.'),
+      });
+      expect(stdout.trim()).toBe(packageJson.version);
+    },
+    CI_TEST_TIMEOUT,
+  );
+
   test(
     'prints command-specific help examples for source add',
     async () => {