DEV Community

Hagicode
Hagicode

Posted on • Originally published at docs.hagicode.com

Why Use Skillsbase to Maintain Your Own Skills Collection Repository

#skills #skillsbase #cli #automation

Why Use Skillsbase to Maintain Your Own Skills Collection Repository

It's kind of funny—the era of AI programming is here, and we have more and more Agent Skills at our disposal, but with that comes more and more trouble. This article is about how we use skillsbase to solve these problems.

Background

In the AI programming era, developers need to maintain an increasing number of Agent Skills—these are reusable instruction sets for extending the capabilities of coding assistants like Claude Code, OpenCode, Cursor, and more. However, as the number of skills grows, a practical issue gradually emerges:

Actually, it's not really a big problem—just that when you have too many things, managing them becomes troublesome.

Skills are scattered, high management cost

  • Local skills are scattered across multiple locations: ~/.agents/skills/, ~/.claude/skills/, ~/.codex/skills/.system/, etc.
  • Different locations may have naming conflicts (e.g., skill-creator exists in both user and system directories)
  • Lack of a unified management interface, making backup and migration difficult

This is quite annoying. Sometimes you don't even know where a particular skill is—it's like losing something, and finding it takes effort.

Lack of standardized maintenance processes

  • Manual skill copying is error-prone and difficult to track sources
  • No unified validation mechanism to ensure skill repository integrity
  • Difficult to synchronize and share skill collections during team collaboration

Manual operations are always error-prone. After all, human memory is limited—who can remember where so many things came from?

Unable to meet reproducibility requirements

  • When switching development machines, all skills need to be reconfigured
  • CI/CD environments cannot automatically validate and synchronize skill repositories

Changing computers means starting all over again. How should I put it—it's as troublesome as moving. Every time you have to re-adapt to the new environment and reconfigure everything.

To address these pain points, we tried multiple solutions: from manual copying to script automation, from direct directory management to global installation then cleanup. Each solution had its own flaws—either unable to guarantee consistency, or polluting the environment, or difficult to use in CI.

Actually, we took quite a few detours.

Eventually, we found a more elegant solution—skillsbase. The core idea of this solution is: first install and validate locally, then transform the structure and write to the repository, and finally uninstall temporary files. This ensures repository content matches actual installation results without polluting the global environment.

It sounds simple, but we stepped into plenty of pits before figuring it out.

About HagiCode

The solution shared in this article comes from our practical experience in the HagiCode project.

HagiCode is an AI code assistant project. During development, we needed to maintain a large number of Agent Skills to extend various coding capabilities. These actual needs prompted us to develop the skillsbase toolset to standardize skill repository management.

Actually, this thing wasn't thought up out of thin air—we were forced into it. More skills naturally require management. Problems encountered during management naturally need solutions. Step by step, we've arrived where we are today.

If you're interested in HagiCode, you can visit the official website to learn more or check the source code on GitHub.

Analysis

Technical Challenges

To establish a maintainable skill collection repository, the following core issues need to be addressed:

  1. Unified namespace conflicts: When multiple sources have skills with the same name, how do we avoid overwrites?
  2. Source traceability: How do we record the source of each skill for future updates and auditing?
  3. Synchronization and validation: How do we ensure repository content matches actual installation results?
  4. Automation integration: How do we integrate with CI/CD workflows for automatic synchronization and validation?

These problems seem simple, but each one is enough to give you a headache. But then again, what isn't difficult?

Design Trade-offs

Solution 1: Direct directory copying

Pros: Simple implementation
Cons: Cannot guarantee consistency with actual skills CLI installation results

We actually thought about this solution. But later we discovered that CLI installation might have some preprocessing logic, and direct copying skips that. The result is that what you copy is different from what you actually install—that's a problem.

Solution 2: Global installation then cleanup

Pros: Can validate installation process
Cons: Pollutes execution environment, difficult to maintain consistency between CI and local results

This solution is worse. Global installation pollutes the environment. Even more troublesome is that CI and local environments are difficult to keep consistent, leading to "works locally, fails in CI" problems. Who understands this feeling?

Solution 3: Local install → Transform → Uninstall (final solution)

This is the solution adopted by skillsbase:

  • First use npx skills to install skills to a temporary location
  • Transform directory structure and add source metadata
  • Write to target repository
  • Finally uninstall temporary files

This solution ensures repository content matches actual consumer installation results, without polluting the global environment. The transformation process can be standardized and supports idempotent operations.

Actually, we didn't think of this solution from the beginning. It's just that after enough trial and error, you naturally know what's feasible and what isn't.

Architecture Decisions

Decision Choice Rationale
Runtime Node.js ESM No build step needed, .mjs suffices for file system orchestration
Config format YAML (sources.yaml) Strong readability, supports manual maintenance
Naming strategy Namespace prefix User skills keep original names, system skills get system- prefix
Workflow add modifies manifest → sync executes sync Single sync engine, avoid duplicate rule implementations
File management Managed file markers Add comment headers, support safe overwriting

These decisions, when you get down to it, are all for one goal: make things simple. After all, simplicity is king.

Solution

CLI Architecture

The skillsbase CLI provides four core commands:

skillsbase
├── init          # Initialize repository structure
├── sync          # Synchronize skill content
├── add           # Add new skills
└── github_action # Generate GitHub Actions configuration
Enter fullscreen mode Exit fullscreen mode

Not many commands, but enough. After all, with tools—good enough is good enough.

Core Workflow 

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│    init     │───▶│    add      │───▶│    sync     │───▶│github_action│
│  初始化仓库  │    │  添加来源   │    │  同步内容   │    │  生成 CI    │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
Enter fullscreen mode Exit fullscreen mode

Step by step, no rushing.

Sync Flow Design 

sources.yaml → 解析来源 → npx skills 安装 → 转换结构 → 写入 skills/ → 卸载临时文件
                              ↓
                        .skill-source.json (来源元数据)
Enter fullscreen mode Exit fullscreen mode

This flow design is fairly clear. At least when I look at it myself, I can understand what each step is doing.

Repository Structure 

repos/skillsbase/
├── sources.yaml              # Source manifest (single source of truth)
├── skills/                   # Skills directory
│   ├── frontend-design/      # User skill
│   ├── skill-creator/        # User skill
│   └── system-skill-creator/ # System skill (with prefix)
├── scripts/
│   ├── sync-skills.mjs       # Sync script
│   └── validate-skills.mjs   # Validation script
├── docs/
│   └── maintainer-workflow.md # Maintainer documentation
└── .github/
    ├── workflows/
    │   └── skills-sync.yml   # CI workflow
    └── actions/
        └── skillsbase-sync/
            └── action.yml     # Reusable Action
Enter fullscreen mode Exit fullscreen mode

A lot of files, but still okay. After all, with clear organizational structure, maintenance becomes convenient.

Practice

Initialize Skills Repository 

# 1. Create empty repository
mkdir repos/myskills && cd repos/myskills
git init

# 2. Initialize using skillsbase
npx skillsbase init

# Output:
# [1/4] create manifest ................. done
# [2/4] create scripts .................. done
# [3/4] create docs ..................... done
# [4/4] create github workflow .......... done
#
# next: skillsbase add <skill-name>
Enter fullscreen mode Exit fullscreen mode

This step generates a bunch of files, but don't worry—they're all auto-generated. Next, you can start adding skills.

Add Skills 

# Add single skill (automatically executes sync)
npx skillsbase add frontend-design --source vercel-labs/agent-skills

# Add from local source
npx skillsbase add documentation-writer --source /home/user/.agents/skills

# Output:
# source: first-party ......... updated
# target: skills/frontend-design ... synced
# status: 1 skill added, 0 removed
Enter fullscreen mode Exit fullscreen mode

Adding skills is quite simple—one command is enough. Sometimes you encounter unexpected situations like poor network or permission issues. But these are minor issues, take it slow.

Sync Skills 

# Execute sync (reconcile all sources)
npx skillsbase sync

# Only check for drift (don't modify files)
npx skillsbase sync --check

# Allow missing sources (CI scenario)
npx skillsbase sync --allow-missing-sources
Enter fullscreen mode Exit fullscreen mode

When syncing, the system checks all sources defined in sources.yaml and reconciles them with the content in the skills/ directory. Update if there are differences, skip if there are none. This avoids "configuration changed but files didn't" problems.

Generate CI Configuration 

# Generate workflow
npx skillsbase github_action --kind workflow

# Generate action
npx skillsbase github_action --kind action

# Generate all
npx skillsbase github_action --kind all
Enter fullscreen mode Exit fullscreen mode

CI configuration is also auto-generated. You just need to adjust some details yourself, like trigger conditions, runtime environment, etc. But these aren't difficult.

sources.yaml Configuration Example 

# Skills root directory configuration
skillsRoot: skills/
metadataFile: .skill-source.json

# Source definitions
sources:
  # First-party: local user skills
  first-party:
    type: local
    path: /home/user/.agents/skills
    naming: original  # Keep original name
    includes:
      - documentation-writer
      - frontend-design
      - skill-creator

  # System: system-provided skills
  system:
    type: local
    path: /home/user/.codex/skills/.system
    naming: prefix-system  # Add system- prefix
    includes:
      - imagegen
      - openai-docs
      - skill-creator  # Will become system-skill-creator

  # Remote: third-party repository
  vercel:
    type: remote
    url: vercel-labs/agent-skills
    naming: original
    includes:
      - web-design-guidelines
Enter fullscreen mode Exit fullscreen mode

This configuration file is the core of the entire system. All sources are defined here. Change this, and the next sync will take effect. So this is a "single source of truth."

.skill-source.json Metadata Example 

{
  "source": "first-party",
  "originalPath": "/home/user/.agents/skills/documentation-writer",
  "originalName": "documentation-writer",
  "targetName": "documentation-writer",
  "syncedAt": "2026-04-07T00:00:00.000Z",
  "version": "unknown"
}
Enter fullscreen mode Exit fullscreen mode

Each skill directory has this file, recording its source information. This way, when problems occur later, you can quickly locate where it came from and when it was synced.

Security and Validation 

# Validate repository structure
node scripts/validate-skills.mjs

# Validate using skills CLI
npx skills add . --list

# Check for updates
npx skills check
Enter fullscreen mode Exit fullscreen mode

Validation—important when it's important, unnecessary when it's not. But for safety's sake, running it occasionally doesn't hurt. After all, who knows what unexpected things might happen?

GitHub Actions Integration 

# .github/workflows/skills-sync.yml
name: Skills Sync

on:
  push:
    paths:
      - 'sources.yaml'
      - 'skills/**'
  workflow_dispatch:

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Validate repository
        run: |
          npx skills add . --list
          node scripts/validate-skills.mjs
      - name: Sync check
        run: npx skillsbase sync --check
Enter fullscreen mode Exit fullscreen mode

After CI integration, every change to sources.yaml or the skills/ directory automatically triggers validation. This avoids "changed locally but forgot to sync" problems.

Best Practices

  1. Naming conflict handling: System skills uniformly get the system- prefix. This preserves all skills while avoiding naming conflicts.
  2. Idempotent operations: All commands support repeated execution—running sync multiple times has no side effects. This is particularly important in CI.
  3. Managed files: Generated files contain a # Managed by skillsbase CLI comment for easy identification and management. These files can be safely overwritten—manual modifications won't be preserved.
  4. Non-interactive mode: CI environments use deterministic behavior by default and won't be interrupted by interactive prompts. All configuration is declared through sources.yaml.
  5. Source traceability: Each skill has a .skill-source.json recording source information, enabling quick localization when problems occur.

Team Collaboration 

# Team members install shared skill library
npx skills add your-org/myskills -g --all

# Local clone validation
git clone https://github.com/your-org/myskills.git
cd myskills
npx skills add . --list
Enter fullscreen mode Exit fullscreen mode

By managing skill repositories through Git, team members can easily synchronize skill collections, ensuring everyone uses the same version of tools and configurations.

This is particularly useful in team collaboration—no more "it works on my machine but not yours" situations. After all, with unified environments, problems are halved.

Summary

The core value of using skillsbase to maintain a skills collection repository lies in:

  • Security: Source validation, conflict detection, managed file protection
  • Maintainability: Unified entry point, idempotent operations, configuration as documentation
  • Standardization: Unified directory structure, naming conventions, metadata format
  • Automation: CI/CD integration, automatic synchronization, automatic validation

Through this solution, developers can manage their Agent Skills like npm packages, achieving a reproducible, shareable, maintainable skill repository system.

The tools and processes shared in this article are exactly what we developed through actual trial and error during HagiCode development. If you find this solution valuable, it means our engineering direction is correct—and then HagiCode itself is worth paying attention to.

After all, good tools deserve to be used by more people.

References

If this article helps you:

This article first appeared on the HagiCode Blog

Original Article & License

Thanks for reading. If this article helped, consider liking, bookmarking, or sharing it.
This article was created with AI assistance and reviewed by the author before publication.

Top comments (0)