🥋

Sensei

Stop skill collisions.
Ship better agents.

Iteratively improve skill frontmatter compliance using the Ralph loop pattern.

npx skills add spboyer/sensei

Skills Without Frontmatter Break Things

Poor frontmatter leads to skill collision — agents invoking the wrong skill for a given prompt.

No triggers

Agent doesn't know when to activate the skill.

No anti-triggers

Agent doesn't know when NOT to use the skill.

Brief descriptions

Not enough context for accurate matching.

Token bloat

Oversized skills waste context window.

The Ralph Loop

Six steps, repeated until your skill reaches Medium-High compliance.

Read

Load skill state and count tokens

Score

Evaluate frontmatter compliance

Improve

Add triggers and anti-triggers

Verify

Run tests to confirm changes

Check

Analyze token usage and budget

Summary

Display before/after results

Before & After

From vague to precise — a single pass through the Ralph loop.

Before Low

---
name: pdf-processor
description: 'Process PDF files for various tasks'
---

After Medium-High

---
name: pdf-processor
description: |
  Process PDF files including text extraction,
  rotation, and merging.
  USE FOR: "extract PDF text", "rotate PDF",
  "merge PDFs", "split PDF", "PDF to text",
  "combine PDF files".
  DO NOT USE FOR: creating new PDFs
  (use document-creator), extracting images
  (use image-extractor), or OCR on scanned
  documents (use ocr-processor).
---

Scoring Levels

Sensei targets Medium-High — the sweet spot between completeness and token efficiency.

Low

No triggers, short description

Medium

Has triggers, missing anti-triggers

Medium-High

Triggers + anti-triggers present

← Target

High

Full routing clarity with INVOKES

Quick Start

Install it as a skill, run it with npx, wire it into CI, or import the parts you need.

npx skills add spboyer/sensei

Run sensei on my-skill-name Improve one skill from Copilot CLI

npx @spboyer/sensei score . Score a skill directory without cloning Sensei

npx @spboyer/sensei check --root . --strict Run token validation in any project

import { parseFrontmatter } from '@spboyer/sensei/parse'; Use granular library exports in your own tooling

GitHub Action

Add spboyer/sensei@v1.5.0 to CI and run check on pull requests.

External roots

Use --root and --config to validate skills from another project directory.

Library exports

Import /score, /parse, or /checks without pulling in the CLI.

Full documentation on GitHub →