Agent Skills Architecture Design

Agent Skills Architecture Design

This document describes the architecture and data model for the Agent Skills feature in MCP Gateway Registry.

Overview

Agent Skills are reusable, shareable instruction sets that augment AI coding assistants with specialized capabilities. Unlike MCP servers (which provide tools), skills provide context, workflows, and behavioral guidance that help AI assistants perform specific tasks more effectively.

The Agent Skills feature follows the agentskills.io specification, providing a standardized way to discover, share, and manage skills across AI coding environments.

Design Principles

Separation of Concerns

Skills and Servers serve different purposes:

URL-Based Discovery

Skills are referenced by a single URL pointing to a SKILL.md file:

https://github.com/org/repo/blob/main/skills/pdf-processing/SKILL.md

The registry:

1. Accepts the user-provided URL (blob URL for GitHub)
2. Auto-translates to raw content URL for fetching
3. Stores both URLs for different use cases

Progressive Disclosure

Skills support multiple detail tiers to avoid overwhelming AI assistants:

1. Card View: Name, description, tags (for discovery)
2. Summary View: Plus requirements, tools, target agents
3. Full View: Complete SKILL.md content with all details

Data Model

SkillCard Entity

The primary entity representing a registered skill:

SkillCard
├── Identification
│   ├── path: /skills/{name}         # Unique, immutable path
│   ├── name: string                 # Lowercase alphanumeric with hyphens
│   └── description: string          # What the skill does
│
├── URLs
│   ├── skill_md_url: HttpUrl        # User-provided URL (e.g., GitHub blob)
│   ├── skill_md_raw_url: HttpUrl    # Auto-translated raw content URL
│   └── repository_url: HttpUrl      # Optional git repository
│
├── Metadata
│   ├── version: string              # Skill version
│   ├── author: string               # Skill author
│   ├── license: string              # License identifier
│   ├── compatibility: string        # Human-readable requirements
│   └── tags: string[]               # Categorization tags
│
├── Requirements
│   ├── requirements: CompatibilityRequirement[]  # Machine-readable
│   ├── target_agents: string[]      # Target AI assistants
│   └── allowed_tools: ToolReference[]  # Required MCP tools
│
├── Access Control
│   ├── visibility: public|private|group
│   ├── allowed_groups: string[]     # For group visibility
│   └── owner: string                # For private visibility
│
├── State
│   ├── is_enabled: boolean          # Enable/disable toggle
│   ├── registry_name: string        # Source registry (for federation)
│   ├── health_status: healthy|unhealthy|unknown
│   └── last_checked_time: datetime  # Last health check
│
├── Ratings
│   ├── num_stars: float             # Average rating (0-5)
│   └── rating_details: RatingDetail[]  # Individual ratings
│
└── Timestamps
    ├── created_at: datetime
    └── updated_at: datetime

ToolReference

Links skills to required MCP server tools:

class ToolReference:
    tool_name: str           # Tool name (e.g., "Read", "Bash")
    server_path: str | None  # MCP server path (e.g., "/servers/claude-tools")
    version: str | None      # Optional version constraint
    capabilities: list[str]  # Capability filters (e.g., ["git:*"])

CompatibilityRequirement

Machine-readable compatibility constraints:

class CompatibilityRequirement:
    type: "product" | "tool" | "api" | "environment"
    target: str              # Target identifier
    min_version: str | None  # Minimum version
    max_version: str | None  # Maximum version
    required: bool           # False = optional enhancement

URL Translation

The registry automatically translates user-friendly URLs to raw content URLs:

GitHub Translation

Input:  https://github.com/org/repo/blob/main/skills/name/SKILL.md
Output: https://raw.githubusercontent.com/org/repo/main/skills/name/SKILL.md

GitLab Translation

Input:  https://gitlab.com/org/repo/-/blob/main/skills/name/SKILL.md
Output: https://gitlab.com/org/repo/-/raw/main/skills/name/SKILL.md

Bitbucket Translation

Input:  https://bitbucket.org/org/repo/src/main/skills/name/SKILL.md
Output: https://bitbucket.org/org/repo/raw/main/skills/name/SKILL.md

Access Control

Skills support three visibility levels:

Public Skills

• Visible to all authenticated users
• Discoverable via search and listing
• Exportable via federation

Private Skills

• Visible only to the owner
• Not discoverable by others
• Not exportable via federation

Group Skills

• Visible to members of specified groups
• Groups are managed via IdP integration (Entra ID, Cognito, etc.)
• Requires allowed_groups to be specified

Health Checking

Skills are health-checked by verifying SKILL.md accessibility:

1. HEAD Request: Verify the raw URL is accessible
2. Status Codes: 2xx = healthy, others = unhealthy
3. Trusted Domains: Only allowed domains are checked (SSRF protection)
4. Caching: Results cached with last_checked_time

Trusted Domains

TRUSTED_DOMAINS = [
    "raw.githubusercontent.com",
    "gitlab.com",
    "bitbucket.org",
    "gist.githubusercontent.com",
]

Rating System

Skills use the same rating system as servers and agents:

1. Star Rating: 1-5 stars
2. Per-User: One rating per user per skill
3. Updates: Users can update their rating
4. Average: Displayed as average of all ratings

Tool Validation

Skills can reference MCP server tools. The registry validates tool availability:

1. Check Registration: Verify referenced servers exist
2. Check Tools: Verify tools are exposed by servers
3. Report Status: Return availability status per tool

API Endpoints

Skill Management

Skill State

Skill Content

Ratings

Database Schema

Skills are stored in MongoDB/DocumentDB with the following indexes:

// Unique index on name
db.agent_skills.createIndex({ "name": 1 }, { unique: true })

// Tags for filtering
db.agent_skills.createIndex({ "tags": 1 })

// Visibility for access control
db.agent_skills.createIndex({ "visibility": 1 })

// Registry name for federation
db.agent_skills.createIndex({ "registry_name": 1 })

// Owner for private skills
db.agent_skills.createIndex({ "owner": 1 })

// Compound index for common queries
db.agent_skills.createIndex({
    "visibility": 1,
    "is_enabled": 1,
    "registry_name": 1
})

Federation Support

Skills participate in peer-to-peer federation:

1. Export: Public skills are exported to peer registries
2. Import: Skills from peers are imported with registry_name set
3. Sync Modes: All, whitelist, or tag-based filtering
4. Ownership: Federated skills retain original registry attribution

Future Considerations

Content Caching

• Cache SKILL.md content to reduce external fetches
• Use content_version hash for cache invalidation
• Track content_updated_at for freshness

Skill Bundles

• Group related skills into bundles
• Enable/disable bundles atomically
• Share bundle configurations

Usage Analytics

• Track skill usage across clients
• Surface popular skills in discovery
• Enable skill recommendations

Versioning

• Track skill version history
• Support rollback to previous versions
• Version-aware federation sync