skill-catalog-curator

Files (9)

• SKILL.md
• openai.yaml · agents/
• sensei-compatibility.md · references/
• audit_skill_frontmatter.py · scripts/
• check_external_auditors.py · scripts/
• generate_trigger_tests.py · scripts/
• scan_skill_catalog.py · scripts/
• security_admission_pipeline.py · scripts/
• security_scan_skill.py · scripts/

SKILL.md (first lines)

# Skill Catalog Curator

Use this skill for read-only skill catalog hygiene. It reports problems; it does not remove, rename, install, update, or overwrite skills.

## Default Workflow

1. Inspect the requested roots. If none are specified, include existing roots from:
   - `~/.agents/skills`
   - `~/.codex/skills`
   - `~/TheAngrySkills/skills`
2. Run the scanner:

```bash
python3 <this-skill>/scripts/scan_skill_catalog.py
```

3. For Sensei-style frontmatter/routing quality on one skill or a repo:

```bash
python3 <this-skill>/scripts/audit_skill_frontmatter.py <skill-or-root>
python3 <this-skill>/scripts/audit_skill_frontmatter.py <skill-or-root> --profile shared
python3 <this-skill>/scripts/audit_skill_frontmatter.py <skill-or-root> --profile codex
python3 <this-skill>/scripts/audit_skill_frontmatter.py <skill-or-root> --profile agentskills
python3 <this-skill>/scripts/audit_skill_frontmatter.py <skill-or-root> --json
```

4. For Waza-style trigger fixtures, generate prompts from explicit `WHEN:` or
   `USE FOR:` phrases:

```bash
python3 <this-skill>/scripts/generate_trigger_tests.py <skill-dir>
python3 <this-skill>/scripts/generate_trigger_tests.py <skill-dir> --write tests
```

These fixtures test expected trigger intent. They do not prove that Codex chose
the skill in a live session.

5. Review findings by severity:
   - `error`: likely broken skill discovery or real local-vs-remote drift.
   - `warning`: likely stale metadata, placeholder text, or duplicated catalog entry.
   - `info`: useful inventory or optional cleanup candidate.
6. Before destructive cleanup, ask the user to approve exact paths and actions.

## Scanner

Use `scripts/scan_skill_catalog.py` for deterministic checks.

Common commands:

```bash
python3 scripts/scan_skill_catalog.py
python3 scripts/scan_skill_catalog.py --root ~/.agents/skills --root ~/TheAngrySkills/skills
python3 scripts/scan_skill_catalog.py --json
```

The scanner checks:

- duplicate frontmatter `name` values across roots
- duplicate folder names across roots
- folder name versus frontmatter name mismatch
- installed/local copy drift for same folder names by directory hash
- missing `agents/openai.yaml`
- `agents/openai.yaml` default prompt that does not mention `$skill-name`
- placeholder/TODO template residue
- short or generic descriptions

## Frontmatter Auditor

Use `scripts/audit_skill_frontmatter.py` when the question is whether a skill
will route well, trigger clearly, stay compact, avoid publishing local machine
metadata, and avoid no-op instruction text. The default profile is `shared`,
for the mixed team/session environment rather than only Codex Desktop.

It checks:

- frontmatter parseability as real YAML, not loose key/value text
- `name` validity and folder-name match
- description length, word count, and trigger language
- extra frontmatter fields
- oversized `SKILL.md`
- missing `agents/openai.yaml`
- local filesystem paths in `SKILL.md` and references
- possible no-op instruction lines such as "be thorough", "make it easy to
  read", or "follow best practices" when they are not tied to an observable
  constraint

No-op findings are informational. They identify cleanup candidates, not proven
bugs. Keep a line if it changes behavior through a concrete constraint, exact
output requirement, path, command, threshold, or routing rule.

This is a Codex/TheAngryPit-specific audit. Do not automatically copy external
spec recommendations such as `license` or `metadata.version` into Codex skills
unless the repo intentionally adopts those fields.

Profiles:

- `shared`: default. Allows metadata used across team sessions while still
  warning on weak routing and local path leaks.
- `codex`: stricter Codex-style frontmatter posture.
- `agentskills`: adds Sensei/agentskills-style hints such as license/version
  recommendations and explicit `WHEN:`/`USE FOR:` trigger checks.

For the policy on what to adopt from Sensei and what to reject, read
`references/sensei-compatibility.md`.

## Trigger Test Fixtures

Use `scripts/generate_trigger_tests.py` to create Waza-compatible
`trigger_tests.yaml` fixtures from a skill's frontmatter. It prefers explicit
quoted phrases in `WHEN:` or `USE FOR:` and falls back to description clauses
when needed.

Common commands:

```bash
python3 scripts/generate_trigger_tests.py skills/core/skill-catalog-curator
python3 scripts/generate_trigger_tests.py skills/core/skill-catalog-curator --write tests
```

From TheAngryPit/TheAngrySkills, MIT.

More from TheAngryPit/TheAngrySkills