PaperlayerView exact revision on arXiv

Source-linked AI summary

Skilldex: A Package Manager and Registry for Agent Skill Packages with Hierarchical Scope-Based Distribution

Sampriti Saha, Pranav Hemanth

arXiv:2604.16911v1cs.AI

TL;DR

Agent skill tooling lacks both specification-grounded conformance signals and a way to bundle related skills with shared context. Skilldex addresses these gaps with compiler-style scoring and shared-asset skillsets, supported by scoped distribution and registry infrastructure. Its principal scope is bounded by the inability of format scoring to measure semantic description quality.

  • Problem

    Existing skill tooling does not score packages against Anthropic’s format specification or bundle related skills with shared context for coherence.

    Source: §I · p. 1

  • Method

    Skilldex combines compiler-style format scoring with skillsets that bundle related skills and shared vocabulary, templates, and persona assets.

    Source: B. Shared Assets: Cross-Skill… · pp. 6–7

  • Results

    Skilldex provides actionable line-level conformance feedback and shared assets that keep related skill outputs mutually coherent.

    Source: B. Shared Assets: Cross-Skill… · p. 7, §XIII · p. 9

  • Takeaways & Limitations

    A complete developer or research agent configuration becomes a first-class publishable artifact through the skillset abstraction.

    Source: §XIII · p. 9

    Conformance scoring cannot determine whether a description is specific enough to trigger reliably in context.

    Source: §XII · p. 9

Abstract

from arXiv · show

Large Language Model (LLM) agents are increasingly extended at runtime via skill packages, structured natural-language instruction bundles loaded from a well-known directory. Community install tooling and registries exist, but two gaps persist: no public tool scores skill packages against Anthropic's published format specification, and no mechanism bundles related skills with the shared context they need to remain mutually coherent. We present Skilldex, a package manager and registry for agent skill packages addressing both gaps. The two novel contributions are: (1) compiler-style format conformance scoring against Anthropic's skill specification, producing line-level diagnostics on description specificity, frontmatter validity, and structural adherence; and (2) the skillset abstraction, a bundled collection of related skills with shared assets (vocabulary files, templates, reference documents) that enforce cross-skill behavioral coherence. Skilldex also provides supporting infrastructure: a three-tier hierarchical scope system, a human-in-the-loop agent suggestion loop, a metadata-only community registry, and a Model Context Protocol (MCP) server. The system is implemented as a TypeScript CLI (skillpm / spm) with a Hono/Supabase registry backend, and is open-source.

I. INTRODUCTION

Skilldex addresses two gaps in agent-skill distribution: missing specification-grounded conformance signals and missing bundles for keeping related skills coherent. It introduces format scoring and skillsets alongside hierarchical scopes, agent suggestions, and registry infrastructure.

A. Agent Skill Packages

  • Skills are SKILL.md-based directories containing YAML frontmatter and Markdown instructions, with optional scripts, references, and assets.The format is used by agents that load skills from well-known directories as prompting context during task execution.Source: §I · p. 1, A. Agent Skill Packages · p. 2

I. INTRODUCTION

  • Skilldex identifies missing conformance scoring and missing skillset coherence as the two central gaps in existing skill tooling.Existing tools provide installation and registry functions, but do not score skills against Anthropic’s format specification or bundle related skills with shared context.Source: §I · p. 1
  • Format conformance scoring produces a 0–100 score with compiler-style line-level diagnostics against Anthropic’s skill format specification.The system targets description specificity, frontmatter validity, and structural adherence rather than relying on install counts or publisher badges.Source: §I · p. 1
  • Skillsets bundle related skills with shared convention files, templates, and persona definitions so their outputs remain mutually coherent.The abstraction makes related skills reference common assets instead of relying on independently installed, potentially divergent conventions.Source: §I · p. 1
  • Skilldex adds global, shared, and project scopes with local-first behavior to manage context across installation levels.The supporting infrastructure also includes a human-reviewed agent suggestion loop and a metadata-only community registry.Source: §I · p. 1

B. Package Management Systems

Skilldex combines conventional package-management operations with agent-specific interfaces and hierarchical installation scopes. Its architecture separates CLI, MCP, registry, and web components while addressing context growth and competing skill definitions.

B. Package Management Systems

C. MCP and Agent Tool Extension

  • The MCP server exposes installation, listing, validation, search, suggestion, and removal as callable tools for agents.This allows agents to manage their skill environment mid-session without terminal interaction.Source: C. MCP and Agent Tool Extension · p. 2

D. Related Systems

  • Skilldex differs from existing skill and MCP registries by combining scoped installation, format scoring, and skillset bundling.Anthropic’s directory supplies a seeding source, while other community efforts provide installation or basic validation without the full combination.Source: D. Related Systems · p. 2

III. SYSTEM ARCHITECTURE

  • The system has separate TypeScript CLI, Hono/Supabase registry, and Next.js web components, with CLI and MCP sharing core modules.The registry stores metadata and handles search and install-count tracking, while both interfaces invoke common installation and validation logic.Source: §III · p. 2, Figure 1 · p. 3, B. Three-Tier Hierarchy · p. 3

A. Motivation

  • Loading every installed skill into every session increases context consumption and leaves name collisions without a principled resolution strategy.These pressures motivate scoped installation and precedence rules.Source: A. Motivation · p. 2

B. Three-Tier Hierarchy

  • Skills can be installed globally, across opted-in shared projects, or within a single project, each with its own manifest and skills directory.The manifest records installed skills and skillsets alongside source URLs, scores, timestamps, and scope-specific schema fields.Source: B. Three-Tier Hierarchy · pp. 2–3

C. Resolution Rules

Skilldex resolves skills across explicit scopes using local-first precedence and supports registry, Git, and local installation sources. It detects cross-scope duplicates without blocking installation.

C. Resolution Rules

  • Lower scopes override higher scopes for the same skill name, allowing project-specific customization without modifying shared or global installations.The resolver materializes all three scope configurations for cross-scope conflict detection.Source: C. Resolution Rules · p. 3
  • Each scope configuration records its level, root, manifest, skills directory, and skillsets directory.The resolver maps scope levels to these concrete filesystem locations.Source: C. Resolution Rules · p. 3

D. Installation Sources

  • Installation accepts registry names, Git URLs, and local paths, then converges on one validation, copy, and atomic manifest-update path.Git sources support branches and subpaths, while registry names resolve to source URLs before installation.Source: D. Installation Sources · p. 3

E. Cross-Scope Conflict Detection

  • When a skill exists at another scope, the installer emits an informational warning but does not block installation.This preserves the system’s principle that warnings do not gatekeep installation.Source: E. Cross-Scope Conflict Detection · p. 3

V. FORMAT CONFORMANCE SCORING

Skilldex scores skill-format conformance with compiler-style diagnostics derived from Anthropic’s specification. The validator separates fatal frontmatter failure from nonfatal checks and preserves a boundary between scoring and semantic quality.

A. Motivation

  • Description quality can affect skill triggering, but conformance scoring is only an objective proxy and not a measure of functional quality.A syntactically perfect skill may still be useless, while a low-scoring skill may be valuable.Source: A. Motivation · pp. 3–4

B. Scoring Checks

  • The validator performs eight checks and produces a score from 0 to 100.The scoring system targets format properties such as description and structural adherence.Source: B. Scoring Checks · p. 4, A. Motivation · p. 4
  • Missing frontmatter is the only fatal condition: it scores zero and halts subsequent checks.Other failures generate diagnostics while allowing installation to proceed.Source: B. Scoring Checks · p. 4

C. Diagnostic Output

  • Diagnostics use compiler-style severities, optional line numbers, and human-readable messages for passes, warnings, and errors.The example reports valid YAML, a short description on line 4, an unknown subdirectory, and a 45/100 score against skill-format v1.0.Source: C. Diagnostic Output · p. 4
  • Structured JSON output exposes the skill, score, diagnostics, specification version, and pass, warning, and error counts for automation.The --json flag enables programmatic use and CI/CD integration.Source: C. Diagnostic Output · p. 4

D. Spec Ownership Boundary

  • Skilldex derives its scoring table from Anthropic’s published guide rather than owning or extending the format specification.Specification updates are handled through new scorer versions recorded in the manifest.Source: D. Spec Ownership Boundary · p. 4

VI. AGENT SUGGESTION LOOP

Skilldex separates capability selection from task execution by gathering project context, generating scoped skill proposals, and requiring human approval before installation.

A. Motivation

  • A human-in-the-loop checkpoint separates deciding what capabilities an agent should have from deciding how it should use them.The checkpoint occurs between project context and task execution.Source: A. Motivation · p. 4

B. Workflow

  • The suggestion workflow gathers repository metadata and installed skills across scopes into a structured context string.It reads the first 100 README.md lines, package.json fields, agent configuration contents, and installed skill manifests.Source: B. Workflow · p. 4
  • An LLM converts that context into proposed skills with names, justifications, suggested scopes, and registry-availability status.The proposal prompt also distinguishes registry skills from custom skills requiring authoring.Source: B. Workflow · p. 4
  • Users approve or reject each proposal and may override its scope; approved registry skills are queued for manual installation, while unavailable skills become authoring candidates.The loop does not trigger installation directly.Source: B. Workflow · p. 4
  • The CLI displays proposed skills with reasons and scopes, and supports non-interactive approval for CI or automated setup.The example output includes project- and global-scope proposals, while --yes approves all proposals at their suggested scopes.Source: B. Workflow · pp. 4–5

VII. COMMUNITY REGISTRY

The community registry stores searchable skill metadata while leaving skill content in source repositories, trading low infrastructure cost and author control for GitHub-dependent installation.

A. Architecture Decisions

  • Skilldex stores registry metadata only; installation fetches skill files directly from the GitHub source URL.The design avoids binary storage and CDN infrastructure while inheriting GitHub reliability, access controls, and versioning.Source: A. Architecture Decisions · p. 5
  • GitHub availability and rate limits constrain installation, with optional authenticated requests increasing the limit from 60 to 5,000 requests per hour.The registry can also be re-seeded from source without data loss.Source: A. Architecture Decisions · p. 5

B. Database Schema

  • The PostgreSQL/Supabase schema represents publishers, skills, and skillsets with source URLs, trust metadata, scores, specification versions, tags, and installation counts.Skillset records additionally store skill references and a generated skill count.Source: B. Database Schema · p. 5
  • PostgreSQL provides full-text search over names and descriptions, supplemented by trigram indexes for fuzzy skill-name matching.Source: B. Database Schema · p. 5

C. Trust Tier Model

Skilldex combines a non-gating verified/community trust model with a versioned API, automated source seeding, and server-side validation for published skills.

C. Trust Tier Model

  • The trust model distinguishes manually assigned verified Anthropic skills from community submissions open to authenticated GitHub users.There is no automated promotion path from community to verified.Source: C. Trust Tier Model · p. 5
  • A hard verified/community boundary is intended to resist rating inflation while keeping trust information non-blocking for installation.Skilldex presents information rather than gatekeeping access.Source: C. Trust Tier Model · p. 5

D. API Surface

  • The registry exposes a versioned REST API with GitHub OAuth authentication and endpoint-specific rate limits, using in-memory limiting in the current deployment.Upstash Redis is planned for production hardening.Source: D. API Surface · p. 6

E. Registry Seeding

  • Nightly seeding fetches registered Anthropic sources, validates them, and upserts verified records; nondestructive re-seeding reflects source changes within 24 hours.The workflow can also run interactively or non-interactively on demand.Source: E. Registry Seeding · p. 6

F. Publishing Flow

  • Publishing reads skill metadata and repository remotes locally, then the backend fetches and validates the skill from GitHub before storing it.Source: F. Publishing Flow · p. 6

A. Motivation

  • Skillsets address behavioral drift by packaging related skills with shared assets that preserve a common vocabulary across their outputs.Independent skills can otherwise diverge when they use incompatible conventions.Source: A. Motivation · p. 6

B. Shared Assets: Cross-Skill Behavioral Coherence

Skillsets bundle related skills around shared assets, allowing constituent skills to use common conventions, templates, and reference material while supporting embedded and remotely referenced skills.

B. Shared Assets: Cross-Skill Behavioral Coherence

  • A skillset’s root assets/ directory supplies shared files referenced by each constituent skill through relative paths.This directory is distinct from each skill’s own per-skill assets/ directory.Source: B. Shared Assets: Cross-Skill… · p. 6
  • Skilldex ships developer, research, and skillset-creator reference skillsets, with the developer set packaging four workflow skills around commit-conventions.md.The illustrated layout also includes skill-specific templates, scripts, and testing references.Source: B. Shared Assets: Cross-Skill… · pp. 6–7
  • Shared commit conventions bind conventional-commit and changelog-gen to the same type definitions and type-to-section mapping.Both skills therefore use a common vocabulary for writing commits and classifying changelog sections.Source: B. Shared Assets: Cross-Skill… · p. 7
  • The research skillset shares audience-personas.md between technical-explainer and paper-summarizer, aligning vocabulary to named personas across outputs.The shared file calibrates both a senior-developer paper summary and a plain-language explanation.Source: B. Shared Assets: Cross-Skill… · p. 7

C. SKILLSET.md Format

  • SKILLSET.md mirrors SKILL.md frontmatter and adds a skills list for remote references, while embedded skills are autodiscovered from subdirectories.The root file defines the skillset’s metadata and membership model.Source: C. SKILLSET.md Format · p. 7

D. Skillset Validation Scoring

Skilldex validates skillsets and installs their embedded and remote skills through the existing installation stack. MCP exposes the same operations to agents, while manifest defaults preserve compatibility with earlier installations.

E. Installation Semantics

  • Skillset installation validates first, installs embedded and remote skills through existing functions, then copies shared metadata and records the bundle in the manifest.The reused installation stack includes validation, scope conflict detection, and manifest recording.Source: E. Installation Semantics · p. 7
  • The installed-skillset manifest records source, version, score, path, embedded skills, and remote skills.The manifest schema names these fields explicitly.Source: E. Installation Semantics · p. 7

F. Backward Compatibility

IX. MCP INTEGRATION

  • The MCP server provides structured JSON tools backed by the same core functions as the CLI, enabling agents to propose, approve, and install skills within one session.Source: §IX · p. 7

X. IMPLEMENTATION DETAILS

Skilldex implements a TypeScript CLI, registry backend, and web frontend around modular commands and searchable package distribution. The implementation reuses shallow Git retrieval, edge-hosted services, and documented installation interfaces.

A. CLI Command Structure

  • Skilldex exposes install, uninstall, update, list, validate, publish, search, suggest, configuration, MCP, and seven skillset commands.Each command uses a thin registration file and a lazily imported action file.Source: A. CLI Command Structure · pp. 7–8

B. Manifest Atomicity

  • Concurrent CLI processes can produce a torn manifest because writes are sequential, though temporary-file renaming supports the interactive use pattern.Source: B. Manifest Atomicity · p. 8

C. Git URL Parsing

  • GitHub tree URLs yield a repository, branch, and subpath; the installer shallow-clones the branch and searches the resolved subpath for skills.Source: C. Git URL Parsing · p. 8

D. Registry Backend

  • The registry uses Hono on Vercel Edge Functions with Supabase PostgreSQL, GitHub OAuth, and row-level security.Source: D. Registry Backend · p. 8

E. Web Frontend

  • The web frontend provides searchable registry and skillset pages with metadata, conformance scores, trust tiers, install counts, and copyable commands.It also hosts organized documentation and platform-specific installation instructions.Source: E. Web Frontend · p. 8

F. Technology Stack

XI. DESIGN PHILOSOPHY

Skilldex favors informative, non-blocking interfaces, preserves Anthropic’s ownership of the skill specification, and unifies human and agent interfaces through one core. The paper identifies unresolved limits in versioning, scoring, concurrency, hierarchy, governance, adoption, and automated installation.

XI. DESIGN PHILOSOPHY

  • Skilldex treats validation, trust, and scope conflicts as warnings rather than installation blockers, while the CLI and MCP server share one behavioral core.The CLI targets humans and MCP targets agents, but both invoke the same core modules.Source: §XI · pp. 8–9

XII. LIMITATIONS AND FUTURE WORK

  • Anthropic’s unversioned format forces Skilldex to track the creator guide manually, and semantic description quality remains outside objective conformance scoring.Word count, YAML parsing, and allowed directories are scoreable, but contextual triggering quality is not.Source: §XII · p. 9
  • The design leaves concurrent manifest writes, fixed three-level hierarchy, absent team governance, community cold-start dynamics, and non-automatic suggestion-loop installation unresolved.Direct installation from the suggestion loop is planned.Source: §XII · p. 9

XIII. CONCLUSION

  • Skilldex makes conformance feedback and mutually coherent skill bundles first-class publishable artifacts, supported by hierarchical scope, suggestion, MCP, and registry infrastructure.The conclusion frames a complete developer or research agent configuration as a publishable artifact.Source: §XIII · p. 9

Related papers

Loading 2604.16911v1…