From 524d5534fd001f62bbdae0521f11c64614309884 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Tue, 30 Jun 2026 09:28:15 +0000 Subject: [PATCH 1/2] docs(cli): improve AI agent support and refine quickstart output - Add "For AI Agents" section to README with prompt template and recipes. - Update quickstart command recipes to include --json, --yes, and --all for agent safety. - Refine quickstart terminal output to strip agent-safe flags for human readability. - Bump version to 0.9.1 across workspace packages. - Add tests for agent-safe quickstart JSON and CLI versioning. - Update CHANGELOG with 0.9.1 release notes. Co-authored-by: travelhawk <7582909+travelhawk@users.noreply.github.com> --- CHANGELOG.md | 8 +++++- README.md | 50 ++++++++++++++++++++++++++++++++++++ apps/cli/src/index.ts | 28 +++++++++++--------- tests/update-and-cli.test.ts | 38 +++++++++++++++++++++++++++ 4 files changed, 111 insertions(+), 13 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1667f16..c62c6ee 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index 7cdfd3f..815073d 100644 --- a/README.md +++ b/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 codex,claude,generic --yes --json`. +- When pushing a local canonical library, use `agentpm push --all --to --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 --target codex,claude,generic --yes --json`. +5. Pull shared skills with `agentpm pull --from --target codex,claude,generic --yes --json`. +6. Push the canonical library with `agentpm push --all --to --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. diff --git a/apps/cli/src/index.ts b/apps/cli/src/index.ts index 4142acc..00f35fa 100644 --- a/apps/cli/src/index.ts +++ b/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()); diff --git a/tests/update-and-cli.test.ts b/tests/update-and-cli.test.ts index a6f4f66..715cfba 100644 --- a/tests/update-and-cli.test.ts +++ b/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 () => { From 8928f82371107adf06e406441b3002473c4bfac3 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Tue, 30 Jun 2026 09:41:55 +0000 Subject: [PATCH 2/2] docs(cli): improve AI agent support and refine quickstart output - Add "For AI Agents" section to README with prompt template and recipes. - Update quickstart command recipes to include --json, --yes, and --all for agent safety. - Refine quickstart terminal output to strip agent-safe flags for human readability. - Bump version to 0.9.1 across workspace packages. - Add tests for agent-safe quickstart JSON and CLI versioning. - Update CHANGELOG with 0.9.1 release notes. Co-authored-by: travelhawk <7582909+travelhawk@users.noreply.github.com>