diff --git a/README.md b/README.md index 72d6b874..9ffd8c96 100644 --- a/README.md +++ b/README.md @@ -140,7 +140,7 @@ That's it. Install and update via `@imdeadpool/guardex`. Setup installs the mini > [!NOTE] -> In this repo, `CLAUDE.md` is a symlink to `AGENTS.md`, so Claude reads the same contract. Optional Codex/Claude companion files are installed at the user level with `gx install-agent-skills`, not copied into each repo. +> In this repo, `CLAUDE.md` is a symlink to `AGENTS.md`, so Claude reads the same contract. Optional Codex/Claude companion files still install at the user level with `gx install-agent-skills`, while the generic repo skill catalog is available through `npx skills add recodeee/gitguardex`. ### Decision flow @@ -459,6 +459,19 @@ npm i -g oh-my-claude-sisyphus@latest Repo: [![GitHub stars](https://img.shields.io/github/stars/Yeachan-Heo/oh-my-claudecode?style=social)](https://github.com/Yeachan-Heo/oh-my-claudecode) +### GitGuardex skills - install the repo skill catalog through `npx skills` + +For agents that already support the generic `skills` installer flow, GitGuardex now exposes its repo skill catalog directly. That lets the installer show the available Guardex skills first, then install only the one you want. + +```sh +npx skills add recodeee/gitguardex +``` + +This repo currently exposes `gitguardex` and `guardex-merge-skills-to-dev` through that flow. Use `gx install-agent-skills` when you want the Codex/Claude user-home startup files instead of the generic `skills` catalog. + +Repo: +[![GitHub stars](https://img.shields.io/github/stars/recodeee/gitguardex?style=social)](https://github.com/recodeee/gitguardex) + ### Caveman — output compression for long agent runs Ultra-compressed response mode for Claude/Codex-style agents. Useful when you want less output-token churn during long reviews, debug loops, or multi-agent sessions. @@ -609,7 +622,7 @@ vscode/guardex-active-agents/README.md Legacy compatibility note: older repos may still contain repo-local workflow scripts under `scripts/`. Direct `gx branch ...`, `gx locks ...`, `gx finish`, `gx cleanup`, `gx merge`, and `gx migrate` do not require them. `gx migrate` removes those leftover workflow shims by default. The CLI still honors repo-local `scripts/review-bot-watch.sh` and `scripts/codex-agent.sh` when they are already present so older repos can keep working during migration. -Optional Codex/Claude user-level companions still install with `gx install-agent-skills`; they are not copied into each repo. +Optional Codex/Claude user-level companions still install with `gx install-agent-skills`; the generic repo skill catalog is available with `npx skills add recodeee/gitguardex`. Neither path copies those user-home files into each repo. --- diff --git a/openspec/changes/agent-codex-add-npx-skills-install-surface-2026-04-23-17-47/notes.md b/openspec/changes/agent-codex-add-npx-skills-install-surface-2026-04-23-17-47/notes.md new file mode 100644 index 00000000..ccbee65a --- /dev/null +++ b/openspec/changes/agent-codex-add-npx-skills-install-surface-2026-04-23-17-47/notes.md @@ -0,0 +1,5 @@ +# T1 Notes + +- Add a repo-root `skills/` catalog so `npx skills add recodeee/gitguardex` shows the Guardex skills the same way Caveman does. +- Keep the existing `gx install-agent-skills` path for Codex/Claude user-home startup files; this change adds a generic skills-installer path, not a replacement. +- Keep the merge-helper runbook and README aligned with the new root skill paths so future skill-only lanes do not miss them. diff --git a/skills/gitguardex/SKILL.md b/skills/gitguardex/SKILL.md new file mode 100644 index 00000000..e156736c --- /dev/null +++ b/skills/gitguardex/SKILL.md @@ -0,0 +1,11 @@ +--- +name: gitguardex +description: "Repo guardrail check and repair." +--- + +Use when repo safety may be broken. + +`gx status` -> `gx doctor` -> `gx status --strict` + +Bootstrap: `gx setup` +Ops: `gx branch start "" ""`, `gx locks claim --branch "" `, `gx branch finish --branch "" --base --via-pr --wait-for-merge --cleanup`, `gx finish --all`, `gx cleanup` diff --git a/skills/guardex-merge-skills-to-dev/SKILL.md b/skills/guardex-merge-skills-to-dev/SKILL.md new file mode 100644 index 00000000..3c86076a --- /dev/null +++ b/skills/guardex-merge-skills-to-dev/SKILL.md @@ -0,0 +1,59 @@ +--- +name: guardex-merge-skills-to-dev +description: "Use when you need to merge SKILL.md updates from agent branches/worktrees into the local base branch (default: dev) with the multiagent-safety flow." +--- + +# GuardeX Merge Skills to dev + +Use this skill when you only want to promote Codex skill file updates into the base branch (normally `dev`) without editing the visible base checkout directly. + +## What this merges + +- `skills/**/SKILL.md` +- `.codex/skills/**/SKILL.md` +- `templates/codex/skills/**/SKILL.md` + +## Merge runbook (safe path) + +1. Resolve the base branch: + +```sh +BASE_BRANCH="$(git config --get multiagent.baseBranch || echo dev)" +echo "$BASE_BRANCH" +``` + +2. Start a dedicated integration sandbox from base: + +```sh +gx branch start "merge-skill-files-to-${BASE_BRANCH}" "skill-merge" "$BASE_BRANCH" +``` + +3. Enter the sandbox worktree printed by the command above. + +4. Pull only skill files from each source agent branch: + +```sh +SOURCE_BRANCH="" +git checkout "$SOURCE_BRANCH" -- ':(glob)skills/**/SKILL.md' ':(glob).codex/skills/**/SKILL.md' ':(glob)templates/codex/skills/**/SKILL.md' +``` + +5. Verify scope before commit: + +```sh +git status --short +git diff --name-only +``` + +6. Commit and merge back to base using guardex finish flow: + +```sh +git add skills .codex/skills templates/codex/skills +git commit -m "Merge skill file updates into ${BASE_BRANCH}" +gx branch finish --branch "$(git rev-parse --abbrev-ref HEAD)" --base "$BASE_BRANCH" --via-pr --wait-for-merge --cleanup +``` + +## Notes + +- If a source branch has non-skill changes, this runbook keeps them out of the merge. +- If merge conflicts occur, resolve only within the skill files, then rerun `gx branch finish`. +- Do not commit directly on `dev`/`main`; always merge through an agent branch/worktree. diff --git a/templates/codex/skills/guardex-merge-skills-to-dev/SKILL.md b/templates/codex/skills/guardex-merge-skills-to-dev/SKILL.md index dc2920f2..3c86076a 100644 --- a/templates/codex/skills/guardex-merge-skills-to-dev/SKILL.md +++ b/templates/codex/skills/guardex-merge-skills-to-dev/SKILL.md @@ -9,6 +9,7 @@ Use this skill when you only want to promote Codex skill file updates into the b ## What this merges +- `skills/**/SKILL.md` - `.codex/skills/**/SKILL.md` - `templates/codex/skills/**/SKILL.md` @@ -33,7 +34,7 @@ gx branch start "merge-skill-files-to-${BASE_BRANCH}" "skill-merge" "$BASE_BRANC ```sh SOURCE_BRANCH="" -git checkout "$SOURCE_BRANCH" -- ':(glob).codex/skills/**/SKILL.md' ':(glob)templates/codex/skills/**/SKILL.md' +git checkout "$SOURCE_BRANCH" -- ':(glob)skills/**/SKILL.md' ':(glob).codex/skills/**/SKILL.md' ':(glob)templates/codex/skills/**/SKILL.md' ``` 5. Verify scope before commit: @@ -46,7 +47,7 @@ git diff --name-only 6. Commit and merge back to base using guardex finish flow: ```sh -git add .codex/skills templates/codex/skills +git add skills .codex/skills templates/codex/skills git commit -m "Merge skill file updates into ${BASE_BRANCH}" gx branch finish --branch "$(git rev-parse --abbrev-ref HEAD)" --base "$BASE_BRANCH" --via-pr --wait-for-merge --cleanup ``` diff --git a/test/metadata.test.js b/test/metadata.test.js index 96df2537..46adae4c 100644 --- a/test/metadata.test.js +++ b/test/metadata.test.js @@ -71,6 +71,26 @@ test('README documents gx release as README-driven GitHub release writer', () => assert.match(readme, /finds the last published GitHub release, and writes one grouped GitHub release body/); }); +test('README advertises the repo skills installer path and root skills stay in sync with shipped templates', () => { + const readme = fs.readFileSync(readmePath, 'utf8'); + assert.match(readme, /npx skills add recodeee\/gitguardex/); + + const pairs = [ + ['templates/codex/skills/gitguardex/SKILL.md', 'skills/gitguardex/SKILL.md'], + ['templates/codex/skills/guardex-merge-skills-to-dev/SKILL.md', 'skills/guardex-merge-skills-to-dev/SKILL.md'], + ]; + + for (const [templatePath, rootSkillPath] of pairs) { + const template = fs.readFileSync(path.join(repoRoot, templatePath), 'utf8'); + const rootSkill = fs.readFileSync(path.join(repoRoot, rootSkillPath), 'utf8'); + assert.equal( + rootSkill, + template, + `${rootSkillPath} diverged from ${templatePath}; keep the repo-root skills catalog aligned with shipped templates`, + ); + } +}); + test('README keeps canonical About copy and problem-solution visuals aligned', () => { const readme = fs.readFileSync(readmePath, 'utf8'); const aboutDescription = fs.readFileSync(aboutDescriptionPath, 'utf8').trim();