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 files

• shouldTriggerPrompts

• 5+ prompts matching new frontmatter triggers

• shouldNotTriggerPrompts

• 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

• SCORING.md - Detailed scoring criteria

• LOOP.md - Ralph loop workflow details

• EXAMPLES.md - Before/after examples

• TOKEN-INTEGRATION.md - Token budget integration

Related Skills

• markdown-token-optimizer - Token analysis and optimization

• skill-authoring - Skill writing guidelines