# 📊 Skill Classification and Metadata

> **The local classifier that scores every skill during validation and build, generating machine-readable profiles for the entire catalog.**

---

## 📊 Status

| Output | Generated |
|:-------|:----------|
| ✅ Root `metadata.json` | Repository-wide summary |
| ✅ Per-skill `skills/<skill>/metadata.json` | Individual classifications |
| ✅ Catalog `dist/catalog.json` | Published catalog with scores |
| ✅ Manifests `dist/manifests/<skill>.json` | Per-skill machine-readable data |

Generated by: `python3 tools/scripts/validate_skills.py`

Current repository snapshot:

- 48 published native skills, with 32 curated English derivatives maintained separately in `skills_omni/`
- average quality score `87.5`
- average best-practices score `85.2`
- average security score `90.6`
- validation mix `40` passed, `8` warn, `0` failed
- current quality spread `37` to `100`
- current best-practices spread `7` to `100`

---

## 🎯 Purpose

The classifier gives every skill a **consistent machine-readable profile** before it reaches the catalog. It performs four jobs:

1. 📋 **Parse** — YAML frontmatter and markdown body
2. 🏷️ **Normalize** — Category labels to canonical taxonomy
3. 📊 **Classify** — Maturity, best practices, quality, and security scoring
4. 📁 **Emit** — Metadata artifacts consumed by build scripts, docs, and CI

---

## 🏷️ Canonical Taxonomy

**18 canonical categories** with automatic alias mapping:

| Category | Domain | Common Aliases |
|:---------|:-------|:---------------|
| 💻 `development` | General software dev | `coding`, `programming` |
| 🎨 `frontend` | Frontend & UI | `ui`, `web-design` |
| 🔧 `backend` | Backend & APIs | `server`, `api` |
| 🌐 `fullstack-web` | End-to-end web | `web`, `full-stack` |
| 🛠️ `tools` | Developer tooling | `utilities` |
| ⚙️ `cli-automation` | CLI & automation | `scripting`, `workflow` |
| 📊 `business` | Business strategy | `strategy` |
| 📐 `product` | Product management | `pm` |
| 🎯 `design` | Visual & UX design | `ux` |
| 🤖 `data-ai` | Data & AI apps | `data`, `analytics` |
| 🧠 `ai-agents` | AI agent patterns | `agents` |
| 📈 `machine-learning` | ML models & training | `ml` |
| 🔌 `devops` | Infrastructure | `infrastructure`, `cloud` |
| 🛡️ `testing-security` | Testing & security | `testing`, `security`, `qa` |
| 📖 `documentation` | Doc management | `docs` |
| 🎬 `content-media` | Content creation | `media`, `content` |
| 💬 `communication` | Communication tools | `chat` |
| ❓ `uncategorized` | Default fallback | — |

> Legacy labels like `workflow`, `architecture`, `infrastructure` are automatically normalized through the alias mapping.

---

## 📏 Computed Attributes

### 🎯 Maturity Levels

| Level | Label | Criteria |
|:------|:------|:---------|
| **L1** | `metadata` | Frontmatter plus minimal body |
| **L2** | `instructions` | Substantial written instructions |
| **L3** | `resources` | Bundled scripts or richer packaged resources |

Additional signals tracked: `has_scripts`, `has_extra_files`

---

### 📋 Best Practices Score (0-100)

The heuristic evaluates:

| Signal | What It Checks |
|:-------|:---------------|
| 📛 Slug quality | `name` field formatting |
| 📝 Description | Clarity, length, informativeness |
| 📐 Structure | Document sections and hierarchy |
| 💡 Examples | Code fences and example blocks |
| 🔗 References | Linked local `references/`, `scripts/`, and support-pack helpers |
| 🧰 Operability | Runnable local script examples and concrete workflow snippets |
| 🧩 Support-pack depth | Multiple support families, reusable files, agent metadata, and operational assets |
| 🩺 Troubleshooting | Explicit `Symptoms` and `Solution` pairs |
| 📚 Coverage | `When to Use`, `Best Practices`, `Troubleshooting`, and `Additional Resources` sections |
| 🌐 Portability | Tool-agnostic wording |
| 📅 Freshness | Avoidance of hardcoded dates |

**Current tiering**

| Tier | Score Range |
|:-----|:-----------|
| `excellent` | 90-100 |
| `good` | 70-89 |
| `fair` | 50-69 |
| `needs-work` | 0-49 |

The scorer is intentionally **semantic enough to create spread** across mature skills. A skill with clean structure can score well, but to reach the top band it also needs depth signals such as:

- multiple examples, not just one
- multiple troubleshooting cases
- related skill guidance
- richer local support packs
- more than one support family beyond plain prose, ideally including `agents/` or `assets/` where they add real reuse
- a dedicated `## Workflow` section with countable steps
- at least one small operational table or decision map when it improves execution clarity
- more operational specificity than a plain template
- clearer workflow depth and decision support assets
- support-pack depth that goes beyond one `references/` file and one linked script
- enough reusable support files to feel like a workflow kit, not a single-note add-on
- enough operational density to separate a polished outline from a reusable workflow kit

That means a structurally complete skill can still land in the high 90s instead of `100` if its support pack is narrower, its decision assets are thinner, or its operational density is lower than the strongest skills in the catalog.

---

### ⭐ Quality Score (0-100)

The heuristic combines:

| Signal | Weight |
|:-------|:-------|
| 📝 Body completeness | Medium-high |
| 📋 Description precision | Medium |
| 📊 Metadata completeness | Medium |
| 📅 Recency (`date_updated`) | Medium |
| 📦 Packaged resources | Medium |
| 📋 Best practices contribution | Medium |
| 🧠 Semantic depth | Medium-high |
| 🛠️ Operational depth | Medium |
| 📚 Support-pack richness | Medium |

**Quality tiers:**

| Tier | Score Range |
|:-----|:-----------|
| 💎 `platinum` | 80+ |
| 🥇 `gold` | 65-79 |
| 🥈 `silver` | 50-64 |
| 🥉 `bronze` | 35-49 |
| 🌱 `starter` | 0-34 |

---

### 🛡️ Security Score (0-100)

The security layer combines:

| Scanner | Always Enabled | What It Does |
|:--------|:---------------|:-------------|
| 🔍 **Static** | ✅ Yes | Scans SKILL.md, packaged files, and scripts |
| 🦠 **ClamAV** | ⚙️ Optional | Malware scanning via `clamscan` |
| 🔒 **VirusTotal** | ⚙️ Optional | Hash lookup (no upload) |

**Static scanner rule families:**
- 🎭 Prompt injection and exfiltration patterns
- 💣 Destructive shell commands
- 🔑 Suspicious credential or OS paths
- ⚠️ Risky script primitives (`shell=True`, `pickle.load`, `eval`, `extractall`)

**Security output shape:**

```json
{
  "score": 100,
  "tier": "hardened",
  "status": "passed",
  "findings_count": 0,
  "findings": [],
  "signals": { "scanned_files": 3 },
  "scanners": {
    "static": { "enabled": true, "status": "completed" },
    "clamav": { "enabled": false, "status": "disabled" },
    "virustotal": { "enabled": false, "status": "disabled" }
  }
}
```

---

## 📁 Generated Metadata Shape

### Per-Skill (`skills/<skill>/metadata.json`)

| Section | Fields |
|:--------|:-------|
| 🆔 Identity | `id`, `slug`, `display_name` |
| 🏷️ Taxonomy | `raw_category`, `canonical_category`, `inferred_category` |
| 📋 Authoring | tags, tools, complexity, risk, source, author |
| 📅 Dates & paths | `date_added`, `date_updated`, paths |
| 📊 Resources | File and reference counters |
| 📝 Content signals | Word count, body length, structural flags |
| 🧠 Semantic depth | Workflow steps, examples, troubleshooting depth, decision assets, support-link families |
| 🧩 Support-pack structure | Support-file counts, linked families, `agents/`, `assets/`, and reusable examples |
| 🎯 Maturity | Level, label, scripts/files flags |
| 📋 Best practices | Score and tier |
| ⭐ Quality | Score, tier, and semantic breakdown |
| 🛡️ Security | Score, tier, status, findings |
| ✅ Validation | Status, errors, warnings |

### Root (`metadata.json`)

| Section | Fields |
|:--------|:-------|
| 📊 Summary | Counts, averages, category distribution |
| 🏷️ Taxonomy | Category counts |
| 🎯 Distribution | Skill level, quality tier, security tier |
| ✅ Validation | Status counts |
| 📋 Skills list | Compact per-skill summaries |

---

## ⚙️ Workflow Integration

```bash
npm run validate              # Validate + regenerate metadata
npm run build                 # Full build with catalog + archives
npm run taxonomy:report       # Show category drift suggestions
```

### 🪝 Optional Git Hooks

```bash
npm run hooks:install
```

This configures `git` to use `.githooks/pre-commit`, which regenerates metadata and catalog artifacts before commit and stages the generated files automatically.