Azure / Azure/documentdb-agent-kit
Replace in-repo .md cross-references in skill content with Microsoft Learn URLs
- Dominant language
- Shell
- Stars
- 5
- Forks
- 10
- Avg merge
- 2d 15h
- Merged PRs (30d)
- 1
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/`
| `.md` reference | Replace with |
|---|---|
| `security-private-endpoint.md` | https://learn.microsoft.com/azure/documentdb/how-to-private-link |
| `security-firewall-rules.md` | https://learn.microsoft.com/azure/documentdb/how-to-configure-firewall |
| `security-entra-rbac.md` | https://learn.microsoft.com/azure/documentdb/how-to-connect-role-based-access-control |
| `security-database-roles.md` | https://learn.microsoft.com/azure/documentdb/how-to-connect-role-based-access-control |
| `security-azure-rbac-actions.md` | https://learn.microsoft.com/azure/documentdb/how-to-connect-role-based-access-control |
| `security-token-lifetime-revocation.md` | https://learn.microsoft.com/azure/documentdb/how-to-connect-role-based-access-control |
| `security-cmk-encryption.md` | https://learn.microsoft.com/azure/documentdb/database-encryption-at-rest |
| `security-cmk-troubleshooting.md` | https://learn.microsoft.com/azure/documentdb/how-to-database-encryption-troubleshoot |
| `security-tls-required.md` | https://learn.microsoft.com/azure/documentdb/security |
| `security-admin-password-and-identity-separation.md` | https://learn.microsoft.com/azure/documentdb/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
1. **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?
2. **Two rules collapse to** `azure/documentdb/security` — `security-tls-required` and `security-admin-password-and-identity-separation`. Both pulled from the "Secure your cluster" overview.
3. **Monitoring landing page** — confirm the right canonical URL for the `../monitoring/` directory reference.
4. **Inline non-link text** like `` `storage/` `` in `SKILL.md` (parenthetical "Premium SSD v1 only — see `storage/`") — 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.
Contributor guide
Assessment
This issue has not been assessed yet.