fix(skills): resolve bundled resources from skill roots

[MAX-IT-Tech]

Summary

Clarifies how skill-local bundled resource paths are resolved across Compound Engineering skills.

Skills that reference assets/, references/, or scripts/ now explicitly state that those paths must be resolved relative to the current SKILL.md directory, not the user's project cwd.

This matters for portability across agent runtimes. Claude Code, Codex, Cursor, and other environments can differ in their working directory and skill loading behavior, so relying on implicit cwd resolution can make bundled references fail outside one specific harness.

Changes

• Added a consistent bundled resource path rule to skills that reference assets/, references/, or scripts/.
• Normalized ad-hoc helper/script wording to point back to the shared rule.
• Kept skill references self-contained and independent of the user's project cwd.

Validation

• git diff --check
• bun run release:validate

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8d50b66181

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Restore a concrete worktree-manager path

When ce-worktree runs under Claude Code, the runtime Bash tool starts in the user's project cwd and the model is not given an actual filesystem value for <skill-dir>, so this placeholder no longer tells it how to locate the bundled script in marketplace/local plugin installs. This regresses the behavior codified in plugins/compound-engineering/AGENTS.md and the existing tests/skills/ce-worktree.test.ts, which require invoking the script via ${CLAUDE_SKILL_DIR:-.}/scripts/worktree-manager.sh so Claude resolves the skill directory while other targets can fall back to a relative path.

Useful? React with 👍 / 👎.

[MAX-IT-Tech]

Fixed in e1d2c346.

Restored the concrete ${CLAUDE_SKILL_DIR:-.}/scripts/worktree-manager.sh invocation for ce-worktree so Claude Code keeps resolving the marketplace/local skill directory correctly, while non-Claude targets retain the existing :-. fallback behavior. The bundled resource path clarification remains in place for the broader skill-resource references.

Validation:

• bun test tests/skills/ce-worktree.test.ts
• bun run release:validate
• git diff --check

[tmchow]

@MAX-IT-Tech is a more efficient way here and more effective to just add a ./ with every file path?

[MAX-IT-Tech]

@MAX-IT-Tech is a more efficient way here and more effective to just add a ./ with every file path?

./ helps visually, but I don't think it defines the right contract here.

The issue is not only path syntax, but the resolution root. A skill can be installed in several places: a Claude marketplace cache, a local plugin directory, a user-level Codex/Cursor install, a project-local install, or another hosted/runtime-specific location. For files bundled with a skill, the only stable root is the current skill directory, i.e. the directory containing that SKILL.md.

./scripts/foo.sh can still resolve from the user's project cwd in runtime shell contexts, which is the class of bug guarded by ce-worktree.test.ts. Conversely, skills may also talk about project-local directories or output paths, and those should remain project-relative or repo-root-relative rather than being confused with bundled resources.

I can tighten the wording to make that distinction explicit: bundled assets/, references/, and scripts/ paths resolve relative to the current SKILL.md; project files and output paths must be described explicitly as project/repo-relative.

[tmchow]

The issue is not only path syntax, but the resolution root. A skill can be installed in several places: a Claude marketplace cache, a local plugin directory, a user-level Codex/Cursor install, a project-local install, or another hosted/runtime-specific location. For files bundled with a skill, the only stable root is the current skill directory, i.e. the directory containing that SKILL.md.

How sure are you of this? I haven't had this experience yet in the harnesses I use. Where have you seen a failure more where the SKILL's context isn't it's own folder and using say the repo root?

[MAX-IT-Tech]

How sure are you of this? I haven't had this experience yet in the harnesses I use. Where have you seen a failure more where the SKILL's context isn't it's own folder and using say the repo root?

I installed and used your plugin in the Codex Desktop App on MacOS. I noticed that when using the ce-compound and ce-compound-refresh skills, Codex kept saying it couldn't find validate-frontmatter.py and was using alternatives. I then asked it to check the issue, and it turned out it was looking for this script in the project folder, not the skill folder. After I asked it to remember where it was located and where to look, everything worked fine. So I decided to try fixing this problem globally directly in the plugin itself, as I noticed it purely by accident while running the agent...