docs(skill): use absolute URLs for the three inline doc references - #124
Merged
Conversation
The amplifier-agent skill is being prepared for public distribution. When
installed independently from a repository checkout, relative paths in the
skill body become unresolvable.
Three inline prose references used bare repo-relative paths:
- line 97: wrappers/typescript/README.md
- line 129: docs/spec/engine-api.md (critical — the skill instructs agents
to READ this file before using the in-process library)
- line 183: docs/spec/envelope-and-errors.md
Line 129 is the serious case: an agent told to read a file it cannot open
will either stall or guess. This skill was written explicitly to prevent
guessing.
Convert all three from bare backtick paths to markdown links pointing at
https://github.com/microsoft/amplifier-agent/blob/main/<path>, keeping the
filename visible in link text for readability.
Validated against official Agent Skills spec:
- npx skills-ref validate ./skills/amplifier-agent → 'Valid skill' (exit 0)
- All 9 GitHub URLs resolve on main
- No bare repo-relative paths remain in prose
- Still within spec limits: 208 lines (<500), ~3,398 tokens (<5,000)
🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)
Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The amplifier-agent skill is being prepared for public distribution. When installed independently from a repository checkout, relative paths in the skill body become unresolvable.
This fixes three inline prose references that used bare repo-relative paths:
wrappers/typescript/README.mddocs/spec/engine-api.md(critical — the skill instructs agents to READ this file before using the in-process library)docs/spec/envelope-and-errors.mdWhy it matters
Line 129 is the serious case. The skill's opening instruction explicitly warns: "do not fill gaps from memory." Then it tells agents to read the engine API spec before using the in-process library. When that file cannot be found, an agent faces a choice between stalling or guessing — and guessing is precisely what this skill was designed to prevent.
The fix
Converted all three from bare backtick paths to markdown links pointing at https://github.com/microsoft/amplifier-agent/blob/main/, keeping the filename visible in link text for readability. This matches the URL convention already used by the documentation table at lines 33-40.
Verification
npx skills-ref@latest validate ./skills/amplifier-agent→ Valid skill (exit 0)main