| name | sensei |
| description | Iteratively improve skill frontmatter compliance using the Ralph loop pattern. USE FOR: run sensei, sensei help, improve skill, fix frontmatter, skill compliance, frontmatter audit, improve triggers, add anti-triggers, batch skill improvement, check skill tokens. DO NOT USE FOR: creating new skills (use skill-authoring), writing skill content, token optimization only (use markdown-token-optimizer), or non-frontmatter changes. |
Sensei
"A true master teaches not by telling, but by refining." - The Skill Sensei
Automates skill frontmatter improvement using the Ralph loop pattern - iteratively improving skills until they reach Medium-High compliance with passing tests, then checking token usage and prompting for action.
Help
When user says "sensei help" or asks how to use sensei, show this:
╔══════════════════════════════════════════════════════════════════╗
║ SENSEI - Skill Frontmatter Compliance Improver ║
╠══════════════════════════════════════════════════════════════════╣
║ ║
║ USAGE: ║
║ Run sensei on <skill-name> # Single skill ║
║ Run sensei on <skill-name> --skip-integration # Fast mode ║
║ Run sensei on <skill1>, <skill2>, ... # Multiple skills ║
║ Run sensei on all Low-adherence skills # Batch by score ║
║ Run sensei on all skills # All skills ║
║ ║
║ EXAMPLES: ║
║ Run sensei on appinsights-instrumentation ║
║ Run sensei on azure-security --skip-integration ║
║ Run sensei on azure-security, azure-networking ║
║ 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 ║
║ ║
║ TARGET SCORE: Medium-High ║
║ ✓ Description > 150 chars ║
║ ✓ Has "USE FOR:" trigger phrases ║
║ ✓ Has "DO NOT USE FOR:" anti-triggers ║
║ ✓ SKILL.md < 500 tokens (soft limit) ║
║ ║
║ MORE INFO: ║
║ See .github/skills/sensei/README.md for full documentation ║
║ ║
╚══════════════════════════════════════════════════════════════════╝
When to Use
- Improving a skill's frontmatter compliance score
- Adding trigger phrases and anti-triggers to skill descriptions
- Batch-improving multiple skills at once
- Auditing and fixing Low-adherence skills
Invocation Modes
Single Skill
Run sensei on azure-deploy
Multiple Skills
Run sensei on azure-security, azure-networking, azure-observability
By Adherence Level
Run sensei on all Low-adherence skills
All Skills
Run sensei on all skills
The Ralph Loop
For each skill, execute this loop until score >= Medium-High AND tests pass:
- READ - Load
plugin/skills/{skill-name}/SKILL.md, tests, and token count
- SCORE - Run rule-based compliance check (see SCORING.md)
- CHECK - If score >= Medium-High AND tests pass → go to TOKENS step
- SCAFFOLD - If
tests/{skill-name}/ doesn't exist, create from tests/_template/
- IMPROVE FRONTMATTER - Add triggers, anti-triggers, compatibility (stay under 1024 chars)
- IMPROVE TESTS - Update
shouldTriggerPrompts and shouldNotTriggerPrompts to match
- VERIFY - Run
cd tests && npm test -- --testPathPattern={skill-name}
- TOKENS - Check token budget, gather optimization suggestions
- SUMMARY - Display before/after comparison with unimplemented suggestions
- PROMPT - Ask user: Commit, Create Issue, or Skip?
- REPEAT - Go to step 2 (max 5 iterations per skill)
Scoring Criteria (Quick Reference)
| Score | Requirements |
|---|
| Low | Basic description, no explicit triggers, no anti-triggers |
| Medium | Has trigger keywords/phrases, description > 150 chars |
| Medium-High | Has "USE FOR:" triggers AND "DO NOT USE FOR:" anti-triggers |
| High | Triggers + anti-triggers + compatibility field |
Target: Medium-High (triggers + anti-triggers present)
Frontmatter Template
---
name: skill-name
description: |
[1-2 sentence description of what the skill does]
USE FOR: [trigger phrase 1], [trigger phrase 2], [trigger phrase 3]
DO NOT USE FOR: [scenario] (use other-skill), [scenario] (use another-skill)
---
IMPORTANT: Always use multi-line YAML format (|) for descriptions over 200 characters. Single-line descriptions become difficult to read, review, and maintain. See azure-ai, azure-functions for examples.
Keep total description under 1024 characters.
Test Scaffolding
When tests don't exist, scaffold from tests/_template/:
cp -r tests/_template tests/{skill-name}
Then update:
SKILL_NAME constant in all test filesshouldTriggerPrompts - 5+ prompts matching new frontmatter triggersshouldNotTriggerPrompts - 5+ prompts matching anti-triggers
Commit Messages:
sensei: improve {skill-name} frontmatter
Constraints
- Only modify
plugin/skills/ - these are the Azure skills used by Copilot
.github/skills/ contains meta-skills like sensei for developer tooling- Max 5 iterations per skill before moving on
- Description must stay under 1024 characters
- SKILL.md should stay under 500 tokens (soft limit)
- Tests must pass before prompting for action
- User chooses: Commit, Create Issue, or Skip after each skill
Flags
| Flag | Description |
|---|
--skip-integration | Skip integration tests for faster iteration. Only runs unit and trigger tests. |
⚠️ Skipping integration tests speeds up the loop but may miss runtime issues. Consider running full tests before final commit.
Reference Documentation
Related Skills
