Would you be open to giving a valid project-local Agent Skill precedence over a same-name global Agent Skill?
Currently, effectiveSkillPaths in src/skills.ts lists ~/.agents/skills before the workspace's .agents/skills. With first-wins name deduplication, the global copy wins. To reproduce, place two valid SKILL.md files with the same frontmatter name (for example, project-checks) in those directories, with distinct descriptions and instructions, then load the workspace skills. The selected path is the global copy, not the repository-specific one.
The use case is a general global skill with a repository-specific specialization, such as a project's actual test commands or contribution workflow. I would propose checking project .agents/skills before ~/.agents/skills, keeping the global copy as fallback when the project skill is absent or rejected by the loader. A valid project skill with disable-model-invocation: true should still win and remain available for explicit invocation; that flag should not silently reactivate the global fallback. Existing collision diagnostics should identify the selected and shadowed paths.
This is a precedence-policy proposal, not a claim that the current order is necessarily a bug. It would change behavior for users who rely on global skills winning name collisions, so I wanted to confirm the intended policy before opening a PR. The scope would be only the relative order of these two Agent Skills directories, without changing custom-path ordering, managed subagent skills, or adding configuration options.
I have a small local patch, documentation, and regression tests prepared for project override, global fallback, invalid project metadata, and invocation-disabled project skills. If this direction is welcome, I can submit it as a separate PR. This is distinct from #208 (opting out of automatic discovery) and #127 (deduplicating bootstrap delivery across projects).
Would you be open to giving a valid project-local Agent Skill precedence over a same-name global Agent Skill?
Currently,
effectiveSkillPathsinsrc/skills.tslists~/.agents/skillsbefore the workspace's.agents/skills. With first-wins name deduplication, the global copy wins. To reproduce, place two validSKILL.mdfiles with the same frontmattername(for example,project-checks) in those directories, with distinct descriptions and instructions, then load the workspace skills. The selected path is the global copy, not the repository-specific one.The use case is a general global skill with a repository-specific specialization, such as a project's actual test commands or contribution workflow. I would propose checking project
.agents/skillsbefore~/.agents/skills, keeping the global copy as fallback when the project skill is absent or rejected by the loader. A valid project skill withdisable-model-invocation: trueshould still win and remain available for explicit invocation; that flag should not silently reactivate the global fallback. Existing collision diagnostics should identify the selected and shadowed paths.This is a precedence-policy proposal, not a claim that the current order is necessarily a bug. It would change behavior for users who rely on global skills winning name collisions, so I wanted to confirm the intended policy before opening a PR. The scope would be only the relative order of these two Agent Skills directories, without changing custom-path ordering, managed subagent skills, or adding configuration options.
I have a small local patch, documentation, and regression tests prepared for project override, global fallback, invalid project metadata, and invocation-disabled project skills. If this direction is welcome, I can submit it as a separate PR. This is distinct from #208 (opting out of automatic discovery) and #127 (deduplicating bootstrap delivery across projects).