# Skill Health Lens

> Audit Agent Skills (SKILL.md files) for trust score, token budget, duplicate content, and risky tool surface. Use when reviewing a SKILL.md, before publishing a skill, or when an agent's skill library starts to feel bloated or untrustworthy. Invoke with "/skill-health-lens" or ask the agent to "lens this skill".

- Skill: `modelbound/skill-health-lens` (Agent Skill)
- Install (CLI): `npx skillmds@latest add modelbound/skill-health-lens`
- Raw SKILL.md: https://api.skillmd.com/api/skills/modelbound/skill-health-lens/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ModelBound (https://skillmd.com/u/modelbound)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/modelbound/skill-health-lens

---


# Skill Health Lens

Audits Agent Skills against the same checks ModelBound runs in its Skill Development Pipeline — **Trust**, **Token Budget**, **Duplicates**, and **Tool Surface** — without running the full pipeline.

## When to use

- Reviewing or editing any `SKILL.md` file
- Before publishing a skill to a team marketplace or Cursor Marketplace
- When an agent's skill library has grown past ~10 skills
- When a skill keeps misfiring or being ignored by the agent

## What to check

For each `SKILL.md` in scope:

### 1. Trust score (target: ≥ 70)
Score the skill 0–100 using ModelBound's `@modelbound/skill-trust` heuristics:

- **Frontmatter completeness** — `name`, `description`, optional `allowed_tools` present and well-formed
- **Description quality** — has a clear "when to use" signal, is between 30 and 400 chars, names concrete triggers
- **Instruction shape** — uses numbered steps or bullets, no walls of prose, no contradictory rules
- **Determinism** — avoids vague language ("maybe", "consider", "could") in favor of imperatives
- **Provenance** — links to source docs or examples where claims are made

Report trust tier:
- **Green** ≥ 80
- **Amber** 60–79
- **Red** < 60

### 2. Token budget
Estimate tokens (chars / 4) for the skill body and compare against ModelBound's thresholds:

- **Green** ≤ 2,000 tokens
- **Amber** 2,000–5,000 tokens
- **Red** > 5,000 tokens

Flag the top 3 most token-heavy sections and suggest where to split into sub-skills or move into a referenced doc.

### 3. Duplicate content
For each skill, compare with every other `SKILL.md` in the workspace using a Jaccard similarity over normalized tokens. Flag pairs with similarity ≥ 0.4 as **likely duplicates** and ≥ 0.6 as **near-clones**. Suggest a merge or rename.

### 4. Tool surface audit
Parse the `allowed_tools` frontmatter (and any explicit tool mentions in the body). Flag:

- Skills with **no** `allowed_tools` field (implicit unrestricted access)
- Skills granting access to destructive tools (`run_terminal`, `delete_file`, `write_file` on broad globs)
- Skills mixing **read-only research** with **mutating actions** (split recommendation)

## How to run

1. Glob `**/SKILL.md` from the workspace root (or operate on the currently open file).
2. For each file, compute the four sections above.
3. Produce a single Markdown report grouped by skill, then a workspace-level summary table.
4. End with **3 prioritized fixes** the user can apply now (concrete, copy-paste-ready edits).

## ModelBound integration

When the user is signed in to ModelBound (via the `modelbound` MCP server defined in this plugin), also:

- Call `skills.list` (optionally filtered by `category` or `group_id`) and `skills.listGroups` to pull the user's Skills — including a whole group at once when they say things like "lens my Onboarding group" or "audit every Backend skill".
- Use `skills.get` / `skills.getFile` for the full bundle, and `platform.exportSkillForIde` with `group_id` to bundle every skill in a group into the IDE in one shot.
- Offer to request an AI review for any skill scoring Red on Trust.
- Surface team-level policies (banned tools, required sections) so they're checked alongside the four core checks.

> Note: ModelBound no longer uses the legacy "pack" concept — everything is a **Skill**, optionally organized into a **Skill group**. Older `packs.*` / `export_pack_for_ide` tool names still work as deprecated aliases but new code should use `skills.*` and `platform.exportSkillForIde`.

If the MCP server is unreachable or the user is not signed in, the four core checks still run locally.

## Output format

```
# Skill Health Lens — <N> skills in <workspace>

## Summary
| Skill | Trust | Tokens | Duplicates | Tools |
| --- | --- | --- | --- | --- |
| code-reviewer | 🟢 86 | 🟢 1.2k | — | ✅ scoped |
| pr-helper    | 🟡 71 | 🔴 6.8k | clones code-reviewer (0.62) | ⚠️ unrestricted |

## Top 3 fixes
1. **pr-helper**: split into `pr-summarize` and `pr-review` (current body is 6.8k tokens).
2. **pr-helper**: add `allowed_tools: [read_file, grep]` to drop the unrestricted warning.
3. **pr-helper** ↔ **code-reviewer**: 62% overlap — consider merging or extracting a shared rule.

## Details
...
```

## Out of scope

- Editing skills automatically — the agent surfaces fixes, the user applies them
- Replacing the ModelBound Skill Development Pipeline — this is the local "Test & Optimize" lens only
- Running scoring inside the agent loop on every keystroke — invoke on demand