ICA Skill Library Use Case¶

Overview¶

This document describes the end-to-end workflow for ICA (Intelligent Coding Assistant) team members to discover, configure, and deploy curated agent skills from the Skill Library to their projects through automated pull requests.

Actors¶

Developer: ICA team member with developer role
Team Lead: ICA team member with admin/lead role (optional for approval workflows)
System Admin: Platform administrator with catalog management permissions
System: SkillMeat Enterprise platform

Prerequisites¶

Active ICA team membership with developer role or higher
Access to SkillMeat Enterprise edition
Project with Git repository configured
GitHub/GitLab credentials configured for PR creation

User Story¶

As a member of an ICA team with a developer role,
I want to browse and filter curated agent skills in the Skill Library catalog,
So that I can discover relevant skills, configure my project's Git repository, and deploy selected skill groups as pull requests to my codebase.

Workflow Overview¶

sequenceDiagram
    actor Dev as Developer
    participant UI as Skill Library UI
    participant API as SkillMeat API
    participant Git as Git Provider
    participant Repo as Project Repository

    Dev->>UI: 1. Browse Skill Library
    UI->>API: GET /marketplace/catalog
    API-->>UI: Return curated skills

    Dev->>UI: 2. Apply filters
    UI->>API: GET /marketplace/catalog?filters=...
    API-->>UI: Return filtered results

    Dev->>UI: 3. Select skills (5)
    UI->>UI: Update selection cart

    Dev->>UI: 4. Configure Git repo
    UI->>API: POST /git-connections
    API->>Git: Test connection
    Git-->>API: Connection OK
    API-->>UI: Configuration saved

    Dev->>UI: 5. Deploy to Git
    UI->>API: POST /deployments/create-pr
    API->>Repo: Create branch
    API->>Repo: Generate skill files
    API->>Repo: Commit changes
    API->>Repo: Push to remote
    API->>Git: Create pull request
    Git-->>API: PR #1234 created
    API-->>UI: Deployment successful

    Dev->>Git: 6. Review PR
    Dev->>Git: 7. Merge PR
    Git->>Repo: Merge changes
    Repo-->>Dev: Skills deployed

High-Level Workflow Steps¶

1. Browse Skill Library¶

Developer navigates to the Skill Library and views curated catalog of agent skills organized by category, technology stack, complexity level, and team recommendations.

2. Filter and Search Skills¶

Developer applies filters (category, technology, complexity) and searches by keywords to narrow down skill selection to relevant results.

3. Review Skill Details¶

Developer clicks on skills to view detailed information including description, dependencies, configuration options, compatibility, and community reviews.

4. Select Skills for Deployment¶

Developer adds individual skills or pre-curated skill groups to selection cart, reviews summary, and checks for conflicts or dependencies.

5. Configure Git Repository¶

Developer configures Git repository connection with URL, branch, authentication credentials, and PR settings (reviewers, labels, templates).

6. Deploy Skills as Pull Request¶

Developer initiates deployment which creates a branch, generates skill files, updates manifest, commits changes, and creates a pull request automatically.

7. Review and Merge Pull Request¶

Team lead receives notification, reviews PR changes, runs CI/CD checks, approves, and merges the PR to make skills available in the project.

Success Criteria¶

✅ Developer can browse and filter 100+ curated skills
✅ Filter combinations reduce results to relevant subset (< 20 skills)
✅ Git repository configuration is saved and reusable
✅ Pull request is created successfully with all metadata
✅ PR contains correct file structure and manifest updates
✅ Skills are immediately usable after PR merge
✅ Deployment completes in < 60 seconds end-to-end

Data Flow¶

flowchart LR
    subgraph "User Actions"
        A[Browse Skills] --> B[Filter/Search]
        B --> C[Select Skills]
        C --> D[Configure Git]
        D --> E[Deploy]
    end

    subgraph "System Processing"
        E --> F{Validate<br/>Selection}
        F -->|Valid| G[Create Branch]
        F -->|Invalid| H[Show Errors]
        G --> I[Generate Files]
        I --> J[Update Manifest]
        J --> K[Commit Changes]
        K --> L[Push to Remote]
        L --> M[Create PR]
    end

    subgraph "Outcomes"
        M --> N[PR Created]
        N --> O[Notify Reviewers]
        O --> P{Review}
        P -->|Approved| Q[Merge PR]
        P -->|Rejected| R[Request Changes]
        Q --> S[Skills Active]
    end

    style A fill:#e1f5ff
    style E fill:#fff3cd
    style M fill:#d4edda
    style S fill:#28a745,color:#fff

Error Handling¶

flowchart TD
    A[Start Deployment] --> B{Git Auth<br/>Valid?}
    B -->|No| C[Show Auth Error]
    C --> D[Refresh Credentials]
    D --> A

    B -->|Yes| E{Skill<br/>Compatible?}
    E -->|No| F[Show Compatibility Warning]
    F --> G{Continue?}
    G -->|No| H[Remove Incompatible Skills]
    H --> A
    G -->|Yes| I[Proceed with Warning]

    E -->|Yes| I
    I --> J{Create<br/>Branch}
    J -->|Conflict| K[Show Merge Conflict]
    K --> L[Retry with New Branch]
    L --> J

    J -->|Success| M[Generate Files]
    M --> N{Commit<br/>Success?}
    N -->|No| O[Show Commit Error]
    O --> P[Rollback Changes]

    N -->|Yes| Q[Create PR]
    Q --> R{PR<br/>Created?}
    R -->|No| S[Show PR Error]
    S --> T[Manual PR Creation]

    R -->|Yes| U[Deployment Complete]

    style C fill:#f8d7da
    style F fill:#fff3cd
    style K fill:#fff3cd
    style O fill:#f8d7da
    style S fill:#f8d7da
    style U fill:#d4edda

Common Error Scenarios¶

Git Authentication Failure: Invalid or expired credentials - Developer updates credentials or contacts team admin

Merge Conflict: Deployment branch conflicts with target branch - System retries with fresh branch or developer resolves manually

Skill Compatibility Issue: Selected skill incompatible with project - Developer upgrades dependencies or removes incompatible skill

Use Case 2: System Admin - Catalog Management¶

User Story¶

As a system administrator with catalog management permissions, I want to manage the Skill Library catalog by adding, updating, and organizing skills, So that I can ensure developers have access to high-quality, curated agent skills that meet organizational standards.

Admin Workflow Overview¶

sequenceDiagram
    actor Admin as System Admin
    participant UI as Admin Console
    participant API as SkillMeat API
    participant DB as PostgreSQL
    participant Git as Git Provider

    Admin->>UI: 1. Access Catalog Management
    UI->>API: GET /admin/marketplace/catalog
    API->>DB: Fetch all skills
    DB-->>API: Return skills
    API-->>UI: Display catalog

    Admin->>UI: 2. Add new skill
    UI->>API: POST /admin/marketplace/skills
    API->>Git: Fetch skill from source
    Git-->>API: Return skill files
    API->>DB: Validate & store skill
    DB-->>API: Skill created
    API-->>UI: Success notification

    Admin->>UI: 3. Update skill metadata
    UI->>API: PATCH /admin/marketplace/skills/{id}
    API->>DB: Update skill
    DB-->>API: Updated
    API-->>UI: Changes saved

    Admin->>UI: 4. Organize into categories
    UI->>API: POST /admin/marketplace/categories
    API->>DB: Create/update categories
    DB-->>API: Categories updated
    API-->>UI: Organization complete

Admin Workflow Steps¶

1. Access Catalog Management¶

System admin logs into admin console and navigates to "Catalog Management" section with full CRUD permissions on skills, categories, metadata, and versions.

2. Add New Skill to Catalog¶

Admin imports skill from Git repository, validates content, sets metadata (category, tags, complexity), assigns initial version (1.0.0), and publishes to catalog for team access.

3. Publish New Skill Version¶

Admin uploads new version of existing skill, increments version number (MAJOR/MINOR/PATCH), writes changelog, marks breaking changes, runs compatibility checks, and publishes update with migration guide if needed.

4. Update Skill Metadata¶

Admin edits skill properties including description, compatibility requirements, team recommendations, and visibility settings across all versions or specific versions.

5. Organize Skills into Categories¶

Admin creates/updates categories, assigns skills to categories, sets display order, and configures filters for better discoverability.

6. Review and Approve Submissions¶

Admin reviews community-submitted skills, runs security scans, validates quality standards, and approves or rejects for catalog inclusion.

7. Monitor Usage Analytics¶

Admin views skill deployment statistics by version, identifies popular/unused versions, analyzes adoption trends, tracks upgrade rates, and makes data-driven curation decisions.

8. Deprecate Skill Versions¶

Admin marks old versions as deprecated, sets 6-month sunset timeline, creates migration guide, notifies affected teams, and eventually archives deprecated versions.

9. Manage Version Lifecycle¶

Admin promotes beta versions to stable, marks latest stable version, manages version tags (latest/stable/beta), and enforces deprecation policies.

Admin Interface¶

graph TB
    subgraph AdminConsole["Admin Console - Catalog Management"]
        A[Dashboard] --> B[Skill List View]
        A --> C[Category Management]
        A --> D[Analytics Dashboard]

        B --> E[Add New Skill]
        B --> F[Edit Skill]
        B --> G[Bulk Operations]

        C --> H[Create Category]
        C --> I[Assign Skills]

        D --> J[Usage Stats]
        D --> K[Adoption Trends]
    end

    style A fill:#6c757d,color:#fff
    style B fill:#007bff,color:#fff
    style D fill:#28a745,color:#fff

Catalog Management Operations¶

Add New Skill (Version 1.0.0)¶

Actions: 1. Click "Add Skill" button 2. Choose import method: - Import from Git repository URL - Upload skill files directly - Clone from existing skill 3. Configure skill metadata: - Name and description - Category and tags - Complexity level (Beginner/Intermediate/Advanced) - Technology stack - Version and compatibility 4. Set visibility: - Public (all teams) - Team-specific - Private (admin only) 5. Run validation checks: - File structure validation - Security scan - Dependency check 6. Publish to catalog

Validation Checks:

file_structure:
  required_files:
    - SKILL.md
    - config.toml
  optional_files:
    - prompts/
    - examples/

security_scan:
  - No hardcoded credentials
  - No malicious code patterns
  - Safe dependency versions

quality_checks:
  - Description completeness
  - Example usage provided
  - Version format valid

Publish New Skill Version¶

Actions: 1. Navigate to skill details page 2. Click "Publish New Version" button 3. Select version increment type: - MAJOR (breaking changes): 1.2.0 → 2.0.0 - MINOR (new features): 1.2.0 → 1.3.0 - PATCH (bug fixes): 1.2.0 → 1.2.1 4. Upload updated skill files or pull from Git 5. Write changelog: - Features added - Improvements made - Bugs fixed - Breaking changes (if MAJOR) - Deprecations 6. Mark breaking changes (if any) 7. Create migration guide (if breaking changes) 8. Set version tags: - Mark as latest (default for new versions) - Mark as stable (if production-ready) - Mark as beta (if pre-release) 9. Run validation and compatibility checks 10. Publish version to catalog

Version Increment Decision Tree:

Breaking API changes: MAJOR (1.x.x → 2.0.0)
New features (backward-compatible): MINOR (1.2.x → 1.3.0)
Bug fixes only: PATCH (1.2.3 → 1.2.4)

Changelog Template:

# Version 1.3.0

## Features
- Added auto-fix suggestions for common issues
- New configuration option: `auto_fix`

## Improvements
- Improved error messages with line numbers
- Performance optimizations (30% faster)

## Bug Fixes
- Fixed validation for nested Pydantic models
- Resolved issue with optional fields

## Breaking Changes
None

## Deprecations
None

## Migration Guide
No migration required - fully backward compatible

Update Skill Metadata¶

Editable Fields: - Description and documentation - Category assignment - Tags and keywords - Complexity level - Technology stack - Compatibility requirements - Team recommendations - Featured/promoted status - Deprecation status

Organize Categories¶

Category Management:

categories:
  - name: Code Review
    description: Skills for automated code review
    icon: code-review
    display_order: 1
    skills_count: 12

  - name: Testing
    description: Test generation and validation skills
    icon: test-tube
    display_order: 2
    skills_count: 8

  - name: Documentation
    description: Auto-documentation and API docs
    icon: book
    display_order: 3
    skills_count: 6

Deprecate Skill Version¶

Actions: 1. Navigate to skill version management 2. Select version to deprecate (e.g., v1.0.0) 3. Click "Deprecate Version" 4. Set deprecation details: - Deprecation date (today) - Sunset date (6 months from now) - Replacement version (e.g., v1.2.0) - Reason for deprecation 5. Create migration guide (if needed) 6. Configure notifications: - Email affected teams - Show warning in UI - Add deprecation notice to API responses 7. Confirm deprecation

Deprecation Notice Example:

version: "1.0.0"
deprecated: true
deprecation_date: "2024-03-01"
sunset_date: "2024-09-01"
replacement_version: "1.2.0"
reason: "Security vulnerabilities fixed in v1.2.0"
migration_guide: "https://docs.skillmeat.io/migrations/1.0-to-1.2"

Affected Teams Notification:

Subject: Skill Version Deprecation Notice

The following skill version will be deprecated:
- Skill: API Schema Validator
- Version: 1.0.0
- Deprecation Date: March 1, 2024
- Sunset Date: September 1, 2024
- Replacement: Version 1.2.0

Action Required:
Please upgrade to version 1.2.0 before September 1, 2024.
Migration guide: https://docs.skillmeat.io/migrations/1.0-to-1.2

Your currently deployed projects using v1.0.0:
- project-api (deployed 2024-01-15)
- backend-service (deployed 2024-02-01)

Manage Version Tags¶

Actions: 1. Navigate to skill version list 2. Select version to tag 3. Assign/remove tags: - latest - Most recent stable version (only one) - stable - Production-ready version (can be multiple) - beta - Pre-release version (can be multiple) 4. Save changes

Tag Rules: - Only one version can have latest tag - Multiple versions can have stable tag - Beta versions should not have latest or stable tags - Deprecated versions lose all tags

Bulk Operations¶

Available Actions: - Bulk category assignment - Bulk tag updates - Bulk visibility changes - Bulk deprecation - Export catalog to JSON/CSV - Import skills from manifest

Admin Success Criteria¶

✅ Admin can add new skills in < 2 minutes
✅ Validation catches 100% of security issues
✅ Category organization is intuitive for developers
✅ Usage analytics update in real-time
✅ Bulk operations handle 50+ skills efficiently
✅ Deprecated skills show clear warnings to users

Admin Metrics¶

Catalog Size: Total skills available
Quality Score: Avg rating across all skills
Submission Rate: New skills added per week
Approval Rate: % of submitted skills approved
Deprecation Rate: Skills deprecated per month
Category Balance: Skills per category distribution

Use Case 3: Agentic App Studio Integration¶

User Story¶

As an Agentic App Studio application,
I want to programmatically access the Skill Library catalog via REST APIs,
So that I can discover, retrieve, and integrate agent skills into my agentic applications dynamically.

High-Level Use Cases¶

Use Case 3.1: AI Agent Builder - Skill Discovery¶

Persona: AI Agent Builder (automated system)
Goal: Discover relevant skills for a new coding agent being built
Scenario: Builder queries catalog API with filters (category: "code-review", technology: "python"), retrieves list of 12 matching skills, ranks by rating and downloads, selects top 3 for integration.

Use Case 3.2: Workflow Orchestrator - Dynamic Skill Loading¶

Persona: Workflow Orchestrator (runtime system)
Goal: Load skills on-demand during workflow execution
Scenario: Orchestrator receives task requiring API validation, queries catalog for "api-validation" skills, fetches skill details including requirements, downloads skill content (ZIP), validates compatibility, and integrates into active workflow.

Use Case 3.3: Skill Marketplace App - Catalog Browsing¶

Persona: Third-Party Marketplace Application
Goal: Display SkillMeat catalog in custom marketplace UI
Scenario: Marketplace app fetches paginated catalog (20 skills per page), displays with custom styling, allows users to filter by category/technology, shows skill ratings and download counts, provides "Install" button that triggers skill download API.

Use Case 3.4: CI/CD Pipeline - Automated Skill Updates¶

Persona: CI/CD Automation System
Goal: Keep deployed skills up-to-date automatically
Scenario: Pipeline subscribes to skill update webhooks, receives notification when "api-schema-validator" v1.3.0 is released, fetches new version details, runs compatibility checks, creates PR with updated skill, triggers tests before merge.

Use Case 3.5: Analytics Dashboard - Usage Tracking¶

Persona: Analytics Platform
Goal: Track skill adoption and usage trends
Scenario: Dashboard polls catalog API hourly, fetches all skills with download counts and ratings, stores time-series data, generates trend reports showing most popular skills, identifies underutilized skills, alerts admins to deprecation candidates.

Integration Overview¶

sequenceDiagram
    participant Studio as Agentic App Studio
    participant API as SkillMeat API
    participant DB as PostgreSQL
    participant Cache as Redis Cache

    Studio->>API: GET /api/v1/public/skills/catalog
    API->>Cache: Check cache
    Cache-->>API: Cache miss
    API->>DB: Query skills
    DB-->>API: Return skills
    API->>Cache: Store in cache
    API-->>Studio: Return catalog (JSON)

    Studio->>API: GET /api/v1/public/skills/{id}
    API->>DB: Fetch skill details
    DB-->>API: Return skill
    API-->>Studio: Return skill (JSON)

    Studio->>API: GET /api/v1/public/skills/{id}/content
    API->>DB: Fetch skill files
    DB-->>API: Return files
    API-->>Studio: Return content (ZIP/JSON)

Public API Endpoints¶

1. List Skills Catalog¶

Endpoint: GET /api/v1/public/skills/catalog

Description: Retrieve paginated list of available skills with filtering and search capabilities.

Query Parameters:

category: string[]          # Filter by categories (e.g., "testing", "code-review")
technology: string[]        # Filter by tech stack (e.g., "python", "typescript")
complexity: string          # Filter by level: "beginner", "intermediate", "advanced"
search: string              # Full-text search across name, description, tags
tags: string[]              # Filter by tags
featured: boolean           # Only featured skills
team_recommended: boolean   # Only team-recommended skills
page: integer               # Page number (default: 1)
per_page: integer           # Results per page (default: 20, max: 100)
sort: string                # Sort by: "name", "popularity", "updated", "rating"
order: string               # Sort order: "asc", "desc"

Response:

href="#__codelineno-7-1">{ "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "api-schema-validator", "display_name": "API Schema Validator", "description": "Validates FastAPI request/response schemas against OpenAPI spec", "version": "1.2.0", "category": "testing", "tags": ["api", "validation", "fastapi", "openapi"], "complexity": "intermediate", "technology_stack": ["python", "fastapi", "pydantic"], "author": "SkillMeat Team", "rating": 4.8, "downloads": 1247, "featured": true, "team_recommended": true, "compatibility": { "skillmeat_version": ">=0.25.0", "python_version": ">=3.9", "dependencies": ["fastapi>=0.100.0", "pydantic>=2.0.0"] }, "created_at": "2024-01-15T10:00:00Z", "updated_at": "2024-03-20T14:30:00Z", "links": { "self": "/api/v1/public/skills/550e8400-e29b-41d4-a716-446655440000", "content": "/api/v1/public/skills/550e8400-e29b-41d4-a716-446655440000/content", "documentation": "/api/v1/public/skills/550e8400-e29b-41d4-a716-446655440000/docs" } } ], "pagination": { "page": 1, "per_page": 20, "total_items": 156, "total_pages": 8, "has_next": true, "has_prev": false }, "filters_applied": { "category": ["testing"], "technology": ["python"], "complexity": "intermediate" } }

2. Get Skill Details¶

Endpoint: GET /api/v1/public/skills/{id}

Description: Retrieve detailed information about a specific skill.

Path Parameters: - id (UUID): Skill identifier

Response: Full skill metadata including capabilities, requirements, configuration, changelog

3. Get Skill Content¶

Endpoint: GET /api/v1/public/skills/{id}/content

Description: Download skill files and implementation.

Query Parameters:

format: string  # Response format: "zip" (default), "json", "tar.gz"
include: string[]  # Files to include: "all" (default), "prompts", "config", "examples"

Response (format=json):

{
  "skill_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "api-schema-validator",
  "version": "1.2.0",
  "files": {
    "SKILL.md": {
      "path": "SKILL.md",
      "content": "# API Schema Validator\n\n## Description\n...",
      "size": 2048,
      "mime_type": "text/markdown"
    },
    "config.toml": {
      "path": "config.toml",
      "content": "[skill]\nname = \"api-schema-validator\"\n...",
      "size": 512,
      "mime_type": "application/toml"
    }
  },
  "metadata": {
    "total_files": 5,
    "total_size": 8192,
    "checksum": "sha256:abc123..."
  }
}

4. Search Skills¶

Endpoint: GET /api/v1/public/skills/search

Description: Full-text search across skills with advanced filtering.

5. Get Categories & Technologies¶

Endpoint: GET /api/v1/public/skills/categories
Endpoint: GET /api/v1/public/skills/technologies

Skill Versioning¶

Overview¶

SkillMeat Skill Library supports semantic versioning (SemVer) for all skills, enabling developers to manage skill updates, maintain compatibility, and roll back to previous versions when needed.

Version Format¶

Semantic Versioning: MAJOR.MINOR.PATCH (e.g., 1.2.3)

MAJOR: Breaking changes, incompatible API changes
MINOR: New features, backward-compatible
PATCH: Bug fixes, backward-compatible

Version Tags: - latest - Most recent stable version - stable - Last known stable version - beta - Pre-release version for testing - v1.2.3 - Specific version tag

Version Management Use Cases¶

Use Case 4.1: Deploy Specific Version¶

Scenario: Developer wants to deploy a specific tested version rather than latest.

Workflow: 1. Browse skill library, view "API Schema Validator" 2. Click "Version History" to see all versions 3. Select version 1.1.0 (tested and approved) 4. Deploy to project with version pinning 5. Manifest records exact version: version = "1.1.0"

API Call:

curl "https://api.skillmeat.io/api/v1/public/skills/{id}/versions/1.1.0/content" \
  -H "Authorization: Bearer YOUR_API_KEY"

Use Case 4.2: Update to Latest Version¶

Scenario: Developer receives notification that skill has new version with bug fixes.

Workflow: 1. Navigate to "Installed Skills" in project 2. See "Update Available" badge on "API Schema Validator" (1.1.0 → 1.2.0) 3. Click "View Changes" to see changelog 4. Review breaking changes (none for MINOR update) 5. Click "Update" to create PR with new version 6. Tests pass, merge PR

API Call:

curl "https://api.skillmeat.io/api/v1/public/skills/{id}/versions/latest" \
  -H "Authorization: Bearer YOUR_API_KEY"

Use Case 4.3: Rollback to Previous Version¶

Scenario: New version introduces regression, need to rollback.

Workflow: 1. Detect issue with skill v1.2.0 in production 2. Navigate to skill in project 3. Click "Version History" → Select v1.1.0 4. Click "Rollback to this version" 5. System creates PR reverting to v1.1.0 6. Merge PR to restore stable version

Use Case 4.4: Version Compatibility Check¶

Scenario: System admin adds new skill version, needs compatibility validation.

Workflow: 1. Admin uploads skill v2.0.0 (MAJOR version) 2. System detects breaking changes 3. Admin marks incompatible versions: incompatible_with: ["<2.0.0"] 4. Developers with v1.x see "Breaking Changes" warning 5. Migration guide provided for upgrade path

Version API Endpoints¶

1. List Skill Versions¶

Endpoint: GET /api/v1/public/skills/{id}/versions

Response:

{
  "skill_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "api-schema-validator",
  "versions": [
    {
      "version": "1.2.0",
      "tag": "latest",
      "release_date": "2024-03-20T14:30:00Z",
      "changelog": [
        "Added auto-fix suggestions",
        "Improved error messages",
        "Performance optimizations"
      ],
      "breaking_changes": false,
      "deprecated": false,
      "downloads": 847,
      "compatibility": {
        "skillmeat_version": ">=0.25.0",
        "python_version": ">=3.9"
      }
    },
    {
      "version": "1.1.0",
      "tag": "stable",
      "release_date": "2024-02-15T10:00:00Z",
      "changelog": [
        "Support for Pydantic v2",
        "Bug fixes"
      ],
      "breaking_changes": false,
      "deprecated": false,
      "downloads": 1247
    },
    {
      "version": "1.0.0",
      "release_date": "2024-01-15T10:00:00Z",
      "changelog": ["Initial release"],
      "breaking_changes": false,
      "deprecated": true,
      "deprecation_date": "2024-06-01T00:00:00Z",
      "downloads": 523
    }
  ],
  "latest_version": "1.2.0",
  "stable_version": "1.1.0"
}

2. Get Specific Version¶

Endpoint: GET /api/v1/public/skills/{id}/versions/{version}

Path Parameters: - id (UUID): Skill identifier - version (string): Version number or tag (1.2.0, latest, stable)

Response: Full skill details for specific version

3. Compare Versions¶

Endpoint: GET /api/v1/public/skills/{id}/versions/compare

Query Parameters:

from: string  # Source version (e.g., "1.1.0")
to: string    # Target version (e.g., "1.2.0")

Response:

{
  "skill_id": "550e8400-e29b-41d4-a716-446655440000",
  "comparison": {
    "from_version": "1.1.0",
    "to_version": "1.2.0",
    "version_type": "minor",
    "breaking_changes": false,
    "changes": {
      "added": [
        "Auto-fix suggestions feature",
        "New configuration option: auto_fix"
      ],
      "modified": [
        "Error message formatting improved",
        "Performance optimizations"
      ],
      "removed": [],
      "deprecated": []
    },
    "files_changed": [
      {
        "path": "SKILL.md",
        "change_type": "modified",
        "additions": 45,
        "deletions": 12
      },
      {
        "path": "prompts/validate.md",
        "change_type": "modified",
        "additions": 23,
        "deletions": 5
      }
    ],
    "migration_required": false,
    "migration_guide": null
  }
}

4. Get Version Changelog¶

Endpoint: GET /api/v1/public/skills/{id}/versions/{version}/changelog

Response:

{
  "version": "1.2.0",
  "release_date": "2024-03-20T14:30:00Z",
  "release_notes": "## What's New\n\n### Features\n- Auto-fix suggestions...",
  "changelog": [
    {
      "type": "feature",
      "description": "Added auto-fix suggestions for common schema issues"
    },
    {
      "type": "improvement",
      "description": "Improved error messages with line numbers"
    },
    {
      "type": "fix",
      "description": "Fixed validation for nested Pydantic models"
    }
  ],
  "breaking_changes": [],
  "deprecations": [],
  "security_fixes": []
}

Version Constraints in Manifest¶

Exact Version:

[[artifacts]]
name = "api-schema-validator"
type = "skill"
version = "1.2.0"  # Exact version

Version Range:

[[artifacts]]
name = "api-schema-validator"
type = "skill"
version = "^1.2.0"  # Compatible with 1.x (>=1.2.0, <2.0.0)

Version Operators: - 1.2.0 - Exact version - ^1.2.0 - Compatible (>=1.2.0, <2.0.0) - ~1.2.0 - Patch updates (>=1.2.0, <1.3.0) - >=1.2.0 - Minimum version - latest - Always use latest version (not recommended for production)

Version Lifecycle¶

stateDiagram-v2
    [*] --> Development: Create new version
    Development --> Beta: Release beta
    Beta --> Stable: Promote to stable
    Beta --> Development: Fix issues
    Stable --> Latest: Mark as latest
    Stable --> Deprecated: Deprecate old version
    Deprecated --> Removed: Remove after sunset
    Removed --> [*]

    note right of Beta
        Pre-release testing
        Limited availability
    end note

    note right of Stable
        Production ready
        Recommended version
    end note

    note right of Deprecated
        6-month sunset period
        Migration guide provided
    end note

Version Update Strategies¶

Conservative (Recommended for Production)¶

# Pin to specific version
version = "1.2.0"

# Or allow patch updates only
version = "~1.2.0"  # 1.2.x

Moderate (Recommended for Development)¶

# Allow minor updates
version = "^1.2.0"  # 1.x

Aggressive (Not Recommended)¶

# Always use latest (risky)
version = "latest"

Deprecation Policy¶

Deprecation Timeline: 1. Announcement (T+0): Version marked as deprecated 2. Warning Period (T+3 months): Warnings shown in UI/API 3. Sunset (T+6 months): Version removed from catalog 4. Archive (T+6 months): Version archived, read-only access

Deprecation Notice:

{
  "version": "1.0.0",
  "deprecated": true,
  "deprecation_date": "2024-03-01T00:00:00Z",
  "sunset_date": "2024-09-01T00:00:00Z",
  "replacement_version": "1.2.0",
  "migration_guide": "https://docs.skillmeat.io/migrations/1.0-to-1.2"
}

Version Metrics¶

Per-Version Analytics: - Download count by version - Active deployments by version - Adoption rate of new versions - Rollback frequency - Average time to upgrade

Admin Dashboard:

api-schema-validator:
  v1.2.0:
    downloads: 847
    active_deployments: 234
    adoption_rate: 65%
    released: 2024-03-20
  v1.1.0:
    downloads: 1247
    active_deployments: 89
    adoption_rate: 25%
    released: 2024-02-15
  v1.0.0:
    downloads: 523
    active_deployments: 36
    adoption_rate: 10%
    deprecated: true
    sunset_date: 2024-09-01

Description: List available categories and technology stacks.

Authentication & Rate Limiting¶

API Key Authentication:

Authorization: Bearer <api_key>

Rate Limits: - Public: 100 req/min - Authenticated: 1000 req/min - Bulk: 10 req/min

Integration Examples¶

Python SDK¶

from skillmeat_client import SkillMeatClient

client = SkillMeatClient(api_key="your_api_key")

# List skills
skills = client.skills.list(category=["testing"], technology=["python"])

# Get skill
skill = client.skills.get("550e8400-e29b-41d4-a716-446655440000")

# Download
content = client.skills.download(skill_id="...", format="zip")

JavaScript/TypeScript SDK¶

import { SkillMeatClient } from '@skillmeat/client';

const client = new SkillMeatClient({ apiKey: 'your_api_key' });

const skills = await client.skills.list({ category: ['testing'] });
const skill = await client.skills.get('550e8400-e29b-41d4-a716-446655440000');
const content = await client.skills.download({ skillId: '...', format: 'json' });

cURL¶

# List skills
curl "https://api.skillmeat.io/api/v1/public/skills/catalog?category=testing" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Download skill
curl "https://api.skillmeat.io/api/v1/public/skills/{id}/content?format=zip" \
  -H "Authorization: Bearer YOUR_API_KEY" -o skill.zip

Webhooks¶

Events: skill.created, skill.updated, skill.deprecated, skill.removed

Payload:

{
  "event": "skill.updated",
  "timestamp": "2024-03-20T14:30:00Z",
  "data": {
    "skill_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "api-schema-validator",
    "version": "1.2.0",
    "changes": ["Added auto-fix suggestions"]
  }
}

Integration Success Criteria¶

✅ API response time < 200ms (p95)
✅ 99.9% uptime SLA
✅ SDKs for Python, JavaScript, Go
✅ Webhook delivery > 99% success

Add Skill to Team Favorites¶

Actor: Developer or Team Lead

Scenario: Team member discovers useful skill and wants to recommend it to team.

Workflow: 1. Browse skill library, find "API Schema Validator" 2. Click skill card to view details 3. Click "Add to Team Favorites" button (⭐) 4. Optionally add recommendation note: "Essential for our FastAPI projects" 5. System adds skill to team's favorites list 6. Skill appears with "Team Favorite" badge for all team members 7. Team members see skill in "Team Recommended" filter

UI Interaction:

graph LR
    A[Skill Detail View] --> B[Click Star Icon]
    B --> C{Team Member?}
    C -->|Yes| D[Add to Favorites]
    C -->|No| E[Show Error]
    D --> F[Show Success Toast]
    F --> G[Update Badge]
    G --> H[Notify Team]

API Call:

POST /api/v1/teams/{team_id}/favorites
{
  "skill_id": "550e8400-e29b-41d4-a716-446655440000",
  "note": "Essential for our FastAPI projects",
  "added_by": "user_id"
}

Team Favorites Response:

{
  "team_id": "team-123",
  "team_name": "Backend Engineering",
  "favorites": [
    {
      "skill_id": "550e8400-e29b-41d4-a716-446655440000",
      "skill_name": "API Schema Validator",
      "added_by": "john.doe",
      "added_at": "2024-03-20T14:30:00Z",
      "note": "Essential for our FastAPI projects",
      "upvotes": 12,
      "deployments": 8
    }
  ]
}

Benefits: - Curated recommendations from team members - Faster skill discovery for new team members - Visibility into team's preferred tools - Social proof for skill quality

Remove from Team Favorites¶

Actor: Team Lead or Original Contributor

Workflow: 1. Navigate to "Team Favorites" section 2. Find skill to remove 3. Click "Remove from Favorites" (only if added by you or team lead) 4. Confirm removal 5. Skill removed from team favorites list

Alternative Flows¶

Deploy to Multiple Projects¶

Developer selects skills, chooses multiple projects, and system creates separate PRs for each project.

Schedule Deployment¶

Developer selects skills, sets deployment time, and PR is created automatically at scheduled time.

Bulk Update Existing Skills¶

Developer navigates to installed skills, sees available updates, and creates PR with skill updates including changelogs.

Add Custom/Third-Party Skills¶

Actor: Developer or Team Lead

Workflow: 1. Navigate to Skill Library 2. Click "Add Custom Skill" button 3. Choose import method: - GitHub Repository: Enter repo URL (e.g., https://github.com/user/repo) - Local Upload: Upload skill package (ZIP/TAR) - Git URL: Enter git clone URL with credentials 4. System validates skill structure: - Checks for required files (SKILL.md, metadata) - Validates skill format and schema - Scans for security issues 5. License Validation (automatic): - Detects license from LICENSE file or package metadata - Validates against approved open source licenses - Flags incompatible or missing licenses 6. Review validation results: - ✅ Structure valid - ✅ License: MIT (approved) - ⚠️ Security scan: 2 warnings 7. Configure skill metadata: - Name, description, category - Tags and technologies - Visibility (private team / public catalog) 8. Submit for approval (if required) or add directly 9. Skill appears in "Custom Skills" section with badge

Mermaid Diagram:

sequenceDiagram
    actor Dev as Developer
    participant UI as Skill Library UI
    participant API as Backend API
    participant Validator as Skill Validator
    participant License as License Scanner
    participant Security as Security Scanner
    participant DB as Database

    Dev->>UI: Click "Add Custom Skill"
    UI->>Dev: Show import options
    Dev->>UI: Enter GitHub URL
    UI->>API: POST /api/v1/skills/import
    API->>Validator: Validate skill structure
    Validator-->>API: Structure valid ✓

    API->>License: Scan for license
    License->>License: Check LICENSE file
    License->>License: Parse package metadata
    License-->>API: License: MIT (approved) ✓

    API->>Security: Run security scan
    Security-->>API: 2 warnings (non-blocking)

    API->>DB: Store custom skill
    DB-->>API: Skill ID created
    API-->>UI: Validation results
    UI->>Dev: Show results + metadata form
    Dev->>UI: Configure metadata
    UI->>API: POST /api/v1/skills/{id}/metadata
    API->>DB: Update skill metadata
    API-->>UI: Success
    UI->>Dev: Skill added to catalog

API Endpoint:

POST /api/v1/skills/import
Content-Type: application/json
Authorization: Bearer {token}

{
  "source_type": "github",
  "source_url": "https://github.com/user/custom-skill",
  "branch": "main",
  "visibility": "team",
  "auto_approve": false
}

Response:

{
  "skill_id": "custom-skill-001",
  "validation": {
    "structure": {
      "valid": true,
      "required_files": ["SKILL.md", "metadata.json"],
      "missing_files": []
    },
    "license": {
      "detected": "MIT",
      "approved": true,
      "compatible": true,
      "license_url": "https://opensource.org/licenses/MIT"
    },
    "security": {
      "passed": true,
      "warnings": [
        {
          "severity": "low",
          "message": "External API call detected",
          "file": "skill.py",
          "line": 42
        }
      ],
      "errors": []
    }
  },
  "status": "pending_metadata",
  "next_steps": ["configure_metadata", "submit_for_approval"]
}

Benefits: - Extend catalog with organization-specific skills - Import community skills from GitHub - Maintain control over custom skill lifecycle - Ensure license compliance before deployment

Open Source License Validation¶

Actor: System Admin or Compliance Officer

Purpose: Ensure all skills (curated and custom) comply with organization's open source license policy.

Workflow:

Automatic Validation on Import:
System scans for license files (LICENSE, LICENSE.txt, COPYING)
Parses package metadata (package.json, pyproject.toml, pom.xml)
Detects SPDX license identifiers
Cross-references with approved license list
License Detection Methods:
File-based: Parse LICENSE file content
Metadata-based: Extract from package manifests
Header-based: Scan source file headers
API-based: Query GitHub/GitLab license API
Approved License Categories:
Permissive (auto-approved): MIT, Apache-2.0, BSD-3-Clause, ISC
Weak Copyleft (requires review): LGPL-2.1, LGPL-3.0, MPL-2.0
Strong Copyleft (blocked by default): GPL-2.0, GPL-3.0, AGPL-3.0
Proprietary (requires legal review): Custom licenses
Validation Results:
✅ Approved: Skill can be deployed immediately
⚠️ Requires Review: Admin approval needed
❌ Blocked: Cannot be deployed (policy violation)
❓ Unknown: License not detected (manual review)
Admin Review Interface:
View all skills pending license review
See detected license details
Override validation (with justification)
Add license to approved/blocked lists
Generate compliance reports

Mermaid Diagram:

flowchart TD
    A[Skill Import] --> B{License File<br/>Detected?}
    B -->|Yes| C[Parse License Content]
    B -->|No| D[Check Package Metadata]

    C --> E{Match SPDX<br/>Identifier?}
    D --> E

    E -->|Yes| F{Check Against<br/>Policy}
    E -->|No| G[Unknown License]

    F -->|Permissive| H[✅ Auto-Approve]
    F -->|Weak Copyleft| I[⚠️ Requires Review]
    F -->|Strong Copyleft| J[❌ Block]
    F -->|Proprietary| K[⚠️ Legal Review]

    G --> L[Manual Review Queue]
    I --> L
    K --> L

    H --> M[Add to Catalog]
    J --> N[Reject Import]
    L --> O{Admin Decision}
    O -->|Approve| M
    O -->|Reject| N

    style H fill:#90EE90
    style J fill:#FFB6C6
    style I fill:#FFE4B5
    style G fill:#E0E0E0

API Endpoint:

GET /api/v1/skills/{skill_id}/license
Authorization: Bearer {token}

Response:

{
  "skill_id": "custom-skill-001",
  "license": {
    "detected": "MIT",
    "spdx_id": "MIT",
    "category": "permissive",
    "approved": true,
    "detection_method": "license_file",
    "license_text": "MIT License\n\nCopyright (c) 2024...",
    "license_url": "https://opensource.org/licenses/MIT",
    "compatibility": {
      "can_modify": true,
      "can_distribute": true,
      "can_sublicense": true,
      "requires_attribution": true,
      "requires_source_disclosure": false
    }
  },
  "validation": {
    "status": "approved",
    "validated_at": "2024-03-15T10:30:00Z",
    "validated_by": "system",
    "policy_version": "1.2.0"
  },
  "dependencies": [
    {
      "name": "requests",
      "license": "Apache-2.0",
      "approved": true
    },
    {
      "name": "pyyaml",
      "license": "MIT",
      "approved": true
    }
  ]
}

Admin Override Endpoint:

POST /api/v1/skills/{skill_id}/license/override
Content-Type: application/json
Authorization: Bearer {admin_token}

{
  "action": "approve",
  "justification": "Legal team approved for internal use only",
  "restrictions": ["internal_only", "no_redistribution"],
  "expires_at": "2025-12-31T23:59:59Z"
}

License Policy Configuration:

{
  "policy_version": "1.2.0",
  "approved_licenses": [
    "MIT",
    "Apache-2.0",
    "BSD-2-Clause",
    "BSD-3-Clause",
    "ISC"
  ],
  "review_required": [
    "LGPL-2.1",
    "LGPL-3.0",
    "MPL-2.0"
  ],
  "blocked_licenses": [
    "GPL-2.0",
    "GPL-3.0",
    "AGPL-3.0"
  ],
  "allow_unknown": false,
  "require_dependency_scan": true,
  "auto_approve_permissive": true
}

Compliance Reports:

GET /api/v1/admin/compliance/license-report
Authorization: Bearer {admin_token}

Response:

{
  "report_date": "2024-03-15",
  "total_skills": 156,
  "by_license": {
    "MIT": 89,
    "Apache-2.0": 34,
    "BSD-3-Clause": 12,
    "LGPL-3.0": 8,
    "Unknown": 13
  },
  "by_status": {
    "approved": 135,
    "pending_review": 8,
    "blocked": 0,
    "unknown": 13
  },
  "violations": [],
  "pending_reviews": [
    {
      "skill_id": "custom-skill-042",
      "skill_name": "Advanced Analytics",
      "license": "LGPL-3.0",
      "submitted_at": "2024-03-10T14:20:00Z",
      "submitted_by": "john.doe@company.com"
    }
  ]
}

Benefits: - Compliance: Ensure all skills meet legal requirements - Risk Mitigation: Prevent license violations before deployment - Transparency: Clear visibility into license obligations - Automation: Reduce manual legal review burden - Audit Trail: Track all license decisions and overrides - Dependency Scanning: Validate transitive dependencies

Integration with Deployment: - Skills with unapproved licenses cannot be deployed - Deployment PR includes license information - License changes trigger re-validation - Expired overrides block future deployments

Skill Groups: Pre-curated collections of related skills
Team Recommendations: Skills endorsed by team leads
Usage Analytics: Track which skills are most deployed
Rollback: Revert skill deployment via PR
Skill Marketplace: Browse community-contributed skills
Custom Catalogs: Create team-specific skill catalogs

System Architecture¶

graph TB
    subgraph "Frontend Layer"
        A[Skill Library UI<br/>Next.js 15]
        B[Selection Cart<br/>React State]
        C[Git Config Form<br/>React Hook Form]
    end

    subgraph "API Layer"
        D[Marketplace Router<br/>/api/v1/marketplace]
        E[Git Connections Router<br/>/api/v1/git-connections]
        F[Deployments Router<br/>/api/v1/deployments]
    end

    subgraph "Service Layer"
        G[Catalog Service<br/>Filter & Search]
        H[Git Service<br/>PR Creation]
        I[Deployment Service<br/>Orchestration]
    end

    subgraph "Data Layer"
        J[(PostgreSQL<br/>Skills, Projects)]
        K[(Credentials Store<br/>Encrypted Tokens)]
        L[File System<br/>Skill Files]
    end

    subgraph "External Services"
        M[GitHub API]
        N[GitLab API]
        O[Bitbucket API]
    end

    A --> D
    A --> E
    A --> F

    D --> G
    E --> H
    F --> I

    G --> J
    H --> K
    I --> L

    H --> M
    H --> N
    H --> O

    style A fill:#61dafb
    style D fill:#10b981
    style G fill:#8b5cf6
    style J fill:#3b82f6
    style M fill:#f59e0b

Metrics and KPIs¶

Adoption Rate: % of team members using Skill Library
Deployment Frequency: Avg deployments per week per team
Time to Deploy: Avg time from selection to PR creation
PR Merge Rate: % of skill deployment PRs merged
Skill Popularity: Most deployed skills by category
Error Rate: % of failed deployments by error type

Future Enhancements¶

AI-Powered Recommendations: Suggest skills based on project analysis
Skill Dependencies: Auto-include required skills
Version Pinning: Lock skills to specific versions
Rollback Automation: One-click revert via PR
Skill Testing: Run skill validation tests before deployment
Multi-Repo Deployment: Deploy to multiple repos simultaneously
Approval Workflows: Require team lead approval before PR creation
Skill Analytics: Track skill usage and effectiveness metrics

Glossary¶

ICA: Intelligent Coding Assistant (enterprise AI coding platform)
Skill Library: Curated catalog of agent skills for enterprise teams
Skill Group: Pre-packaged collection of related skills
Deployment Set: Snapshot of skills deployed to a project
Manifest: TOML file tracking installed artifacts
Lockfile: TOML file with resolved versions and checksums

References¶

Appendix: Detailed Implementation¶

Detailed Workflow Steps¶

1. Access Skill Library¶

Actor: Developer

Actions: 1. Navigate to SkillMeat web interface 2. Select "Skill Library" from main navigation 3. View curated catalog of agent skills organized by: - Category (e.g., Code Review, Testing, Documentation, Refactoring) - Technology stack (e.g., Python, TypeScript, React, FastAPI) - Complexity level (Beginner, Intermediate, Advanced) - Team recommendations (curated by team leads)

System Response: - Display paginated grid/list of available skills - Show skill metadata: - Name and description - Author/maintainer - Version and last updated - Usage statistics (downloads, ratings) - Compatibility tags - Preview of skill capabilities

UI Wireframe:

graph TB
    subgraph SkillLibrary["Skill Library Interface"]
        A[Search Bar] --> B[Filter Panel]
        B --> C[Category Filters]
        B --> D[Technology Filters]
        B --> E[Complexity Filters]
        B --> F[Team Recommended Toggle]

        G[Skill Grid] --> H["Skill Card A<br/>Rating: 4.8 | Python<br/>Select Button"]
        G --> I["Skill Card B<br/>Rating: 4.5 | TypeScript<br/>Select Button"]
        G --> J["Skill Card C<br/>Rating: 4.9 | Testing<br/>Select Button"]

        K[Selection Panel] --> L["Selected: 0 skills<br/>Deploy Button"]
    end

    style A fill:#e1f5ff
    style G fill:#f0f0f0
    style K fill:#fff3cd

2. Filter and Search Skills¶

Actor: Developer

Actions: 1. Apply filters to narrow skill selection: - Category filter: Select "Code Review" + "Testing" - Technology filter: Select "Python" + "FastAPI" - Complexity filter: Select "Intermediate" - Text search: Enter keywords like "API validation" 2. Sort results by: - Relevance (default) - Most popular - Recently updated - Team recommended

System Response: - Update skill list in real-time based on filter criteria - Display match count (e.g., "Showing 12 of 156 skills") - Highlight matching keywords in search results - Show "No results" state with suggestions if no matches

Filter Combinations:

Example 1:
  categories: [Code Review, Testing]
  technologies: [Python, FastAPI]
  complexity: Intermediate
  result_count: 8 skills

Example 2:
  search: "API validation"
  technologies: [Python]
  team_recommended: true
  result_count: 3 skills

3. Review Skill Details¶

Actor: Developer

Actions: 1. Click on skill card to view detailed information 2. Review skill details panel: - Full description and use cases - Required dependencies - Configuration options - Example usage/screenshots - Changelog and version history - Community ratings and reviews - Compatibility matrix 3. Preview skill files (read-only): - SKILL.md content - Example prompts - Configuration templates

System Response: - Open slide-over panel or modal with full skill details - Display skill metadata in structured format - Show compatibility warnings if any - Provide "Add to Selection" button

Detail View Structure:

# Skill Name: API Schema Validator

## Description
Validates FastAPI request/response schemas against OpenAPI spec...

## Capabilities
- Schema validation
- Type checking
- Error reporting
- Auto-fix suggestions

## Requirements
- Python 3.9+
- FastAPI 0.100+
- Pydantic v2

## Configuration
```yaml
validation_level: strict
auto_fix: true
report_format: json

Compatibility¶

✓ SkillMeat v0.25+ ✓ Enterprise Edition ⚠ Requires Git integration

Reviews (4.8/5.0)¶

"Essential for API development" - @user1

"Caught 15 schema bugs in our codebase" - @user2

### 4. Select Skills for Deployment

**Actor**: Developer

**Actions**:
1. Add individual skills to selection cart
2. Or select pre-curated skill groups:
   - "Python Backend Essentials" (8 skills)
   - "API Development Suite" (12 skills)
   - "Testing & QA Bundle" (6 skills)
3. Review selection summary:
   - Total skills selected: 5
   - Total size: 2.3 MB
   - Estimated deployment time: ~30 seconds
4. Check for conflicts or dependencies
5. Proceed to deployment configuration

**System Response**:
- Update selection counter badge
- Show selection panel with:
  - List of selected skills
  - Remove individual items option
  - Clear all option
  - Conflict warnings (if any)
  - Dependency resolution suggestions

**Selection Panel**:

```mermaid
graph TB
    subgraph "Selection Cart"
        A[Selected Skills: 5] --> B[Clear All Button]

        C[Skill List] --> D[✓ API Schema Validator - Remove]
        C --> E[✓ Code Review Assistant - Remove]
        C --> F[✓ Test Generator - Remove]
        C --> G[✓ Documentation Writer - Remove]
        C --> H[✓ Performance Analyzer - Remove]

        I[Summary] --> J[Total Size: 2.3 MB]
        I --> K[Dependencies: 3 packages]

        L[Configure Deployment Button]
    end

    style A fill:#28a745,color:#fff
    style C fill:#f8f9fa
    style I fill:#e7f3ff
    style L fill:#007bff,color:#fff

5. Configure Git Repository¶

Actor: Developer

Actions: 1. Navigate to "Project Settings" > "Git Integration" 2. Configure repository connection: - Repository URL: https://github.com/company/project-api - Branch: main (or select from dropdown) - Authentication: Select credential set or add new - PR Settings: - Target branch: main - Create branch: skillmeat/deploy-skills-{timestamp} - PR title template: [SkillMeat] Deploy {count} agent skills - PR description template: (customizable) - Auto-assign reviewers: @team-lead, @senior-dev - Labels: skillmeat, agent-skills, enhancement 3. Test connection 4. Save configuration

System Response: - Validate repository URL and credentials - Test write permissions - Fetch branch list - Show connection status (✓ Connected / ✗ Failed) - Save configuration to project settings - Enable "Deploy to Git" option in skill deployment flow

Git Configuration Form:

repository:
  url: https://github.com/company/project-api
  provider: github
  branch: main

authentication:
  type: oauth_token
  credential_id: cred_abc123

pull_request:
  target_branch: main
  source_branch_prefix: skillmeat/deploy-skills-
  title_template: "[SkillMeat] Deploy {count} agent skills"
  description_template: |
    ## Deployed Skills
    {skill_list}

    ## Changes
    - Added {count} agent skills to `.claude/skills/`
    - Updated project configuration

    ## Testing
    - [ ] Verify skill files are present
    - [ ] Run `skillmeat list` to confirm deployment
    - [ ] Test skill activation

  reviewers:
    - team-lead
    - senior-dev

  labels:
    - skillmeat
    - agent-skills
    - enhancement

  draft: false
  auto_merge: false

6. Deploy Skills as Pull Request¶

Actor: Developer

Actions: 1. Click "Deploy to Git" button from selection panel 2. Review deployment summary: - Target repository and branch - Skills to be deployed (5 items) - File changes preview - PR metadata 3. Customize PR details (optional): - Modify title/description - Add/remove reviewers - Adjust labels - Set as draft PR 4. Confirm deployment 5. Monitor deployment progress

System Response: 1. Preparation Phase (5-10s): - Create deployment branch - Generate skill files in .claude/skills/ directory - Update project manifest - Create lockfile entries 2. Commit Phase (2-3s): - Stage all changes - Create commit with message - Push to remote repository 3. PR Creation Phase (3-5s): - Create pull request via Git provider API - Assign reviewers - Apply labels - Add description with skill details 4. Completion: - Display PR URL - Show success notification - Provide quick actions (View PR, Deploy More, Done)

Deployment Progress:

stateDiagram-v2
    [*] --> Preparing: Start Deployment
    Preparing --> CreatingBranch: Initialize
    CreatingBranch --> GeneratingFiles: Branch Created
    GeneratingFiles --> UpdatingManifest: Files Generated (5/5)
    UpdatingManifest --> Committing: Manifest Updated
    Committing --> Pushing: Changes Committed
    Pushing --> CreatingPR: Pushed to Remote
    CreatingPR --> Success: PR Created
    CreatingPR --> Failed: Error
    Success --> [*]
    Failed --> [*]

    note right of Success
        PR #1234 Created
        Branch: skillmeat/deploy-skills-20260415
        Reviewers: @team-lead, @senior-dev
    end note

7. Review and Merge Pull Request¶

Actor: Team Lead (or Developer with merge permissions)

Actions: 1. Receive PR notification (email/Slack/GitHub) 2. Navigate to PR in Git provider interface 3. Review changes: - Skill files added to .claude/skills/ - Manifest updates - Lockfile entries - No unexpected changes 4. Run CI/CD checks (if configured): - Skill validation tests - Manifest integrity checks - No conflicts with existing skills 5. Approve and merge PR 6. Delete deployment branch (optional)

System Response: - PR appears in Git provider with all metadata - CI/CD pipeline runs automatically (if configured) - Skills become available in project after merge - SkillMeat detects merge and updates project status

Pull Request Content:

# [SkillMeat] Deploy 5 agent skills

## Deployed Skills

1. **API Schema Validator** (v1.2.0)
   - Validates FastAPI schemas against OpenAPI spec
   - Path: `.claude/skills/api-schema-validator/`

2. **Code Review Assistant** (v2.0.1)
   - Automated code review with best practices
   - Path: `.claude/skills/code-review-assistant/`

3. **Test Generator** (v1.5.3)
   - Generates unit tests from code
   - Path: `.claude/skills/test-generator/`

4. **Documentation Writer** (v1.8.0)
   - Auto-generates API documentation
   - Path: `.claude/skills/documentation-writer/`

5. **Performance Analyzer** (v1.3.2)
   - Analyzes code performance bottlenecks
   - Path: `.claude/skills/performance-analyzer/`

## Changes

- Added 5 agent skills to `.claude/skills/`
- Updated `.claude/manifest.toml` with skill entries
- Updated `.claude/lockfile.toml` with resolved versions
- Total files changed: 47 files (+2,847 lines)

## Testing Checklist

- [ ] Verify skill files are present in `.claude/skills/`
- [ ] Run `skillmeat list` to confirm deployment
- [ ] Test skill activation with `skillmeat skill activate <name>`
- [ ] Verify no conflicts with existing project configuration

## Deployment Info

- **Deployed by**: @developer-user
- **Deployment time**: 2026-04-15 21:06:30 UTC
- **SkillMeat version**: v0.25.0
- **Edition**: Enterprise

---

*This PR was automatically generated by SkillMeat Skill Library*

File Structure After Deployment¶

project-api/
├── .claude/
│   ├── manifest.toml                    # Updated with new skills
│   ├── lockfile.toml                    # Updated with resolved versions
│   └── skills/
│       ├── api-schema-validator/
│       │   ├── SKILL.md
│       │   ├── prompts/
│       │   └── config.toml
│       ├── code-review-assistant/
│       │   ├── SKILL.md
│       │   ├── prompts/
│       │   └── config.toml
│       ├── test-generator/
│       │   ├── SKILL.md
│       │   ├── prompts/
│       │   └── config.toml
│       ├── documentation-writer/
│       │   ├── SKILL.md
│       │   ├── prompts/
│       │   └── config.toml
│       └── performance-analyzer/
│           ├── SKILL.md
│           ├── prompts/
│           └── config.toml
├── src/
├── tests/
└── README.md

Manifest Updates¶

Before Deployment (.claude/manifest.toml):

[tool.skillmeat]
version = "1.0.0"
project_name = "project-api"

[[artifacts]]
name = "existing-skill"
type = "skill"
source = "company/skills/existing-skill"
version = "1.0.0"
scope = "local"

After Deployment (.claude/manifest.toml):

[tool.skillmeat]
version = "1.0.0"
project_name = "project-api"

[[artifacts]]
name = "existing-skill"
type = "skill"
source = "company/skills/existing-skill"
version = "1.0.0"
scope = "local"

[[artifacts]]
name = "api-schema-validator"
type = "skill"
source = "skillmeat/catalog/api-schema-validator"
version = "1.2.0"
scope = "local"
deployed_at = "2026-04-15T21:06:30Z"
deployed_by = "developer-user"
deployed_via = "skill-library-pr"

[[artifacts]]
name = "code-review-assistant"
type = "skill"
source = "skillmeat/catalog/code-review-assistant"
version = "2.0.1"
scope = "local"
deployed_at = "2026-04-15T21:06:30Z"
deployed_by = "developer-user"
deployed_via = "skill-library-pr"

# ... (3 more skills)

Technical Implementation¶

API Endpoints¶

GET /api/v1/marketplace/catalog
  - Fetch curated skill catalog
  - Supports filtering and pagination

POST /api/v1/git-connections
  - Configure Git repository connection
  - Store credentials securely

POST /api/v1/deployments/create-pr
  - Create deployment pull request
  - Payload: skill IDs, repo config, PR metadata

GET /api/v1/deployments/{id}/status
  - Poll deployment progress
  - Returns: phase, progress %, errors

Database Schema¶

-- Git connections per project
CREATE TABLE git_connections (
  id UUID PRIMARY KEY,
  project_id UUID REFERENCES projects(id),
  repository_url TEXT NOT NULL,
  provider TEXT NOT NULL, -- github, gitlab, bitbucket
  branch TEXT NOT NULL,
  credential_id UUID REFERENCES credentials(id),
  pr_config JSONB, -- PR template, reviewers, labels
  created_at TIMESTAMP,
  updated_at TIMESTAMP
);

-- Deployment history
CREATE TABLE skill_deployments (
  id UUID PRIMARY KEY,
  project_id UUID REFERENCES projects(id),
  git_connection_id UUID REFERENCES git_connections(id),
  skill_ids UUID[], -- Array of deployed skill IDs
  pr_url TEXT,
  pr_number INTEGER,
  branch_name TEXT,
  status TEXT, -- pending, success, failed
  deployed_by UUID REFERENCES users(id),
  deployed_at TIMESTAMP,
  merged_at TIMESTAMP
);

Security Considerations¶

Credential Storage: OAuth tokens encrypted at rest using AES-256
Permission Checks: Verify user has write access to repository
Rate Limiting: Max 10 deployments per hour per user
Audit Logging: All deployments logged with user, timestamp, skills
PR Validation: Verify PR content matches requested skills (no injection)

Document Version: 1.0.0
Last Updated: 2026-04-15
Author: SkillMeat Documentation Team
Status: Draft