Merge branch 'main' into copilot/update-functions-recipe-reference

Author: saikoumudi

.github/skills/file-test-bug/SKILL.md

@@ -9,7 +9,7 @@ Creates a GitHub issue in `microsoft/github-copilot-for-azure` for integration t
 
 ## Input
 
-- **Skill name** (required): e.g., `azure-role-selector`, `appinsights-instrumentation`
+- **Skill name** (required): e.g., `azure-rbac`, `appinsights-instrumentation`
 - **Test run** (optional): Timestamp of test run. Defaults to most recent with logs for the skill.
 
 ## Steps

.github/skills/sensei/README.md

@@ -36,10 +36,11 @@ Sensei implements the "Ralph Wiggum" technique:
 2. **Score** - Evaluate frontmatter compliance
 3. **Improve** - Add triggers, anti-triggers, compatibility
 4. **Verify** - Run tests to ensure changes work
-5. **Check Tokens** - Analyze token usage, gather suggestions
-6. **Summary** - Display before/after with suggestions
-7. **Prompt** - Ask user: Commit, Create Issue, or Skip?
-8. **Repeat** - Until target score reached
+5. **Validate References** - Check markdown links are valid
+6. **Check Tokens** - Analyze token usage, gather suggestions
+7. **Summary** - Display before/after with suggestions
+8. **Prompt** - Ask user: Commit, Create Issue, or Skip?
+9. **Repeat** - Until target score reached
 
 ---
 
@@ -57,7 +58,7 @@ Run sensei on appinsights-instrumentation --skip-integration
 
 ### Multiple Skills
 ```
-Run sensei on azure-security, azure-networking, azure-observability
+Run sensei on azure-security, azure-observability
 ```
 
 ### All Low-Adherence Skills
@@ -169,20 +170,27 @@ npm test -- --testPathPattern=azure-validation
 └─────────────────────┬───────────────────────────────────┘
                       ▼
 ┌─────────────────────────────────────────────────────────┐
-│  7. CHECK TOKENS:                                       │
+│  7. VALIDATE REFERENCES:                                │
+│     npm run references {skill-name}                     │
+│     • Check markdown links are valid                    │
+│     • Ensure links stay within skill directory          │
+└─────────────────────┬───────────────────────────────────┘
+                      ▼
+┌─────────────────────────────────────────────────────────┐
+│  8. CHECK TOKENS:                                       │
 │     npm run tokens -- check plugin/skills/{skill-name}  │
 │     npm run tokens -- suggest (gather optimizations)    │
 └─────────────────────┬───────────────────────────────────┘
                       ▼
 ┌─────────────────────────────────────────────────────────┐
-│  8. SUMMARY: Display before/after comparison            │
+│  9. SUMMARY: Display before/after comparison            │
 │     • Score change (Low → Medium-High)                  │
 │     • Token delta (+/- tokens)                          │
 │     • Unimplemented suggestions                         │
 └─────────────────────┬───────────────────────────────────┘
                       ▼
 ┌─────────────────────────────────────────────────────────┐
-│  9. PROMPT USER: Choose action                          │
+│  10. PROMPT USER: Choose action                         │
 │     [C] Commit changes                                  │
 │     [I] Create GitHub issue with suggestions            │
 │     [S] Skip (discard changes)                          │

.github/skills/sensei/SKILL.md

@@ -28,19 +28,20 @@ When user says "sensei help" or asks how to use sensei, show this:
 ║  EXAMPLES:                                                       ║
 ║    Run sensei on appinsights-instrumentation                     ║
 ║    Run sensei on azure-security --skip-integration               ║
-║    Run sensei on azure-security, azure-networking                ║
+║    Run sensei on azure-security, azure-observability             ║
 ║    Run sensei on all Low-adherence skills                        ║
 ║                                                                  ║
 ║  WHAT IT DOES:                                                   ║
-║    1. READ    - Load skill's SKILL.md, tests, and token count    ║
-║    2. SCORE   - Check compliance (Low/Medium/Medium-High/High)   ║
-║    3. SCAFFOLD- Create tests from template if missing            ║
-║    4. IMPROVE - Add USE FOR triggers + DO NOT USE FOR            ║
-║    5. TEST    - Run tests, fix if needed                         ║
-║    6. TOKENS  - Check token budget, gather suggestions           ║
-║    7. SUMMARY - Show before/after with suggestions               ║
-║    8. PROMPT  - Ask: Commit, Create Issue, or Skip?              ║
-║    9. REPEAT  - Until Medium-High score + tests pass             ║
+║    1. READ      - Load skill's SKILL.md, tests, and token count  ║
+║    2. SCORE     - Check compliance (Low/Medium/Medium-High/High) ║
+║    3. SCAFFOLD  - Create tests from template if missing          ║
+║    4. IMPROVE   - Add USE FOR triggers + DO NOT USE FOR          ║
+║    5. TEST      - Run tests, fix if needed                       ║
+║    6. REFERENCES- Validate markdown links                        ║
+║    7. TOKENS    - Check token budget, gather suggestions         ║
+║    8. SUMMARY   - Show before/after with suggestions             ║
+║    9. PROMPT    - Ask: Commit, Create Issue, or Skip?            ║
+║   10. REPEAT    - Until Medium-High score + tests pass           ║
 ║                                                                  ║
 ║  TARGET SCORE: Medium-High                                       ║
 ║    ✓ Description > 150 chars                                     ║
@@ -70,7 +71,7 @@ Run sensei on azure-deploy
 
 ### Multiple Skills
 ```
-Run sensei on azure-security, azure-networking, azure-observability
+Run sensei on azure-security, azure-observability
 ```
 
 ### By Adherence Level
@@ -94,10 +95,11 @@ For each skill, execute this loop until score >= Medium-High AND tests pass:
 5. **IMPROVE FRONTMATTER** - Add triggers, anti-triggers, compatibility (stay under 1024 chars)
 6. **IMPROVE TESTS** - Update `shouldTriggerPrompts` and `shouldNotTriggerPrompts` to match
 7. **VERIFY** - Run `cd tests && npm test -- --testPathPattern={skill-name}`
-8. **TOKENS** - Check token budget, gather optimization suggestions
-9. **SUMMARY** - Display before/after comparison with unimplemented suggestions
-10. **PROMPT** - Ask user: Commit, Create Issue, or Skip?
-11. **REPEAT** - Go to step 2 (max 5 iterations per skill)
+8. **VALIDATE REFERENCES** - Run `cd scripts && npm run references {skill-name}` to check markdown links
+9. **TOKENS** - Check token budget, gather optimization suggestions
+10. **SUMMARY** - Display before/after comparison with unimplemented suggestions
+11. **PROMPT** - Ask user: Commit, Create Issue, or Skip?
+12. **REPEAT** - Go to step 2 (max 5 iterations per skill)
 
 ## Scoring Criteria (Quick Reference)
 

.github/skills/sensei/references/EXAMPLES.md

@@ -120,7 +120,7 @@ description: |
   security services are available", "explain managed identity", "RBAC basics", "Key Vault
   concepts", "Entra ID overview", "Defender for Cloud features". DO NOT USE FOR: hardening
   existing resources (use azure-security-hardening), Entra app registration setup (use
-  entra-app-registration), or role assignment guidance (use azure-role-selector).
+  entra-app-registration), or role assignment guidance (use azure-rbac).
 ---
 ```
 

.github/skills/sensei/references/LOOP.md

@@ -36,19 +36,19 @@ The Ralph loop is an iterative improvement cycle inspired by the ["Ralph Wiggum"
                   │ YES             │           │
                   ▼                 ▼           │
          ┌──────────────────┐       │           │
-         │  6. CHECK TOKENS │       │           │
+         │  7. CHECK TOKENS │       │           │
          │  Get suggestions │       │           │
          └────────┬─────────┘       │           │
                   │                 │           │
                   ▼                 │           │
          ┌──────────────────┐       │           │
-         │  7. SUMMARY      │       │           │
+         │  8. SUMMARY      │       │           │
          │  Before/After    │       │           │
          └────────┬─────────┘       │           │
                   │                 │           │
                   ▼                 │           │
          ┌──────────────────┐       │           │
-         │  8. PROMPT USER  │       │           │
+         │  9. PROMPT USER  │       │           │
          │  Commit/Issue?   │       │           │
          └────────┬─────────┘       │           │
                   │                 │           │
@@ -83,6 +83,12 @@ The Ralph loop is an iterative improvement cycle inspired by the ["Ralph Wiggum"
                                     │           │
                                     ▼           │
                            ┌──────────────────┐ │
+                           │ 5c. VALIDATE     │ │
+                           │   REFERENCES     │ │
+                           └────────┬─────────┘ │
+                                    │           │
+                                    ▼           │
+                           ┌──────────────────┐ │
                            │  Iteration < 5?  │─┘
                            └────────┬─────────┘
                                     │ NO
@@ -220,6 +226,33 @@ This runs only unit and trigger tests, which are fast and don't require the Copi
 - Adjust frontmatter or test prompts
 - Re-run (counts as sub-iteration)
 
+### Step 5c: VALIDATE REFERENCES
+
+**Action:** Check that all markdown links in skill files are valid and don't escape the skill directory
+
+**Command:**
+```bash
+cd scripts && npm run references {skill-name}
+```
+
+**What it checks:**
+1. Every local markdown link points to an actual file or directory
+2. Every local markdown link stays within the skill's own directory
+3. External links (http://, https://, mailto:) are ignored
+4. Fragment-only links (#anchor) are ignored
+
+**Expected outcome:**
+- ✅ All references are valid and contained within skill directory
+
+**If validation fails:**
+- Review broken or escaped references
+- Fix invalid links or move referenced files into skill directory
+- Re-run validation (counts as sub-iteration)
+
+**Example issues caught:**
+- Broken link: `[CLI Commands](references/CLI-COMMANDS.md)` when file doesn't exist
+- Escaped reference: `[Other skill](../../other-skill/SKILL.md)` crosses skill boundary
+
 ### Step 6: CHECK TOKENS
 
 **Action:** Analyze token usage and gather optimization suggestions

.github/skills/sensei/references/SCORING.md

@@ -214,14 +214,13 @@ From the [frontmatter audit](https://gist.github.com/spboyer/28c31bf0cafb8748940
 2. `azure-diagnostics`
 3. `azure-security`
 4. `azure-security-hardening`
-5. `azure-networking`
-6. `azure-observability`
-7. `azure-storage`
-8. `azure-ai`
-9. `azure-validation`
-10. `azure-nodejs-production`
-11. `entra-app-registration`
-12. `azure-role-selector`
+5. `azure-observability`
+6. `azure-storage`
+7. `azure-ai`
+8. `azure-validation`
+9. `azure-nodejs-production`
+10. `entra-app-registration`
+11. `azure-rbac`
 
 ### Medium-Adherence Skills
 

.github/skills/skill-authoring/SKILL.md

@@ -37,6 +37,7 @@ Metadata (~100 tokens) loads at startup. SKILL.md (<5000 tokens) loads on activa
 
 References are JIT (just-in-time) loaded:
 - Only files explicitly linked via `[text](references/file.md)` load
+- **Link to files, not folders** - `[Recipes](references/recipes/README.md)` not `[Recipes](references/recipes/)`
 - Each file loads in full (not sections)
 - No caching between requests - write self-contained files
 - Use recipes/services patterns for multi-option skills
@@ -48,12 +49,26 @@ See [REFERENCE-LOADING.md](references/REFERENCE-LOADING.md) for details.
 ```bash
 # Run from the scripts directory
 cd scripts
-npm run tokens -- check plugin/skills/my-skill/SKILL.md
+npm run references              # Validate all skill links
+npm run tokens -- check         # Check token limits
 ```
 
+### Integrity Checks
+
+When reviewing or authoring skills, verify:
+1. **No broken links** - All referenced files exist
+2. **No orphaned references** - All reference files are linked
+3. **Token budgets** - References under 1000 tokens (split if exceeded)
+4. **No duplicates** - Consolidate repeated content
+5. **No out-of-place guidance** - Service-specific content belongs in service-specific references
+
+See [Validation](references/validation/README.md) for detailed procedures.
+
 ## Reference Documentation
 
-- [GUIDELINES.md](references/GUIDELINES.md) - Detailed writing guidelines
-- [REFERENCE-LOADING.md](references/REFERENCE-LOADING.md) - How references load and token efficiency
-- [CHECKLIST.md](references/CHECKLIST.md) - Pre-submission checklist
+- [Guidelines](references/guidelines/README.md) - Detailed writing guidelines
+- [Token Budgets](references/token-budgets.md) - Limits and splitting guidance
+- [Reference Loading](references/REFERENCE-LOADING.md) - How references load
+- [Checklist](references/CHECKLIST.md) - Pre-submission checklist
+- [Validation](references/validation/README.md) - Link and reference validation
 - [agentskills.io/specification](https://agentskills.io/specification) - Official spec

.github/skills/skill-authoring/references/CHECKLIST.md

@@ -14,11 +14,12 @@ Use this checklist before submitting a new skill or updating an existing one.
 
 ## Token Budget
 
+See [Token Budgets](token-budgets.md) for detailed limits.
+
 - [ ] SKILL.md is under 500 tokens (soft limit)
 - [ ] SKILL.md is under 5000 tokens (hard limit per spec)
-- [ ] SKILL.md is under 500 lines
 - [ ] Reference files are each under 1000 tokens
-- [ ] Run `npm run check` from `scripts/` directory
+- [ ] Run `npm run tokens -- check` from `scripts/` directory
 
 ## Structure
 
@@ -29,6 +30,14 @@ Use this checklist before submitting a new skill or updating an existing one.
 - [ ] File references use relative paths from skill root
 - [ ] No deeply nested reference chains
 
+## Link and Reference Integrity
+
+- [ ] All markdown links point to existing files (no broken links)
+- [ ] All files in `references/` are linked from SKILL.md or other references (no orphans)
+- [ ] References >1000 tokens are split into folder with README.md
+- [ ] Duplicate content is consolidated into shared references
+- [ ] No out-of-place guidance (service-specific content in generic sections)
+
 ## Content Quality
 
 - [ ] Instructions are action-oriented (step-by-step)
@@ -56,12 +65,9 @@ Use this checklist before submitting a new skill or updating an existing one.
 ## Final Steps
 
 ```bash
-# Run token check
 cd scripts
-npm run check
-
-# Generate updated metadata (optional)
-npm run tokens
+npm run references        # Validate all skill links
+npm run tokens -- check   # Check token limits
 ```
 
-If any checks fail, see [GUIDELINES.md](GUIDELINES.md) for guidance.
+If any checks fail, see [Guidelines](guidelines/README.md) for guidance.