Address skill-inventory findings

A skill-inventory scan analyzes the skills across a workspace's repos and produces findings. Each finding is a specific, actionable observation about a skill instance, a logical skill, or a repo.

A finding has:

• archetype: what kind of issue it is (see remediation below).
• priority: critical, high, medium, or low.
• status: active (needs attention) or resolved.
• title / description: what was observed.
• gated: when true, detail is withheld (the workspace plan lacks the entitlement); only the finding type and impacted repos/skills are present.

The findings endpoint resolves each finding's evidence inline, so the artifacts arrive on the response itself. There is no separate evidence id list to resolve. Read whichever of these fields the finding populates:

• logicalSkill: the logical (registry) skill the finding concerns, with name, canonicalRepo, category, body, frontmatter, and registry coordinates (or null).
• skillInstance: the concrete skill installed or vendored in a repo, with path, body, frontmatter, frontmatterError, and repo details (or null).
• clusterMembers: for overlap, the set of logical skills that cover the same purpose.
• instances: the concrete skill instances the finding impacts, with repo and path metadata.

Discovering and calling the API

All raw API mechanics (endpoint paths, query params, response shapes) live in the tessl/api skill. Never restate endpoint schemas or read openapi.json here.

tessl/api is a separate plugin this skill depends on. If it is not available, install it first with tessl install tessl/api, then proceed.

• Use tessl/api search to find the right endpoint for a task, and show to inspect its params and response.
• Call the endpoint with tessl api …, which handles auth and headers.

Workflow

1. Identify the workspace and inventory. Determine the workspace name and the skill-inventory id for the current repo. Use tessl/api search/show to find the inventory-listing and inventory-header endpoints, call them via tessl api, and match the inventory to this repo.
2. Fetch active findings. Use tessl/api search/show to inspect the findings endpoint, then call it via tessl api with status=active. Work through findings in priority order, highest first: critical, then high, then medium, then low (the endpoint's default -priority sort returns them in that order). Follow pagination until the pages are exhausted so no findings are missed.
3. Read the resolved evidence before fixing. Each finding already carries its artifacts inline (logicalSkill, skillInstance, clusterMembers, instances). Ground the fix in that actual state (the returned body, frontmatter, and path), not the finding title, then locate those skill files in this repo.
4. Re-fetch to confirm findings move to resolved after remediation.

Remediation by archetype

For each archetype, read the resolved fields it populates, then apply the fix.

• registry-match: a local skill matches one already in the registry. Compare skillInstance against logicalSkill to confirm the content matches. Replace the local copy with the registry plugin via tessl install.
• drift: an installed skill has diverged from its published source. Diff skillInstance against logicalSkill to see exactly what diverged. Re-sync with tessl update if the registry is canonical, or republish if the local edits are intended.
• overlap: two or more skills cover the same purpose. Compare the clusterMembers (and their instances) to decide which is canonical. Consolidate into one; merge or remove the duplicates.
• publishable: a useful local skill is not yet shared. Inspect skillInstance to confirm it is registry-ready (clear frontmatter, no repo-specific assumptions). Publish with tessl skill publish.
• frontmatter-error: a SKILL.md has invalid or missing frontmatter. Read skillInstance.frontmatterError and frontmatter to see which field is malformed or missing. Fix name/description and required fields so it parses.
• untracked: a skill exists on disk but is not declared in tessl.json. Use skillInstance to locate the skill in the repo and confirm it is real. Add it to the manifest so it is managed.
• unmanaged: a skill is referenced but not installed or vendored. Use logicalSkill and instances to see what is referenced and where it is missing. Install or vendor it so it resolves.
• skill-overload: a repo carries too many skills for an agent to use effectively. Review the repo's instances to see the full set. Prune, merge, or split skills to reduce the count.