Sensei

"A true master teaches not by telling, but by refining." - The Skill Sensei

Sensei validates portable Agent Skills frontmatter and suggests authoring improvements using the Ralph loop pattern. Medium-High is a Sensei advisory target, not a specification compliance level.

Specification versus advice: score keeps portable diagnostics in specChecks and optional Sensei recommendations in checks, including license/version suggestions. The standard requires only name and description; 150 characters, 60 words, WHEN:, type prefixes, and the 500-token target are heuristics, not normative rules. Static scores and proof artifacts are neither observed activation nor security audits. See scoring and host portability for constraints, runtime limitations, and the separately owned Copilot extension work in #5.

Table of Contents

• Overview
• Quick Start
• Distribution and Release Status
• Prerequisites
• How It Works
• Configuration
• Scoring Criteria
• Examples
• Troubleshooting
• Contributing

---

Overview

The Problem

Skills without proper frontmatter lead to skill collision - agents invoking the wrong skill for a given prompt. Common issues include:

• No triggers - Agent doesn't know when to activate the skill
• Ambiguous scope - Similar skills compete for the same request
• Vague descriptions - Length alone does not establish useful context
• Token bloat - Oversized skills waste context window

The Solution

Sensei implements the "Ralph Wiggum" technique:

1. Read - Load the skill's current state and token count
2. Score - Evaluate frontmatter compliance
3. Improve - Clarify positive scope and test close near-misses
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

---

Quick Start

Using with Copilot CLI

Single Skill

Run sensei on my-skill-name

Single Skill (Fast Mode)

Run sensei on my-skill-name --fast

Multiple Skills

Run sensei on skill-a, skill-b, skill-c

All Low-Adherence Skills

Run sensei on all Low-adherence skills

All Skills

Run sensei on all skills

GEPA Mode (Deep Optimization)

Run sensei on my-skill-name --gepa
Run sensei score my-skill-name

Score-only mode runs without LLM calls.

External Integration Modes

Published packages and Action tags may lag main; see release status before using newly merged features.

CLI / npx

npx @spboyer/sensei score .
npx @spboyer/sensei check --root . --config .token-limits.json --strict

--root resolves paths; --config selects limits; --emit-proof writes sensei-audit.md; .sensei.json enables repo policy. Install globally via npm i -g @spboyer/sensei.

GitHub Action

steps:
  - uses: actions/checkout@v4
  - uses: spboyer/[email protected]
    with:
      command: check
      root: .
      path: .
      config: .token-limits.json
      strict: 'true'

Library API

import { scoreSkillContent } from '@spboyer/sensei/score';
import { parseFrontmatter } from '@spboyer/sensei/parse';
import { checkNameCompliance } from '@spboyer/sensei/checks';

const result = scoreSkillContent(renderedSkillMarkdown, { path: 'skills/my-skill', moduleCount: 2 });
const frontmatter = parseFrontmatter(renderedSkillMarkdown);
checkNameCompliance(frontmatter?.name ?? '');

path is metadata; moduleCount defaults to 0. parseFrontmatter returns null for absent/unclosed delimiters, and optional errors for invalid delimited YAML. Nested metadata and scalar types are preserved; inspect diagnostics before using typed convenience fields.

---

Optional Behavioral Evaluation

npm run --silent tokens -- eval manifest.json --root=/path/to/project --format=json

Run from a current Sensei checkout with script dependencies installed. Compare repeated host observations and output assertions against a baseline. Unavailable evidence cannot pass; GEPA keyword fitness is not observed activation. No provider or Python dependency is added. See the trusted adapter contract, exit codes, and protocol smoke test.

GEPA Commands

uv run scripts/src/gepa/auto_evaluator.py score --skill my-skill --skills-dir skills --tests-dir tests
uv run --with-requirements scripts/src/gepa/requirements.txt scripts/src/gepa/auto_evaluator.py optimize --skill my-skill --skills-dir skills --tests-dir tests

Score-only mode needs no GEPA installation. Optimization requires the optional version in scripts/src/gepa/requirements.txt and model access; if that version is unavailable from your package index, optimization cannot run. GEPA uses keyword/proxy fitness; it does not observe whether a host loaded a skill.

Workflow prompt flags (not token CLI options)

Flag	Description
--fast	Skip tests for faster iteration
--gepa	Use GEPA evolutionary optimization instead of template-based improvements
--skip-integration	Skip integration tests (unit + trigger tests only)

⚠️ Note: Using --fast speeds up the loop significantly but may miss issues. Consider running full tests before final commit.

---

This is the beginning of the README. Read the rest at the original. Read the full README ↗