Skill Repository - Z-M-Huang/openhive GitHub Wiki

Skill Repository

The skill repository enables teams to discover and adopt existing skills from the Vercel skills ecosystem rather than creating every skill from scratch. When a user requests a new capability, the agent searches for matching skills, presents options with trust signals, and tailors the best match to OpenHive's format and the user's specific needs.

This page covers the skill repository and adoption flow. For skill file format and usage, see Skills. For the architectural decision, see Architecture-Decisions#ADR-26.

Overview

When a user requests a new skill or trigger, the agent follows a search-first approach: fully understand what the user wants, then search the Vercel skills ecosystem (skills.sh) for matching skills. If a match scores 60% or higher, the agent downloads the SKILL.md file, tailors it to OpenHive's skill format and the user's specific requirements, and writes it locally. If no match reaches the 60% threshold, the agent creates the skill from scratch. In either case, the skill is pre-assumed to work and then verified through testing.

The Vercel Skills Ecosystem

The Vercel skills ecosystem centers on skills.sh, a central registry hosting 269+ skills with 91K+ installs across the community.

Format. Each skill is a single SKILL.md file with YAML frontmatter containing name and description fields, followed by a markdown body with the skill's guidelines and procedures.

Contributors. The ecosystem includes skills from major publishers:

  • vercel-labs -- official Vercel Labs skills
  • anthropics -- Anthropic-published skills
  • Community -- independent contributors and organizations

Cross-agent compatibility. Skills on skills.sh are designed to work across 40+ coding agents including Claude Code, Cursor, Copilot, Windsurf, and others. The simple SKILL.md format makes skills portable across agent platforms.

OpenHive's role. OpenHive joins this ecosystem as a consumer. The agent searches skills.sh for relevant skills, downloads them, and converts them to OpenHive's richer skill format during the tailoring step.

Repository Sources

Repository sources are pre-defined in the container image, following the same immutability model as /app/system-rules/. The admin controls what sources agents can access.

Source Type Description
skills.sh search API Primary Full-text search across the entire Vercel skills registry
vercel-labs/agent-skills Curated Official Vercel Labs skill collection
anthropics/skills Curated Anthropic-published skills

Sources are not user-configurable. Changing the source list requires a container rebuild, ensuring the same trust boundary as system rules. This prevents individual teams or users from pointing the agent at untrusted skill repositories.

Trust Signals

Trust signals are derived from ecosystem data and presented to the user when showing search results. No custom trust tier system is needed -- the ecosystem's own metrics serve as quality indicators.

Signal How Used Example
Install count Higher installs = more battle-tested 787K installs (find-skills) = highly trusted
Source reputation Known publishers = verified quality vercel-labs, anthropics = high trust
GitHub stars Community validation and interest 1K+ stars = established project
Recency Last update date indicates maintenance Updated within 6 months = actively maintained

The LLM presents these signals when showing matches so the user can make an informed decision:

"Found 'frontend-design' from Anthropic (222K installs). Shall I adapt this?"

Format Conversion

Skills from the Vercel ecosystem use a different format than OpenHive skills. Conversion is a two-phase process: (1) extract/create plugin tools for all external operations (plugin-first per ADR-39), then (2) generate the OpenHive skill markdown referencing those plugins. The LLM handles both phases during the tailoring step — it reads the Vercel SKILL.md content as reference material and generates plugins + skill adapted to the user's needs. After creation, the skill is wired to a subagent.

Vercel SKILL.md format is intentionally simple: YAML frontmatter with name and description fields, followed by freeform markdown with guidelines and procedures.

OpenHive skill format is structured with explicit sections: Required Tools, Purpose, Steps, Inputs, Outputs, and Error Handling. See Skills#Skill Definition Format for the full section breakdown.

The LLM bridges these formats during the tailoring step by extracting tool requirements from scripts, generating structured steps from freeform content, and adapting to the user's specific context.

The Vercel format is intentionally simple (name, description, and freeform markdown), while OpenHive's format is structured (Required Tools, Purpose, Steps, Inputs, Outputs, Error Handling). The LLM bridges this gap by:

  1. Extracting tool requirements — Scripts in the Vercel skill become TypeScript tool() definitions written to .run/teams/{name}/plugins/
  2. Generating tool names — From script filenames or H1 action verbs (e.g., "Deploy Service" → deploy_service)
  3. Declaring tool dependencies — The ## Required Tools section lists generated tools

Tool generation from scripts:

  • Bash scripts → TypeScript tool with Zod schema for parameters
  • No scripts → Tool generated from H1 action verb + first paragraph
  • Multiple scripts → Multiple tools with descriptive suffixes

search_skill_repository Tool

The search_skill_repository tool accepts a natural language query and optional filters:

Parameter Type Required Description
query string Yes Natural language description of the desired capability
filters.source string No Filter by source repository (e.g., "anthropics")
filters.min_installs number No Minimum install count threshold

Returns an array of match objects, each containing: name, description, source (repository path), installs (count), match_score (0-1), and skill_url (GitHub link to the SKILL.md file). Only results scoring ≥ 60% are returned.

Behavior:

  • Only results with match score >= 60% are returned
  • Read-only -- no side effects, no writes
  • Queries the skills.sh search API
  • Falls back gracefully if skills.sh is unreachable (returns empty array, logs warning)

See Organization-Tools#skill-repo-tool.ts for tool registration and guardrails.

Skill Adoption Flow

The full adoption flow from user request to tested skill with plugin tool generation:

Match Evaluation Decision Tree

Match Result Action
No results (< 60%) Create skill from scratch using team context (AC-2)
One result ≥ 80% Exact match — proceed to tool generation (AC-1)
Multiple results ≥ 80% Present all matches, require user selection (AC-4)
Results 60-79% Partial match — present with confidence %, offer 'create from scratch' option (AC-3)

Tool Generation Flow

  1. Understand intent -- The LLM fully grasps what the user needs before searching
  2. Search -- The LLM calls search_skill_repository("API health monitoring")
  3. Evaluate -- Apply match threshold and present options per decision tree above
  4. User decides -- User picks a match, or says "create from scratch"
  5. Download -- Tool fetches the full SKILL.md content from the GitHub source
  6. Extract scripts -- Identify bash scripts, code blocks, or H1 action verbs
  7. Generate tool -- Create TypeScript tool() definition with Zod schema:
    • From scripts: Extract parameters → generate Zod schema → wrap in tool()
    • No scripts: Use H1 action verb for tool name → generate from skill intent (AC-5)
  8. Verify tool -- TypeScript typecheck + security scan (see Organization-Tools#Plugin Tool Guards)
  9. Write tool -- Save to .run/teams/{name}/plugins/{tool_name}.ts
  10. Tailor skill -- Convert to OpenHive format with ## Required Tools section
  11. Write skill -- Save to .run/teams/{name}/skills/{skill}.md
  12. Wire to subagent -- Add the skill to the target subagent's ## Skills section in subagents/{name}.md (see Skills#4-Step Creation Workflow)
  13. Test -- Invoke on a sample task via the subagent
flowchart TD
    A[User requests skill] --> B[Understand intent]
    B --> C[search_skill_repository]
    C --> D{Match confidence}
    D -->|≥ 80% single| E[Exact match AC-1]
    D -->|≥ 80% multiple| F[Present options AC-4]
    D -->|60-79%| G[Partial match AC-3]
    D -->|< 60%| H[Create from scratch AC-2]
    F --> I{User selection}
    G --> I
    I -->|Select match| E
    I -->|Create from scratch| H
    E --> J[Download SKILL.md]
    H --> K[Generate tool from team context]
    J --> L{Has scripts?}
    L -->|Yes| M[Extract scripts → generate tool]
    L -->|No| N[Use H1 verb → generate tool AC-5]
    M --> O[Verify: typecheck + security scan]
    N --> O
    K --> O
    O --> P{Verification passes?}
    P -->|Yes| Q[Write to plugins/]
    P -->|No| R[Error with fix guidance]
    R --> K
    Q --> S[Write skill with Required Tools]
    S --> T[Test]

AC-2: No Match (LLM Creates from Scratch)

When no matching skill exists, the LLM receives team context:

  • Existing tools in .run/teams/{name}/plugins/
  • Team naming convention: {team_name}.{action}
  • Last 3 skill markdowns
  • Team configuration (allowed_tools, etc.)

The generated tool must:

  • Pass TypeScript typecheck
  • Export valid Tool interface: {description, parameters, execute}
  • Have Zod schema with at least 1 input field

AC-5: Scriptless Skill

When a skill has no executable scripts:

  • Tool name extracted from H1 action verb (e.g., "Deploy Service" → deploy_service)
  • Tool description from first paragraph
  • Original skill preserved with ## Required Tools section added

Graceful Degradation

If skills.sh is unreachable (network issues, downtime, timeout), the agent:

  1. Logs a warning noting the repository is unavailable
  2. Proceeds to create the skill from scratch
  3. Never blocks or fails the user's request due to repository unavailability

The skill repository is an optimization, not a dependency. The agent can always fall back to creating skills from its own knowledge of the user's requirements.

Security Model

The skill repository follows these security boundaries:

  • Sources are pre-defined in the container. Administrators control which repositories agents can search. Users and teams cannot add arbitrary sources.
  • Trust signals are visible to the user. Install counts, source reputation, and other signals are presented transparently so users can evaluate skill quality.
  • User confirms before adoption. The agent always presents matches and waits for user approval before downloading and tailoring. No skill is adopted without explicit user consent.
  • LLM reads content as reference. The downloaded SKILL.md is read by the LLM as reference material -- the same trust boundary as any other markdown the LLM processes. The skill content influences the generated output but is not executed directly.
  • No executable code distribution. Skills are markdown procedures (instructions for the LLM), not executable scripts or binaries. The repository distributes guidance, not code.