SkillFoxx

Sensei skill

Validates Agent Skills frontmatter, scores it and improves a skill description and size step by step with the Ralph loop.

  • 60 ★ on the repository
  • Last commit
  • MIT
Skill

Extended access

Why this level

  • The skill edits the SKILL.md of audited skills and calls a model in GEPA mode.
All reasons and checks

spboyer/senseiAuthor:spboyer

Install

In your terminal, with SkillFoxx CLI

npx skillfoxx add skills/sensei

Detects the agents on your machine, shows the access level and pins the version.

Other ways to install

Access and checks

How we review

Extended accessThe tool runs code or makes network calls and only reads external data.

  • The skill edits the SKILL.md of audited skills and calls a model in GEPA mode.

This is third-party code. Review the repository files before installing.

What it does

Sensei reads a skill, counts its tokens and scores its frontmatter: whether triggers exist, whether the description is vague, whether the text is bloated. The Ralph loop then repeats steps: improve the description, run tests, recount tokens and show before and after. Each round ends with a question: commit, open an issue or skip. Agent Skills specification checks (`name` and `description`) are kept apart from Sensei own advice: it calls the 150 character and 500 token limits heuristics. The `score` mode makes no model calls. A `--gepa` mode adds deep optimization, and there is a `@spboyer/sensei` CLI and a GitHub Action for CI checks.

Who it is for. Skill authors whose agent calls the wrong skill, or misses the right one, because of a weak description and a bloated SKILL.md.

Good fit when

  • Two similar skills collide and the agent picks the wrong one.
  • A skill description names no triggers, so it rarely fires.
  • SKILL.md has grown and takes extra room in the context.
  • You need a `sensei-audit.md` report and a strict skill check in CI.

Not a fit when

  • You need a security review: static scores are not an audit.
  • You must prove a skill really activates: a text score does not observe that.
  • There is no Node.js 22 or newer: the source CLI depends on it.

Example request

Run sensei on my-skill-name and show the score before and after, then offer a commit.

Limitations

Scores are static: they do not observe real skill activation and are not a security check. The Medium-High target is Sensei advice, not a specification compliance level. Published packages and Action tags can lag `main`, so for the newest features the README suggests cloning the repository and installing dependencies in `scripts`. Node.js 22.12 or newer is required. GEPA mode also needs Python 3.10 and uv, and the improvement rounds call a model and spend tokens.

How to disable. Delete the cloned folder `~/.copilot/skills/sensei` or `.github/skills/sensei`. Remove the global CLI with `npm uninstall --global @spboyer/sensei`.

FAQ

How do I run a check without a model?

Run `npx @spboyer/sensei score .`. The score mode rates frontmatter and tokens with no model calls. A strict CI check is `npx @spboyer/sensei check --root . --strict`.

What is the Ralph loop?

It is a repeat of eight steps: read, score, improve, verify tests, recheck tokens, summarize, ask what to do, and repeat until the target score.

Can Sensei run in GitHub Actions?

Yes. Use `spboyer/sensei@v1.5.0` with the `check` command and `root` and `path` inputs. The tag can lag behind `main`.

What does Sensei assess in a skill?

Presence of triggers, clarity of the description, token size and frontmatter conformity to the Agent Skills specification. The project calls the 150 character and 500 token limits heuristics.

What must be installed first?

The source CLI needs Node.js 22.12 or newer and `npm install` inside `scripts`. GEPA mode also needs Python 3.10 and uv.

Discussion

No questions or reviews yet.

Skills

A skill that designs, tests, evaluates and packages other agent skills, starting from architecture

SkillExtended access212

An autonomous spec-driven coding loop: the agent takes a task, checks acceptance criteria and commits until the list runs out.

SkillBroad access313

A catalog of nearly two hundred skills: code delivery, review, debugging, AI governance, product work and agent coordination.

SkillMinimal access175

A CLI that runs your agent on tasks and revises its skills, keeping a change only when held-out tasks confirm the gain

CLIBroad access287

A meta-skill that folds rules scattered across AGENTS.md, CLAUDE.md and Cursor files into one project skill with task routes.

PluginExtended access622

A doctor skill for agent skills that picks an architecture, audits against 21 red lines and returns a report with line references

SkillExtended access267

README in short

The project validates portable Agent Skills frontmatter and adds optional recommendations. Improvement runs as a loop with human confirmation while the skill token budget stays under control.

README badge

Original SKILL.md

---
name: sensei
description: "**WORKFLOW SKILL** - Iteratively improve skill frontmatter and routing clarity. WHEN: \"run sensei\", \"sensei help\", \"improve skill\", \"fix frontmatter\", \"score skill\", \"check skill tokens\". INVOKES: token CLI, test runners, git. FOR SINGLE OPERATIONS: use the token CLI directly."
---

# Sensei

Improve skills using the [Ralph loop](references/loop.md). For help, explain modes,
defaults, and checks from [configuration](references/configuration.md).
For source bundles and installation, see [distribution](references/distribution.md).

1. **Read** the target `SKILL.md`, references, tests, and repo-local instructions.
   Verify tooling exists before claiming it is missing. Count baseline tokens:
   From the Sensei checkout, pass the target repository root and a path relative
   to it: `npm run tokens -- count --root <target-repo> <skill-path>/SKILL.md`.
2. **Score** with `npm run tokens -- score --root <target-repo> <skill-path>`.
   Separate portable-spec
   diagnostics from [Sensei recommendations](references/scoring.md).
   Preserve `.sensei.json` and AGENTS.md short-description policy. A 150-character
   floor, 60-word target, type prefix, `WHEN:`, and 500-token target are heuristics,
   not specification requirements.
3. **Scaffold** missing tests using [templates](references/test-templates/skill-init.md).
   Use realistic positive prompts and close near-misses from intended scope;
   negative frontmatter syntax is not required.
4. **Improve** concise positive routing and operational instructions using
   [examples](references/examples.md). Keep descriptions non-empty and within
   1024 characters. Preserve meaningful boundaries; evaluate them on the target host.
   Check [portability](references/portability.md) before introducing host fields.
5. **Verify** with the target project's test runner; `--fast` skips tests but must
   report them as not run. GEPA mode uses optional keyword/proxy fitness, not
   observed host activation; follow [configuration](references/configuration.md).
6. **Check budgets** with
   `npm run tokens -- check --root <target-repo> <skill-path>/SKILL.md`.
   Report configured token-limit warnings separately from optional optimization
   suggestions. For MCP-aware skills, follow [MCP integration](references/mcp-integration.md).
7. **Summarize** changes, diagnostics, tests, token deltas, and remaining suggestions.
   `score --emit-proof` records static evidence, not runtime quality or a security audit.
   Ask whether to commit, create an issue, or skip; do not discard edits unasked.
8. **Repeat** until the advisory target and tests pass, at most five iterations.
   Process batches sequentially and report failures explicitly.

Report a problem