tessleng/skill-insights
Scan a directory or workspace for SKILL.md files across all agents and repos, capture supporting files (references, scripts, linked docs), dedupe vendored copies, enrich each Tessl tile with registry signals, and emit a canonical JSON inventory validated by JSON Schema. Then run four analytical phases in parallel against the inventory — staleness + git provenance (history, broken refs, contributors), quality (Tessl `skill review`), duplicates (similarity + LLM judgement), registry-search (per-standalone-skill registry suggestions, HTTP only) — and render a self-contained interactive HTML report with a top-of-report health overview, top-issues panel, recently-changed list, and per-tessl.json manifests view.
84
1.44x
Quality
90%
Does it follow best practices?
Impact
97%
1.44xAverage score across 2 eval scenarios
Securityby
Advisory
Suggest reviewing before use
org-usage.schema.jsonreferences/schemas/
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://tessl.io/skill-insights/org-usage.schema.json",
"title": "Skill Insights — Org-wide Usage Output",
"description": "Org-wide skill / MCP / session usage produced by posthog-skill-query, optionally scoped by a (repo prefix OR person email domain) filter. Designed as raw input for downstream cross-reference and rendering — no judgement or derived buckets are encoded here.",
"type": "object",
"additionalProperties": false,
"required": [
"schema_version",
"fetched_at",
"source",
"windows",
"primary_window_days",
"top_tiles_detail",
"top_untiled",
"top_loaded",
"top_repos",
"tool_version",
"filter",
"totals",
"tiles",
"skills",
"untiled_skills",
"loaded_skills",
"mcp_tools",
"session_aggregates",
"repos",
"tiles_by_repo",
"skills_by_repo",
"untiled_skills_by_repo",
"mcp_tools_by_repo",
"session_aggregates_by_repo"
],
"properties": {
"schema_version": { "type": "string", "const": "1.4" },
"fetched_at": { "type": "string", "format": "date-time" },
"source": {
"type": "object",
"additionalProperties": false,
"required": ["kind", "host", "project_id"],
"properties": {
"kind": { "type": "string", "const": "posthog" },
"host": { "type": "string", "format": "uri" },
"project_id": { "type": "integer", "minimum": 1 },
"dashboard_id_for_reference": { "type": ["integer", "null"] }
}
},
"windows": {
"type": "array",
"items": { "type": "integer", "minimum": 1 },
"minItems": 1
},
"primary_window_days": { "type": "integer", "minimum": 1 },
"top_tiles_detail": { "type": "integer", "minimum": 0 },
"top_untiled": { "type": "integer", "minimum": 0 },
"top_loaded": { "type": "integer", "minimum": 0 },
"top_repos": {
"type": "integer",
"minimum": 0,
"description": "Cap on the number of distinct repos retained in `repos[]` and `*_by_repo[]` arrays per query. Repos beyond this cap (sorted by primary-window activations) are dropped from the per-repo views; their events still contribute to top-line `totals` and the all-repos aggregates."
},
"tool_version": { "type": "string" },
"filter": {
"type": "object",
"description": "Combined (repo prefix OR email domain) filter applied to all event queries. An event passes the filter if EITHER the repo half matches OR the email half matches. Both halves are independently optional. When both `repos` and `email_domains` are empty, no filter is applied and every event in the project is included.",
"additionalProperties": false,
"required": ["repos", "email_domains", "match_kind", "events_per_window"],
"properties": {
"repos": {
"type": "array",
"description": "Prefix-allowlist matched against `properties.gitRepo` (and `properties.sessionGitRepo` for session-processed events). Each prefix matches as exact-equal OR `prefix/`-prefixed.",
"items": { "type": "string", "minLength": 1 }
},
"email_domains": {
"type": "array",
"description": "Suffix-allowlist matched against `person.properties.email` as `%@<domain>`.",
"items": { "type": "string", "minLength": 1 }
},
"match_kind": { "type": "string", "const": "prefix-or-email-domain" },
"events_per_window": {
"type": "object",
"description": "Per-window counts of how the filter selected events. Keyed by window name (e.g. `30d`).",
"additionalProperties": { "$ref": "#/$defs/FilterWindowCounts" }
}
}
},
"totals": {
"type": "object",
"description": "Top-line counts per window keyed by '<N>d'.",
"additionalProperties": { "$ref": "#/$defs/WindowTotals" }
},
"tiles": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": ["tile", "windows"],
"properties": {
"tile": { "type": "string", "minLength": 1 },
"windows": {
"type": "object",
"additionalProperties": { "$ref": "#/$defs/TileWindowCounts" }
}
}
}
},
"skills": {
"type": "array",
"description": "Per-(tile, name) detail. Only populated for the top N tiles by primary-window activations to keep the query budget bounded.",
"items": {
"type": "object",
"additionalProperties": false,
"required": ["tile", "name", "windows", "providers", "first_seen", "last_seen"],
"properties": {
"tile": { "type": "string", "minLength": 1 },
"name": { "type": "string", "minLength": 1 },
"windows": {
"type": "object",
"additionalProperties": { "$ref": "#/$defs/SkillWindowCounts" }
},
"providers": {
"type": "object",
"description": "Per-provider activation counts in the primary window.",
"additionalProperties": { "type": "integer", "minimum": 0 }
},
"first_seen": { "type": ["string", "null"] },
"last_seen": { "type": ["string", "null"] }
}
}
},
"untiled_skills": {
"type": "array",
"description": "Skills with empty skillTile (third-party, private SKILL.md). No tile attribution available — cross-reference can only match by name.",
"items": {
"type": "object",
"additionalProperties": false,
"required": ["name", "windows"],
"properties": {
"name": { "type": "string", "minLength": 1 },
"windows": {
"type": "object",
"additionalProperties": { "$ref": "#/$defs/UntiledSkillWindowCounts" }
}
}
}
},
"loaded_skills": {
"type": "array",
"description": "Per-(tile, name, scope) install footprint, derived from the installedSkills array carried on every skill-activation event. Tells you who has the skill *available* in their catalogue, independent of whether they ever activated it. NOTE: only captures skills that were installed at the time *some* skill-activation event fired in a session — users with zero activation events in the window contribute no loaded-skill rows.",
"items": {
"type": "object",
"additionalProperties": false,
"required": ["tile", "name", "scope", "windows"],
"properties": {
"tile": { "type": ["string", "null"] },
"name": { "type": "string", "minLength": 1 },
"scope": { "type": ["string", "null"], "enum": ["project", "global", null] },
"windows": {
"type": "object",
"additionalProperties": { "$ref": "#/$defs/LoadedWindowCounts" }
}
}
}
},
"mcp_tools": {
"type": "array",
"description": "Tessl MCP tool activations (mcp__tessl__*).",
"items": {
"type": "object",
"additionalProperties": false,
"required": ["tool", "windows"],
"properties": {
"tool": { "type": "string", "minLength": 1 },
"windows": {
"type": "object",
"additionalProperties": { "$ref": "#/$defs/McpWindowCounts" }
}
}
}
},
"session_aggregates": {
"type": "object",
"description": "Aggregates from cli:agent-signals:session-processed events, per window.",
"additionalProperties": { "$ref": "#/$defs/SessionAggregate" }
},
"repos": {
"type": "array",
"description": "Per-repo top-line totals. One row per distinct `properties.gitRepo` (events with no gitRepo are excluded — their volume is reported via `filter.events_per_window.*.events_no_gitrepo`). Sorted by primary-window activations, capped at `top_repos`.",
"items": {
"type": "object",
"additionalProperties": false,
"required": ["repo", "windows"],
"properties": {
"repo": { "type": "string", "minLength": 1 },
"windows": {
"type": "object",
"additionalProperties": { "$ref": "#/$defs/WindowTotals" }
}
}
}
},
"tiles_by_repo": {
"type": "array",
"description": "Per-(tile, repo) rollup of skill activations. Same shape as `tiles[]` plus a `repo` discriminator. Used by the renderer to re-aggregate when a repo filter is active client-side.",
"items": {
"type": "object",
"additionalProperties": false,
"required": ["tile", "repo", "windows"],
"properties": {
"tile": { "type": "string", "minLength": 1 },
"repo": { "type": "string", "minLength": 1 },
"windows": {
"type": "object",
"additionalProperties": { "$ref": "#/$defs/TileWindowCounts" }
}
}
}
},
"skills_by_repo": {
"type": "array",
"description": "Per-(tile, name, repo) rollup. Mirrors `skills[]` but with a `repo` discriminator. Only populated for the same top N tiles as `skills[]`.",
"items": {
"type": "object",
"additionalProperties": false,
"required": ["tile", "name", "repo", "windows"],
"properties": {
"tile": { "type": "string", "minLength": 1 },
"name": { "type": "string", "minLength": 1 },
"repo": { "type": "string", "minLength": 1 },
"windows": {
"type": "object",
"additionalProperties": { "$ref": "#/$defs/SkillWindowCounts" }
}
}
}
},
"untiled_skills_by_repo": {
"type": "array",
"description": "Per-(name, repo) rollup of untiled-skill activations. Mirrors `untiled_skills[]` with a `repo` discriminator.",
"items": {
"type": "object",
"additionalProperties": false,
"required": ["name", "repo", "windows"],
"properties": {
"name": { "type": "string", "minLength": 1 },
"repo": { "type": "string", "minLength": 1 },
"windows": {
"type": "object",
"additionalProperties": { "$ref": "#/$defs/UntiledSkillWindowCounts" }
}
}
}
},
"mcp_tools_by_repo": {
"type": "array",
"description": "Per-(tool, repo) rollup of `mcp__tessl__*` invocations. Mirrors `mcp_tools[]` with a `repo` discriminator.",
"items": {
"type": "object",
"additionalProperties": false,
"required": ["tool", "repo", "windows"],
"properties": {
"tool": { "type": "string", "minLength": 1 },
"repo": { "type": "string", "minLength": 1 },
"windows": {
"type": "object",
"additionalProperties": { "$ref": "#/$defs/McpWindowCounts" }
}
}
}
},
"session_aggregates_by_repo": {
"type": "object",
"description": "Per-window per-repo session aggregates. Keyed by window name (e.g. `30d`); each value is an array of per-repo `SessionAggregate` rows. Repo here is `properties.sessionGitRepo` from `cli:agent-signals:session-processed` events; events with no sessionGitRepo are excluded.",
"additionalProperties": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": ["repo", "sessions", "users", "messages", "tool_calls", "skill_calls", "tessl_skill_calls", "tessl_mcp_calls", "tessl_cli_calls"],
"properties": {
"repo": { "type": "string", "minLength": 1 },
"sessions": { "type": "integer", "minimum": 0 },
"users": { "type": "integer", "minimum": 0 },
"messages": { "type": "integer", "minimum": 0 },
"tool_calls": { "type": "integer", "minimum": 0 },
"skill_calls": { "type": "integer", "minimum": 0 },
"tessl_skill_calls": { "type": "integer", "minimum": 0 },
"tessl_mcp_calls": { "type": "integer", "minimum": 0 },
"tessl_cli_calls": { "type": "integer", "minimum": 0 }
}
}
}
}
},
"$defs": {
"FilterWindowCounts": {
"type": "object",
"additionalProperties": false,
"required": [
"events_total",
"events_no_gitrepo",
"events_with_gitrepo",
"events_matched_filter",
"events_matched_by_repo",
"events_matched_by_email",
"events_excluded_by_filter"
],
"properties": {
"events_total": { "type": "integer", "minimum": 0, "description": "All cli:agent-signals:skill-activation events in the window, ignoring filter." },
"events_no_gitrepo": { "type": "integer", "minimum": 0, "description": "Events whose properties.gitRepo was null — impossible to attribute to any repo." },
"events_with_gitrepo": { "type": "integer", "minimum": 0, "description": "Events with a non-null properties.gitRepo." },
"events_matched_filter": { "type": "integer", "minimum": 0, "description": "Events that matched the combined (repo OR email) filter — i.e. selected events." },
"events_matched_by_repo": { "type": "integer", "minimum": 0, "description": "Subset of `events_matched_filter` whose `properties.gitRepo` matched a configured prefix. Zero when no repo filter is configured. Can overlap with `events_matched_by_email`." },
"events_matched_by_email": { "type": "integer", "minimum": 0, "description": "Subset of `events_matched_filter` whose `person.properties.email` matched a configured domain. Zero when no email filter is configured. Can overlap with `events_matched_by_repo`." },
"events_excluded_by_filter": { "type": "integer", "minimum": 0, "description": "events_total - events_matched_filter when any filter is configured; zero otherwise." }
}
},
"WindowTotals": {
"type": "object",
"additionalProperties": false,
"required": [
"activations",
"users",
"sessions",
"tiled_activations",
"untiled_activations",
"providers"
],
"properties": {
"activations": { "type": "integer", "minimum": 0 },
"users": { "type": "integer", "minimum": 0 },
"sessions": { "type": "integer", "minimum": 0 },
"tiled_activations": { "type": "integer", "minimum": 0 },
"untiled_activations": { "type": "integer", "minimum": 0 },
"providers": {
"type": "object",
"additionalProperties": {
"type": "object",
"additionalProperties": false,
"required": ["activations", "users"],
"properties": {
"activations": { "type": "integer", "minimum": 0 },
"users": { "type": "integer", "minimum": 0 }
}
}
}
}
},
"TileWindowCounts": {
"type": "object",
"additionalProperties": false,
"required": ["activations", "users", "sessions"],
"properties": {
"activations": { "type": "integer", "minimum": 0 },
"users": { "type": "integer", "minimum": 0 },
"sessions": { "type": "integer", "minimum": 0 }
}
},
"SkillWindowCounts": {
"type": "object",
"additionalProperties": false,
"required": ["activations", "users", "sessions"],
"properties": {
"activations": { "type": "integer", "minimum": 0 },
"users": { "type": "integer", "minimum": 0 },
"sessions": { "type": "integer", "minimum": 0 }
}
},
"UntiledSkillWindowCounts": {
"type": "object",
"additionalProperties": false,
"required": ["activations", "users"],
"properties": {
"activations": { "type": "integer", "minimum": 0 },
"users": { "type": "integer", "minimum": 0 }
}
},
"LoadedWindowCounts": {
"type": "object",
"additionalProperties": false,
"required": ["users"],
"properties": {
"users": { "type": "integer", "minimum": 0 }
}
},
"McpWindowCounts": {
"type": "object",
"additionalProperties": false,
"required": ["activations", "users", "sessions"],
"properties": {
"activations": { "type": "integer", "minimum": 0 },
"users": { "type": "integer", "minimum": 0 },
"sessions": { "type": "integer", "minimum": 0 }
}
},
"SessionAggregate": {
"type": "object",
"additionalProperties": false,
"required": [
"sessions",
"users",
"messages",
"tool_calls",
"skill_calls",
"tessl_skill_calls",
"tessl_mcp_calls",
"tessl_cli_calls"
],
"properties": {
"sessions": { "type": "integer", "minimum": 0 },
"users": { "type": "integer", "minimum": 0 },
"messages": { "type": "integer", "minimum": 0 },
"tool_calls": { "type": "integer", "minimum": 0 },
"skill_calls": { "type": "integer", "minimum": 0 },
"tessl_skill_calls": { "type": "integer", "minimum": 0 },
"tessl_mcp_calls": { "type": "integer", "minimum": 0 },
"tessl_cli_calls": { "type": "integer", "minimum": 0 }
}
}
}
}