Skip to content

Commit f83a7ec

Browse files
committed
fix: drop copilot per-scope path override, use .agents/skills both ways
The user-scope copilot install was landing at ~/.copilot/skills/, but the bundled x-x skill content (agents/skills/x-plan/SKILL.md and agents/skills/x-x/SKILL.md) defines `<skills_root>` as only `.claude/skills/` (Claude Code) or `.agents/skills/` (other agents). The agent's path-resolution logic globs that exact list and never searches `~/.copilot/skills/`, so sibling files like `_x-x_shared/_plan_first.md` were undiscoverable at user scope. `~/.agents/skills/` is on Copilot CLI's official user-scope list alongside `~/.copilot/skills/` (docs.github.com/en/copilot/how-tos/ copilot-cli/customize-copilot/add-skills), so reusing the cross-agent open spec path at user scope is conformant — and it lets the bundled skill content work unchanged. agentTarget.userSkillsRel stays on the struct for future agents whose project- vs user-scope paths genuinely diverge; copilot doesn't need it anymore. Cleanup: - constants.go: copilot row's userSkillsRel back to empty. - scripts/e2e_test.sh + ps1: drop COPILOT_USER_SKILLS_REL constant, update the user-scope copilot e2e case to assert on `~/.agents/skills`. - docs/public/reference.md + getting-started.md: prose updated. Signed-off-by: Tanzim Saqib <[email protected]>
1 parent ad34581 commit f83a7ec

5 files changed

Lines changed: 55 additions & 49 deletions

File tree

‎constants.go‎

Lines changed: 16 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -141,15 +141,22 @@ var agentTargets = []agentTarget{
141141
{"codex", "Codex CLI", ".agents/skills", "", "codex", ".codex"},
142142
// GitHub Copilot CLI reads skills from `.agents/skills/`, `.claude/skills/`,
143143
// or `.github/skills/` at project scope, and `~/.copilot/skills/` or
144-
// `~/.agents/skills/` at user scope. We pick `.agents/skills` for project
145-
// (cross-agent open spec, already populated by codex when both are picked
146-
// — install is idempotent) and `~/.copilot/skills` for user (the Copilot-
147-
// native path, distinct from codex's `~/.agents/skills`). Skills-only for
148-
// now — no settings.json / hooks file shipped yet; that's a follow-up
149-
// once the manual eval workflow tells us which Copilot CLI lifecycle
150-
// hooks make sense to register. Official path docs:
151-
// docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills.
152-
{"copilot", "GitHub Copilot CLI", ".agents/skills", ".copilot/skills", "", ""},
144+
// `~/.agents/skills/` at user scope (per Copilot CLI's May 2026 docs at
145+
// docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills).
146+
// We use `.agents/skills` at BOTH scopes — the cross-agent open spec
147+
// path. Reasons:
148+
// 1. agents/skills/x-plan/SKILL.md and agents/skills/x-x/SKILL.md
149+
// define `<skills_root>` as exactly `.claude/skills/` (Claude) or
150+
// `.agents/skills/` (other agents). The agent's path-resolution
151+
// logic globs that exact list — `.copilot/skills` is not in it.
152+
// 2. `~/.agents/skills` is on Copilot CLI's official user-scope list
153+
// alongside `~/.copilot/skills`. Both work for skill discovery.
154+
// 3. Reusing `.agents/skills` co-locates with Codex (install is
155+
// idempotent), keeping the registry uniform across "other agents".
156+
// Skills-only for now — no settings.json / hooks file shipped yet;
157+
// that's a follow-up once the manual eval workflow tells us which
158+
// Copilot CLI lifecycle hooks make sense to register.
159+
{"copilot", "GitHub Copilot CLI", ".agents/skills", "", "", ""},
153160
}
154161

155162
// skillsSubdir is the directory inside ~/.x-x/agents/ that holds the

‎docs/public/getting-started.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ iex (irm https://stackific.com/x-x/INSTALL.ps1)
1919

2020
```bash
2121
# Run this inside of a project folder
22-
$ x-x init # installs bundled skills into ~/.claude/skills, ~/.agents/skills, ~/.copilot/skills (or project-local)
22+
$ x-x init # installs bundled skills into ~/.claude/skills, ~/.agents/skills (or project-local)
2323
```
2424

2525
See [Reference](reference.md) for the full command reference.

‎docs/public/reference.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ Installs every bundled skill into the locations each agent looks for, then seeds
2727
1. **Which agents?** Multi-select over every registered agent (Claude Code, Codex CLI, GitHub Copilot CLI today). Blank line / no toggle accepts the default (all agents).
2828
2. **Which scope?**
2929
- **This project only** — writes under the current working directory (`.claude/skills/`, `.agents/skills/` shared by Codex and Copilot, and seeds `.x-plans/`).
30-
- **All my projects (user scope)** — writes under `$HOME` (`~/.claude/skills/`, `~/.agents/skills/` for Codex, `~/.copilot/skills/` for Copilot CLI).
30+
- **All my projects (user scope)** — writes under `$HOME` (`~/.claude/skills/`, `~/.agents/skills/` for Codex and Copilot CLI).
3131
3. **Prefix width for plan files** — zero-padded width for plan filenames (e.g. width `4` → `0001-foo.md`). Default: `4`.
3232
4. **Maximum lines per plan** — cap enforced by `x-x plans lint`. Keeps AI agents on a short leash: forces them to split sprawling work into smaller, reviewable plans. Default: `30`.
3333
5. **Pause for review after every…** — `task` reviews each EARS criterion as the planner finishes it (tight loop, more interruptions); `plan` reviews only at plan boundaries (looser loop, larger diffs). Default: `task`.
@@ -42,15 +42,15 @@ Every prompt has a non-interactive flag twin — pass any subset to skip the mat
4242

4343
Values 3–5 land in `.x-plans/_config.lock` and become the lock-file pins for the project — re-running `x-x init` later does NOT refresh them (Cargo.lock / package-lock.json semantics). Never manually edit `.x-plans/_config.lock`.
4444

45-
Codex CLI reads from `.agents/skills` at every level (cwd, repo root, and `$HOME`), per the cross-agent SKILL.md open standard. GitHub Copilot CLI also reads `.agents/skills` at project scope (so the project-scope install populates one directory that both Codex and Copilot CLI pick up), but its user-scope path is `~/.copilot/skills/` — the Copilot-native location documented at [docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills). On Windows, `~` resolves to `%USERPROFILE%`, so `~/.claude/skills/` is `%USERPROFILE%\.claude\skills\`, `~/.agents/skills/` is `%USERPROFILE%\.agents\skills\`, `~/.copilot/skills/` is `%USERPROFILE%\.copilot\skills\`, and so on. Inside WSL2, paths resolve against the WSL home (`/home/<user>/...`) — install x-x with `INSTALL.sh` from inside WSL to land in the WSL filesystem.
45+
Codex CLI reads from `.agents/skills` at every level (cwd, repo root, and `$HOME`), per the cross-agent SKILL.md open standard. GitHub Copilot CLI also reads `.agents/skills` at both project and user scope — `~/.agents/skills/` is on Copilot CLI's [official user-scope list](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills) alongside `~/.copilot/skills/`, and we land in the cross-agent path so the bundled `SKILL.md` content (which documents only `.claude/skills` and `.agents/skills`) discovers shared docs correctly. On Windows, `~` resolves to `%USERPROFILE%`, so `~/.claude/skills/` is `%USERPROFILE%\.claude\skills\`, `~/.agents/skills/` is `%USERPROFILE%\.agents\skills\`, and so on. Inside WSL2, paths resolve against the WSL home (`/home/<user>/...`) — install x-x with `INSTALL.sh` from inside WSL to land in the WSL filesystem.
4646

4747
On macOS and Linux at user scope, skill directories are installed as symlinks into `~/.x-x/agents/skills/`, so refreshes to the bundled tree propagate to every project at once. On Windows (and at project scope everywhere), skills are copied. Re-running `x-x init` always overwrites the bundled skill directories with the current release — they are repo-shipped content, not user state.
4848

4949
Agent-specific config files (e.g. `~/.claude/settings.json`) are seeded only when absent — existing files are left alone.
5050

5151
### `x-x skills remove --user`
5252

53-
Walks `~/.claude/skills/`, `~/.agents/skills/`, `~/.copilot/skills/`, etc., and removes every entry whose name matches the bundled-skill allowlist (`_x-x_shared`, `x-plan`, `x-x` today). The name is the only criterion — symlink targets are not consulted, which means an entry named the same as a bundled skill *will* be removed even if you authored it yourself. Rename any local skill that collides with a bundled one before running this command.
53+
Walks `~/.claude/skills/`, `~/.agents/skills/`, etc., and removes every entry whose name matches the bundled-skill allowlist (`_x-x_shared`, `x-plan`, `x-x` today). The name is the only criterion — symlink targets are not consulted, which means an entry named the same as a bundled skill *will* be removed even if you authored it yourself. Rename any local skill that collides with a bundled one before running this command.
5454

5555
In addition to deleting bundled skill directories, `skill remove` un-merges the hook records `x-x init` previously deep-merged into each agent's JSON config (`~/.claude/settings.json`, `~/.codex/hooks.json`). Subtraction is per-record and uses deep-equality against the currently bundled file under `~/.x-x/agents/<agent>/`: a record that byte-equals one of ours is dropped; a user-tweaked variant (different command, different matcher) is preserved. The file, its top-level non-hook keys, user-added event keys, and any user-authored sibling entries under the same event key all stay.
5656

@@ -59,7 +59,7 @@ The following are never touched:
5959
- Folders whose name is not on the bundled-skill allowlist (your own skills sitting alongside ours).
6060
- Anything in the agent config files outside of their `"hooks"` subtree — top-level keys like `"fastMode"` and any user-authored content. Empty arrays or event-key maps left behind by the un-merge are kept as-is; we subtract records, not containers.
6161
- The `.x-plans/` scaffold at project scope. Once `init` writes it, it's yours.
62-
- Parent directories (`.claude/`, `.codex/`, `.copilot/`). Only the `skills/` subdirectory under each may be removed, and only when it is empty after cleanup.
62+
- Parent directories (`.claude/`, `.codex/`). Only the `skills/` subdirectory under each may be removed, and only when it is empty after cleanup.
6363

6464
### `x-x skills remove --project`
6565

‎scripts/e2e_test.ps1‎

Lines changed: 18 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -70,15 +70,17 @@ Set-Variable -Option Constant -Name SHARED_DOC_EARS -Value '_ears.md'
7070
Set-Variable -Option Constant -Name OWNED_SKILLS -Value @($SKILL_SHARED_DIR, $SKILL_X_PLAN_DIR, $SKILL_X_X_DIR)
7171

7272
# agentTargets in constants.go — index 0 = Claude Code, 1 = Codex CLI,
73-
# 2 = GitHub Copilot CLI. Copilot is the first agent with a per-scope
74-
# skill path: project reuses Codex's `.agents/skills` (cross-agent open
75-
# spec, idempotent install), user scope uses Copilot-native `.copilot/skills`.
76-
Set-Variable -Option Constant -Name CLAUDE_SKILLS_REL -Value '.claude\skills'
77-
Set-Variable -Option Constant -Name CLAUDE_CONFIG_REL -Value '.claude'
78-
Set-Variable -Option Constant -Name CODEX_SKILLS_REL -Value '.agents\skills'
79-
Set-Variable -Option Constant -Name CODEX_CONFIG_REL -Value '.codex'
80-
Set-Variable -Option Constant -Name COPILOT_SKILLS_REL -Value '.agents\skills'
81-
Set-Variable -Option Constant -Name COPILOT_USER_SKILLS_REL -Value '.copilot\skills'
73+
# 2 = GitHub Copilot CLI. Copilot reuses Codex's `.agents/skills` at both
74+
# scopes (cross-agent open spec, install is idempotent so the two rows
75+
# co-exist on disk without conflict). The agentTarget.userSkillsRel field
76+
# exists for future agents whose project- vs user-scope paths diverge;
77+
# Copilot doesn't need it because the bundled x-x skill content already
78+
# documents `.agents/skills` as the canonical "other agents" path.
79+
Set-Variable -Option Constant -Name CLAUDE_SKILLS_REL -Value '.claude\skills'
80+
Set-Variable -Option Constant -Name CLAUDE_CONFIG_REL -Value '.claude'
81+
Set-Variable -Option Constant -Name CODEX_SKILLS_REL -Value '.agents\skills'
82+
Set-Variable -Option Constant -Name CODEX_CONFIG_REL -Value '.codex'
83+
Set-Variable -Option Constant -Name COPILOT_SKILLS_REL -Value '.agents\skills'
8284

8385
# Bundled config filenames (not constants in Go; pinned here for assertions).
8486
Set-Variable -Option Constant -Name CLAUDE_SETTINGS_FILE -Value 'settings.json'
@@ -2365,21 +2367,21 @@ try {
23652367
(Join-Path $projCP1 (Join-Path $CLAUDE_SKILLS_REL $SKILL_X_X_DIR))
23662368
} finally { Pop-Location }
23672369

2368-
Start-Case 'init --agents=copilot --scope=user lands at ~/.copilot/skills'
2370+
Start-Case 'init --agents=copilot --scope=user lands at ~/.agents/skills'
23692371
Reset-UserHome
23702372
$projCP2 = New-FreshProject
23712373
Push-Location $projCP2
23722374
try {
23732375
Invoke-XX init --scope user --agents=copilot `
23742376
--prefix-width 4 --max-plan-lines 30 --review-per task
23752377
Assert-Eq 'exit 0' $RunRC 0
2376-
# User scope: copilot diverges from `.agents/skills` and lands at
2377-
# `.copilot/skills` under USERPROFILE. Codex's user dir must NOT be
2378-
# created when only copilot is selected.
2378+
# User scope: copilot reuses Codex's `.agents/skills` (cross-agent open
2379+
# spec, one of two official Copilot CLI user-scope paths). Skills land
2380+
# under USERPROFILE, project cwd untouched.
23792381
Assert-IsDir 'copilot user-scope skills landed' `
2380-
(Join-Path $env:USERPROFILE (Join-Path $COPILOT_USER_SKILLS_REL $SKILL_X_X_DIR))
2381-
Assert-NotExists 'codex user-scope dir NOT created' `
2382-
(Join-Path $env:USERPROFILE $CODEX_SKILLS_REL)
2382+
(Join-Path $env:USERPROFILE (Join-Path $COPILOT_SKILLS_REL $SKILL_X_X_DIR))
2383+
Assert-NotExists 'no install under project cwd' `
2384+
(Join-Path $projCP2 (Join-Path $COPILOT_SKILLS_REL $SKILL_X_X_DIR))
23832385
} finally { Pop-Location }
23842386

23852387
Start-Case 'init --prefix-width=6 seeds the lock with 6'

‎scripts/e2e_test.sh‎

Lines changed: 16 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -49,24 +49,21 @@ readonly SHARED_DOC_EARS="_ears.md" # sharedDocEars
4949
readonly OWNED_SKILLS="${SKILL_SHARED_DIR} ${SKILL_X_PLAN_DIR} ${SKILL_X_X_DIR}"
5050

5151
# agentTargets in constants.go — index 0 = Claude Code, 1 = Codex CLI,
52-
# 2 = GitHub Copilot CLI. Copilot is the first agent with a per-scope
53-
# skill path: project scope reuses Codex's `.agents/skills` (cross-agent
54-
# open spec, install is idempotent so both rows can co-exist), user scope
55-
# uses the Copilot-native `~/.copilot/skills`.
52+
# 2 = GitHub Copilot CLI. Copilot reuses Codex's `.agents/skills` for
53+
# both scopes (cross-agent open spec, install is idempotent so the two
54+
# rows co-exist on disk without conflict). The agentTarget.userSkillsRel
55+
# field exists for future agents whose project- vs user-scope paths
56+
# diverge; Copilot doesn't need it because the bundled x-x skill content
57+
# already documents `.agents/skills` as the canonical "other agents" path.
5658
readonly CLAUDE_SKILLS_REL=".claude/skills" # agentTargets[0].skillsRel
5759
readonly CLAUDE_CONFIG_REL=".claude" # agentTargets[0].configRel
5860
readonly CODEX_SKILLS_REL=".agents/skills" # agentTargets[1].skillsRel
5961
readonly CODEX_CONFIG_REL=".codex" # agentTargets[1].configRel
6062
readonly COPILOT_SKILLS_REL=".agents/skills" # agentTargets[2].skillsRel
61-
readonly COPILOT_USER_SKILLS_REL=".copilot/skills" # agentTargets[2].userSkillsRel
6263
# Parent of CODEX_SKILLS_REL — used by isolation cases that seed sibling
6364
# files alongside the Codex skills dir. Derived (not a Go constant) to
6465
# avoid drift if agentTargets[1].skillsRel ever moves.
6566
readonly CODEX_SKILLS_PARENT="${CODEX_SKILLS_REL%/*}"
66-
# Parent of COPILOT_USER_SKILLS_REL — used by reset_user_home so the next
67-
# case starts with `~/.copilot/` wiped. Derived the same way as the codex
68-
# parent constant above.
69-
readonly COPILOT_USER_SKILLS_PARENT="${COPILOT_USER_SKILLS_REL%/*}"
7067

7168
# Bundle-provided config filenames (agents/<configSrc>/* in the embed). Not
7269
# named in constants.go (the embed tree is the source) but pinned here
@@ -180,7 +177,6 @@ reset_user_home() {
180177
rm -rf "$HOME/${CLAUDE_CONFIG_REL}" \
181178
"$HOME/${CODEX_CONFIG_REL}" \
182179
"$HOME/${CODEX_SKILLS_PARENT}" \
183-
"$HOME/${COPILOT_USER_SKILLS_PARENT}" \
184180
"$HOME/${XX_HOME_DIR}"
185181
}
186182

@@ -609,18 +605,19 @@ assert_eq "exit 0" "$RUN_RC" "0"
609605
assert_is_dir "copilot project skills installed" "$PROJ_CP/${COPILOT_SKILLS_REL}/${SKILL_X_X_DIR}"
610606
assert_absent "claude NOT installed" "$PROJ_CP/${CLAUDE_SKILLS_REL}"
611607

612-
case_start "x-x init --agents=copilot --scope=user lands at ~/.copilot/skills"
608+
case_start "x-x init --agents=copilot --scope=user lands at ~/.agents/skills"
609+
PROJ_CP_USER="$(fresh_project)"
610+
cd "$PROJ_CP_USER"
613611
reset_user_home
614-
cd "$(fresh_project)"
615612
run_capture "" init --agents=copilot --scope=user
616613
assert_eq "exit 0" "$RUN_RC" "0"
617-
# User-scope copilot has its own path (.copilot/skills), distinct from
618-
# the project-scope `.agents/skills`. Codex's user dir (~/.agents/skills)
619-
# MUST NOT be created when only copilot is selected.
614+
# Copilot reuses the Codex `.agents/skills` path at both scopes (cross-
615+
# agent open spec). Skills land under SANDBOX_HOME, project cwd is left
616+
# alone (user scope must not pollute the user's terminal pwd).
620617
assert_is_dir "copilot user-scope skills landed" \
621-
"${SANDBOX_HOME}/${COPILOT_USER_SKILLS_REL}/${SKILL_X_X_DIR}"
622-
assert_absent "codex user-scope dir NOT created" \
623-
"${SANDBOX_HOME}/${CODEX_SKILLS_REL}"
618+
"${SANDBOX_HOME}/${COPILOT_SKILLS_REL}/${SKILL_X_X_DIR}"
619+
assert_absent "no install under project cwd" \
620+
"$PROJ_CP_USER/${COPILOT_SKILLS_REL}"
624621

625622
case_start "x-x init --agents=invalid rejects unknown agent"
626623
reset_user_home
@@ -1244,7 +1241,7 @@ reset_user_home
12441241
# Trigger the lazy first-run write of ~/${XX_HOME_DIR}/agents/ via bare
12451242
# x-x, then wipe the install dirs so skill remove has nothing to do.
12461243
run_capture "" >/dev/null
1247-
rm -rf "$HOME/${CLAUDE_CONFIG_REL}" "$HOME/${CODEX_SKILLS_PARENT}" "$HOME/${CODEX_CONFIG_REL}" "$HOME/${COPILOT_USER_SKILLS_PARENT}"
1244+
rm -rf "$HOME/${CLAUDE_CONFIG_REL}" "$HOME/${CODEX_SKILLS_PARENT}" "$HOME/${CODEX_CONFIG_REL}"
12481245
run_capture "" skills remove --user
12491246
assert_eq "exit 0 on empty state" "$RUN_RC" "0"
12501247
assert_contains "summary line" "$RUN_OUT" "Removed 0"

0 commit comments

Comments
 (0)