#9221: fix(skills): use skillKey for env config lookup in snapshots
agents
stale
Cluster:
Skill and Session Management Fixes
## Summary
When skills have a custom `skillKey` in their metadata (e.g., `skillKey: 'trello'` for a skill named `trello-skill`), the env var config lookup in `applySkillEnvOverridesFromSnapshot` was failing because it used `skill.name` instead of the skillKey.
This caused skill env vars defined in `skills.entries.<skill>.env` to not be injected into subagent exec commands when the skill uses a custom skillKey for the config.
## Changes
- Add `skillKey` to `SkillSnapshot.skills` type (stored only when it differs from name)
- Update `buildWorkspaceSkillSnapshot` to include skillKey in the snapshot
- Update `applySkillEnvOverridesFromSnapshot` to use skillKey (with fallback to name) for config lookup
- Add test case for skillKey-based env lookup
## Testing
- All existing tests pass
- New test case verifies skillKey-based env lookup works
Fixes #9207
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This PR fixes a config lookup bug for skill environment overrides when a skill uses a custom `skillKey` in its frontmatter metadata. It updates the serialized `SkillSnapshot` shape to optionally include `skillKey` (only when it differs from `name`), updates snapshot building to store it, and updates `applySkillEnvOverridesFromSnapshot` to resolve config entries by `skillKey ?? name`. A new unit test covers the `skillKey`-based lookup path.
This change integrates with the existing skills pipeline by affecting the snapshot used to avoid reloading skills during embedded runs (`src/agents/pi-embedded-runner/*`), ensuring env injection uses the same config keying as the non-snapshot path (`applySkillEnvOverrides`, which already resolves the skill key from frontmatter).
<h3>Confidence Score: 4/5</h3>
- This PR is close to safe to merge, but there is a concrete snapshot type mismatch that can break session snapshot persistence/compatibility and may drop the new `skillKey` field.
- Core logic change is small and aligns snapshot env lookup with the existing non-snapshot codepath, and the new unit test covers the intended behavior. However, `SessionSkillSnapshot` in `src/config/sessions/types.ts` was not updated to include `skillKey`, which can cause type incompatibilities and prevent `skillKey` from being retained when snapshots are stored/loaded via session types.
- src/config/sessions/types.ts
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#21883: fix: guard against undefined snapshot.skills in applySkillEnvOverride…
by felipedamacenoteodoro · 2026-02-20
81.9%
#22525: [Bug]: Session snapshot not reloading skills after gateway restart ...
by zwffff · 2026-02-21
80.3%
#12076: fix(skills): recursive directory filtering to actually exclude venv...
by xiaoyaner0201 · 2026-02-08
80.1%
#9215: Fix: Inject skill env vars into subagent exec commands
by vishaltandale00 · 2026-02-05
80.1%
#12209: fix(skills): refresh stale skill snapshot after gateway restart
by mcaxtr · 2026-02-09
79.9%
#19664: fix(skills): log skill YAML parsing diagnostics with skill name
by orchidsun · 2026-02-18
79.8%
#16654: fix: refresh skills snapshot when managed skills change
by PhineasFleabottom · 2026-02-15
79.7%
#11250: fix: expand skills watcher ignore list and improve session repair l...
by zhangzhefang-github · 2026-02-07
79.3%
#20533: fix: strip resolvedSkills from session store to prevent snapshot bloat
by echoVic · 2026-02-19
78.9%
#12956: fix: guard .trim() calls on potentially undefined workspaceDir
by omair445 · 2026-02-10
78.5%