Replace in-repo .md cross-references in skill content with Microsoft Learn URLs
Nobody has claimed this yet.
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 52/100
- Issue type
- Documentation
- Clarity
- Mostly clear
- Activity status
- Quiet
- Tech stack
- markdown, powershell, python
- Domain
- documentation, tooling
Research direction
Start by auditing skills/**/*.md and the mapping from PR #14, including the unresolved monitoring and inline-text questions. Use the listed Learn references to identify every in-repo .md link, then run scripts/validate-skills.ps1. Done means all applicable skill links resolve to canonical Learn URLs and the validator passes.
Written by the indexing model from the issue text.
Description
Problem
Skill rule files cross-reference each other and adjacent skills using relative .md paths (e.g. [security-private-endpoint](security-private-endpoint.md), [ha-cross-region-replica](../high-availability/ha-cross-region-replica.md)). When the skill content is consumed by an agent or rendered outside the repo, these in-repo links don't resolve — the consumer needs links to the official Microsoft Learn articles instead.
Proposed fix
Replace every *.md link inside skill content (rule files and SKILL.md) with the canonical Learn URL. Each rule already lists its primary Learn source in its ## References section, so the mapping is straightforward.
Mapping (from PR #14 audit)
Sibling rules — skills/security/
Cross-skill references
.md reference |
Replace with |
|---|---|
../high-availability/ha-cross-region-replica.md |
https://learn.microsoft.com/azure/documentdb/cross-region-replication |
../high-availability/ha-backup-retention.md |
https://learn.microsoft.com/azure/reliability/reliability-documentdb |
../monitoring/ (directory ref) |
https://learn.microsoft.com/azure/documentdb/monitor-resource-logs (needs confirmation) |
Open questions
- Four security rules collapse to the same RBAC Learn article (
how-to-connect-role-based-access-control) —security-entra-rbac,security-database-roles,security-azure-rbac-actions,security-token-lifetime-revocation. That single Learn article is the source for all four. Acceptable, or do we want sub-section anchors? - Two rules collapse to
azure/documentdb/security—security-tls-requiredandsecurity-admin-password-and-identity-separation. Both pulled from the "Secure your cluster" overview. - Monitoring landing page — confirm the right canonical URL for the
../monitoring/directory reference. - Inline non-link text like
`storage/`inSKILL.md(parenthetical "Premium SSD v1 only — seestorage/") — convert to Learn link too, or leave as in-repo navigation hint?
Scope
This issue is about all skill folders, not just security/. PR #14 surfaced the issue but the same pattern almost certainly exists in high-availability/, storage/, and any future skill. Recommend a one-pass sweep across skills/**/*.md once the open questions are resolved.
Suggested implementation
A small PowerShell or Python script that walks skills/**/*.md, applies the mapping table above, and reports any unmapped .md) link for manual review. Validator (scripts/validate-skills.ps1) should pass after the sweep.
Originating context
Surfaced during review of PR #14 (docs/security-rbac). Mapping table was generated by auditing the ## References section of each affected rule file.
- Dominant language
- Shell
- Stars
- 6
- Forks
- 10
- Avg merge
- 11d 20h
- Merged PRs (30d)
- 2
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from Azure/documentdb-agent-kit
-
Difficulty 4/5 3-5 days Newbie friendliness 45/100
Azure/documentdb-agent-kit#20 · 1 comment ·
-
Add a sample-app-generator skill: scaffold runnable starter apps against an Azure DocumentDB cluster Open
Difficulty 5/5 Over a week Newbie friendliness 35/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 58/100
-
Add a skill for RBAC Open
Difficulty 4/5 3-5 days Newbie friendliness 20/100
All issues in Azure/documentdb-agent-kit
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
-
Difficulty 1/5 Under an hour Newbie friendliness 85/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
-
bug easy help wanted
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
lacs-project/sysknife#503 ·
-
help wanted kind/documentation
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
liquidmetal-dev/flintlock#1239 ·