microsoft / microsoft/GitHub-Copilot-for-Azure

Consolidate redundant .github/skills: markdown-token-optimizer and skill-reviewer into sensei

Open
#1,839 2 comments 1 reaction 2 assignees Claimed by @spboyer View on GitHub
untriaged
Dominant language
Python
Stars
250
Forks
204
Avg merge
1d 12h
Merged PRs (30d)
67

Description

## Summary

Analysis of the `.github/skills/` meta-skills reveals that 2 of 3 skills compared are redundant with `sensei`:

| Skill | Verdict | Rationale |
|-------|---------|-----------|
| **skill-authoring** | ✅ **Keep** | Foundational knowledge base. Sensei depends on it (links to it for token budgets, reference loading rules). Only skill that teaches how to create a new skill from scratch. |
| **markdown-token-optimizer** | ❌ **Delete entirely** | 100% redundant. Sensei already runs `npm run tokens -- count/check/suggest` in steps 1, 9-10. The 2 reference files (ANTI-PATTERNS.md, OPTIMIZATION-PATTERNS.md) are just expanded examples of generic markdown writing tips — sensei's own `TOKEN-INTEGRATION.md` already has a Quick Reference table covering the same patterns. Nothing to salvage. |
| **skill-reviewer** | ⚠️ **Fold into sensei** | ~80% content overlap with sensei's scoring criteria. Unique parts (severity classification, PR output format, section checks) could become a `--review` mode in sensei. |

## Detailed Findings

### markdown-token-optimizer — Fully Redundant

- **Workflow duplication**: Its workflow (Count → Scan → Suggest → Summary) is 100% embedded in sensei's Ralph loop (steps 1, 9-10)
- **Token CLI**: Sensei already calls `npm run tokens -- count`, `check`, and `suggest`
- **Reference files**: `ANTI-PATTERNS.md` covers generic markdown tips (remove emojis, filler words, echo headers). `OPTIMIZATION-PATTERNS.md` covers tables vs lists, inline code, progressive disclosure. All of this is already summarized in sensei's `TOKEN-INTEGRATION.md` Quick Reference table.
- **No unique value** to preserve

### skill-reviewer — Mostly Redundant

- **~80% overlap**: The review checklist (frontmatter checks, token budgets, trigger analysis, YAML safety, name validation) mirrors sensei's `SCORING.md` almost exactly
- **Unique content worth preserving**:
- Severity classification (Critical/High/Medium/Low findings)
- Structured PR review output format with positive acknowledgment
- Required SKILL.md section checks (Quick Reference, MCP Tools, etc.)
- Test registration checks (`tests/skills.json`)
- **Recommendation**: Add a `--review` mode to sensei that produces PR-style output, absorb the unique references

## Proposed Actions

1. **Delete `.github/skills/markdown-token-optimizer/`** entirely
2. **Update sensei's `TOKEN-INTEGRATION.md`** to remove dangling links to deleted files
3. **Add `--review` flag to sensei** for PR review output
4. **Move unique skill-reviewer references** (`severity-classification.md`, `output-format.md`, `routing-analysis.md`) into sensei
5. **Delete `.github/skills/skill-reviewer/`**
6. **Update sensei's description** to absorb trigger phrases from removed skills

## Risks

- **Sensei token bloat**: Mitigate by keeping new references JIT-loaded
- **Trigger routing gaps**: Ensure "review skill PR", "optimize markdown" triggers route to sensei after removal
- **Breaking workflows**: Users who invoke removed skills directly need those triggers in sensei's description

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.