# Skill Auditor

> skill-auditor — Use when auditing, reviewing, or grading Hermes skills for quality. Checks trigger phrases, exact commands, pitfalls, verification steps, tool guidance, and shareability. Assigns A-F grade with specific fix suggestions. Run this before publishing a skill or when troubleshooting unreliable skills.

- **Type:** Skill
- **Install:** `agentstack add skill-atlasomnia-donna-starter-skill-auditor`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [AtlasOmnia](https://agentstack.voostack.com/s/atlasomnia)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [AtlasOmnia](https://github.com/AtlasOmnia)
- **Source:** https://github.com/AtlasOmnia/donna-starter/tree/main/skills/hermes/skill-auditor

## Install

```sh
agentstack add skill-atlasomnia-donna-starter-skill-auditor
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Skill Auditor — Quality Grading System (A–F)

Audit any Hermes skill file and assign a quality grade based on clarity, completeness, tool guidance, and shareability. Returns specific fix suggestions ranked by impact.

## When to Use

- User asks you to review, audit, or grade a skill
- You're about to create a new skill and want to validate the draft
- A skill is behaving unreliably (agent skips it, calls wrong tools, misses steps)
- User shares a skill file or path for feedback
- You're preparing skills for sharing with others

**Don't use for:** general Hermes troubleshooting, model selection, config review — those have their own skills.

## Grading Criteria

Each skill is scored across **five dimensions**. Points are deducted from 100. The final grade maps to a letter:

- **Grade A (90–100)** — Production-ready. Solid frontmatter, exact commands, real pitfalls, verification steps, consistent structure. Will fire reliably and execute correctly across model sizes.
- **Grade B (80–89)** — Minor gaps. Missing one dimension but still reliable.
- **Grade C (70–79)** — Functional but vague in places. Needs clarification on 1–2 key areas, especially with smaller models.
- **Grade D (60–69)** — Error-prone patterns detected. Incomplete steps or missing critical sections. Will fail silently on model switches.
- **Grade F (/SKILL.md`"
- Example: "Confirm email was sent by checking Sent folder"

**Partial marks (6–14):** Has some verification but incomplete or vague.
- Problem: "make sure it worked" — no way to actually verify

**Zero marks ( 20k chars without splitting to references

**Zero marks ( 20k chars without splitting to references: -2 pts
- Inconsistent with peer skills in same category: -1 pt

## How Skills Actually Work in Hermes

When auditing, keep the three-phase mechanism in mind:

1. **Discovery phase** — Hermes scans the `available_skills` block (the one-line description from each skill's frontmatter). If your description is vague, the router never loads the skill. Nothing inside SKILL.md matters if this step fails.
2. **Loading phase** — The full SKILL.md loads into context. Now structure, commands, and clarity matter.
3. **Execution phase** — The model follows the skill. Vague steps, missing commands, and absent verification cause silent failures, especially on smaller models.

Dimension 1 checks discovery. Dimensions 2-5 check loading and execution.

## Audit Workflow

### Step 0: Prefer class-level umbrellas

If the topic is broad (skill maintenance, config hygiene, verification, authoring), update or extend the umbrella skill for the class rather than creating a one-off session artifact. If the change includes a reusable check or workaround, move the detailed recipe into `references/` and keep the SKILL.md body as the durable overview.

### Step 1: Load the Skill

Read the skill file using `read_file`:

```
read_file(path="~/.hermes/skills///SKILL.md")
```

If the user provides a skill name, use `skills_list` to confirm it exists, then `skill_view(name="")`.

For an uninstalled local draft or GitHub staging directory, inspect the supplied `SKILL.md` path directly rather than assuming registry discovery. Do not treat a zero process exit code as proof that `hermes skills inspect ./SKILL.md` succeeded: inspect the command output for an explicit success result. If that Hermes release resolves only registry IDs or URLs, run a direct frontmatter/body validator against the local file, then audit the registered copy after installation with `hermes skills audit  --deep`.

If `skill_view` says the skill is not found and the user implies it should exist, do not stop at the installed skill registry. Search the user's vault/project notes for the requested skill/workflow name before concluding it is absent:

```
search_files(pattern="||", target="content", path="", file_glob="*.md")
search_files(pattern="**", target="files", path="")
```

When the vault contains a draft or workflow note, report that it is not installed as a Hermes skill and offer to promote it into the appropriate class-level umbrella skill rather than creating a narrow one-off skill.

### Step 2: Check Each Dimension

Systematically evaluate each of the five dimensions against the criteria above. Quote specific lines from the skill as evidence for each score.

### Step 3: Calculate Grade

Sum points across all five dimensions. Map to letter grade.

### Step 4: Generate Fix Suggestions

For every dimension scoring below full marks, provide **one concrete fix** with a before/after example pulled from the actual skill content.

### Step 5: Output Report

Use this exact format:

```
## Skill Audit: 

**Grade: X/YZ** — 

### Dimension Scores

- Frontmatter & Description: N/25 — 
- Exact Commands: N/25 — 
- Pitfalls Section: N/20 — 
- Verification Steps: N/15 — 
- Structure & Conventions: N/15 — 

### Fix Suggestions (ranked by impact)

1. **[Dimension]** 
2. **[Dimension]** 
...

### Related Skills Check

- `related_skills` in frontmatter:  — 
- Overlap with peers: 
```

## Common Pitfalls in Skill Auditing

1. **Auditing against your own expectations, not the rubric.** Stick to the five dimensions. Don't penalize for style preferences — only for missing structural elements.

2. **Calling a skill "too long" without checking content density.** A 15k-char skill with all five dimensions scores higher than a 3k-char skeleton. Length is fine if every line adds signal.

3. **Missing the difference between tool guidance and tool use.** The skill should tell the agent *which* tools to call and *when*. It doesn't need to actually call them during the audit — that's your job as the auditor.

4. **Ignoring shareability.** A skill with hardcoded paths like `~/Documents/` works for one person but breaks for everyone else. Flag this even if the rest is solid.

5. **Making claims about validator limits or tool names without verifying them against actual implementation.** Before asserting "the validator enforces X" or "use tool Y", check the source (`tools/skill_manager_tool.py` for validators, `model_tools.py` for registered tool names). Aspirational claims mislead auditors — if a limit isn't enforced, reframe it as a guideline.

## Verification Checklist

- [ ] Skill file loaded and readable
- [ ] All five dimensions scored with quoted evidence
- [ ] Grade calculated correctly (sum of dimension scores)
- [ ] Fix suggestions include before/after examples from the actual skill
- [ ] Report follows the output format exactly
- [ ] Related skills checked for overlap or missing cross-references
- [ ] If no canonical suite exists for a skill edit, use a temporary `hermes-verify-*.py` script under `/var/folders/...` and clean it up after the run

## Reference Files

- `references/ad-hoc-skill-verification.md` — temporary-script verification pattern for skill edits without a canonical suite.
- `references/public-skill-package-release-gate.md` — standalone GitHub skill-package staging, script safety, privacy review, independent closeout, and immutable pre-push verification.

## One-Shot Recipes

### Quick Audit (user provides skill name)

```
1. skill_view(name="")
2. Evaluate against five dimensions
3. Output grade report
```

### Audit and Fix (user wants immediate improvements)

```
1. skill_view(name="")
2. Evaluate and grade
3. skill_manage(action='patch', name="", old_string="", new_string="")
4. Re-audit to confirm grade improvement
```

### Batch Audit (user wants all skills reviewed)

```
1. skills_list() — capture the CLI-visible/registered skill set.
2. Independently inventory every SKILL.md under the target skill root; report registered skills and on-disk files as separate counts.
3. Validate every file with Hermes's installed frontmatter/content-size validator, then check duplicate names and concrete relative Markdown links.
4. Grade structural omissions as review signals, not automatic rewrite orders. Do not mass-add boilerplate when it only increases prompt weight.
5. Apply high-confidence fixes only: malformed frontmatter, confirmed broken links, validator size violations, and executable guidance proven stale or incomplete.
6. Re-run the validator across the entire library, run `hermes skills list`, and require zero validator failures before completion.
7. Save before/after machine-readable and Markdown reports plus a rollback backup.
```

### Recovery-safe rules for malformed and oversized skills

- A malformed placeholder is not evidence that a real integration exists. Never invent commands, backends, authentication flows, or generic “route to the relevant helper” instructions merely to make it pass the rubric. If no executable workflow can be verified, preserve it in the rollback backup and remove/archive the invalid entry rather than registering fiction.
- When a skill exceeds Hermes's content-size validator, keep the class-level operational core in `SKILL.md` and move a coherent secondary section into `references/.md`. Add a concise link from the core, then validate both the reduced size and the relative link.
- Markdown-link checks must distinguish concrete links from examples/templates. Ignore placeholders containing variables such as `{relative-path}`.
- Treat subagent audit summaries as provisional. Read the generated report, inspect every changed file, and independently rerun the full-library validator before reporting success.
- For bulk hygiene runs, trust only the post-fix rescan. If the checker itself was missing or stale, repair that helper first, rerun the audit, and use the new report as the source of truth.
- When normalizing weak openers, strip accidental file-name prefixes before prepending the skill name, and leave already-valid descriptions alone. A fix that compounds a bad prefix is worse than the original smell.
- After deleting snapshot caches or regenerating generated indexes, verify the file state explicitly instead of assuming the command did it.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [AtlasOmnia](https://github.com/AtlasOmnia)
- **Source:** [AtlasOmnia/donna-starter](https://github.com/AtlasOmnia/donna-starter)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-atlasomnia-donna-starter-skill-auditor
- Seller: https://agentstack.voostack.com/s/atlasomnia
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.