microsoft / microsoft/amplifier

skills discovery: `~/.agents/skills` is appended with no opt-out, and every skipped directory logs a warning

Open
#402 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
3.1k
Forks
261
Avg merge
3h 28m
Merged PRs (30d)
13

Description

On a machine where ~/.agents/skills is a directory of symlinks into other repos — the layout
other agent CLIs install into, and the one the "cross-tool location" comment in
_ensure_default_skills_dirs is describing — Amplifier logs 490 warning lines per session and
loads zero skills from that root. Two separate causes, either of which would be enough on its own.

1. The root is appended unconditionally.

amplifier_app_cli/runtime/config.py (_ensure_default_skills_dirs) appends
.amplifier/skills, .agents/skills, ~/.amplifier/skills, ~/.agents/skills and the packaged
directory to whatever config.skills the bundle set. There is no way for a bundle or for
settings.yaml to decline one of them — the only control is AMPLIFIER_SKILLS_DIR, which
prepends. The docstring is explicit that this is app-layer policy, which is fine; what is missing
is a way to say "not that one".

2. The boundary warning is per directory walked, not per root.

tool-skills discovery.py computes boundary = _find_repo_root(skills_dir) or skills_dir.resolve() and logs

Skipping symlink that escapes skill directory boundary: <dir> (resolves to <target>, outside <boundary>)

for every walked directory that resolves outside it. A single linked skill with a normal internal
structure produces one line per subdirectory — one of mine contributes 15 on its own — so 81 links
produce ~490 lines. The decision is per root; the logging is per directory.

_find_repo_root also walks up from the skills directory, so the documented escape hatch
("when a git repo is detected, symlinks may resolve anywhere within the repo root") cannot be used
here: the link targets live in a different repo, and the only repo root that would contain them is
$HOME itself.

What I'd suggest

Either would fix it; the first is the one I'd want.

  • Let a session decline a default root — an explicit skills_dirs_exclude, or honouring a
    sentinel in config.skills, so a machine that uses ~/.agents/skills for another tool can keep
    it out of Amplifier's list.
  • Log the boundary skip once per root with a count, at debug level, rather than once per
    directory. The information is useful; 490 lines of it is not.

Environment

  • amplifier CLI 2026.09.12, amplifier-app-cli 1.6.1
  • tool-skills from amplifier-bundle-skills@main (editable install)
  • macOS 15.6, 81 symlinked entries under ~/.agents/skills

Happy to send a PR for either if you tell me which shape you'd take.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in amplifier_app_cli/runtime/config.py at _ensure_default_skills_dirs, then inspect tool-skills discovery.py around _find_repo_root and the boundary warning. Reproduce the symlinked ~/.agents/skills layout and trace both default-root selection and directory walking. Done means the chosen behavior provides an opt-out or reduces repeated warnings without breaking valid skill discovery.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
cli, tooling
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.