Why Use Skillsbase to Maintain Your Own Skills Collection Repository

2026年4月7日

Why Use Skillsbase to Maintain Your Own Skills Collection Repository

It is kind of funny when you think about it: the era of AI programming has arrived, and the Agent Skills we keep on hand are becoming more and more numerous. But along with that comes more and more hassle. This article is about how we used skillsbase to solve those problems.

Background

In the age of AI programming, developers need to maintain an increasing number of Agent Skills - reusable instruction sets that extend the capabilities of coding assistants such as Claude Code, OpenCode, and Cursor. However, as the number of skills grows, a practical problem gradually emerges:

It is not exactly a major problem, but once you have too many things, managing them becomes troublesome.

Skills are scattered across different locations, making management costly

Local skills are scattered in multiple places: ~/.agents/skills/, ~/.claude/skills/, ~/.codex/skills/.system/, and so on
Different locations may have naming conflicts, for example skill-creator existing in both the user directory and the system directory
There is no unified management entry point, which makes backup and migration difficult

This part is genuinely annoying. Sometimes you do not even know where a certain skill actually is. It feels like losing something and then struggling to find it.

Lack of a standardized maintenance workflow

Manually copying skills is error-prone and makes it difficult to trace their origins
Without a unified validation mechanism, there is no guarantee that the skill repository remains complete
During team collaboration, synchronizing and sharing a skill collection is difficult

Manual work is always prone to mistakes. Human memory is limited, after all. Who can remember where every single thing came from?

Failing to meet reproducibility requirements

When switching development machines, all skills need to be configured again
In CI/CD environments, the skill repository cannot be validated and synchronized automatically

Changing to a different computer means doing everything all over again. It feels, in a way, just like moving house - troublesome every single time. You have to adapt to the new environment and reconfigure everything again.

To address these pain points, we tried many different approaches: from manual copying to scripted automation, from directly managing directories to globally installing and then recovering files. Each approach had its own flaws. Some could not guarantee consistency, some polluted the environment, and some were hard to use in CI.

We definitely took quite a few detours.

In the end, we found a more elegant solution: skillsbase. The core idea behind this approach is to install and validate locally first, then convert the structure and write it into the repository, and finally uninstall the temporary files. This ensures that the repository contents match the actual installation result while avoiding pollution of the global environment.

It sounds simple when you put it that way, but we only figured it out after stepping into quite a few pitfalls.

About HagiCode

The solution shared in this article comes from our hands-on experience in the HagiCode project.

HagiCode is an AI coding assistant project. During development, we need to maintain a large number of Agent Skills to extend various coding capabilities. These real-world needs are exactly what pushed us to build the skillsbase toolset for standardized management of skill repositories.

This was not invented out of thin air. We were pushed into it by real needs. Once the number of skills grows, management naturally becomes necessary. When problems appear during management, solutions become necessary too. Step by step, that is how we got here.

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

Analysis

Technical challenges

To build a maintainable skills collection repository, the following core problems need to be solved:

Unified namespace conflicts: when multiple sources contain skills with the same name, how do we avoid overwriting them?
Source traceability: how do we record the source of each skill for future updates and audits?
Synchronization and validation: how do we ensure that repository contents stay consistent with the actual installation results?
Automation integration: how do we integrate with CI/CD workflows to enable automatic synchronization and validation?

These problems may look simple, but every single one of them is a headache. Then again, what worthwhile work is ever easy?

Design trade-offs

Option 1: Copy directories directly

Pros: simple to implement Cons: cannot guarantee consistency with the actual installation result of the skills CLI

We did think about this approach. Later, however, we realized that the CLI may apply some preprocessing logic during installation. Direct copying skips that step. As a result, what you copy is not the same as what is actually installed, and that becomes a problem.

Option 2: Install globally and then recover

Pros: the installation process can be validated Cons: pollutes the execution environment, and it is hard to keep CI and local results consistent

This approach is even worse. A global installation pollutes the environment. More importantly, it is difficult to keep the CI environment consistent with the local environment, which leads to the classic “works on my machine, fails in CI” problem. Anyone who has dealt with that knows how painful it is.

Option 3: Local install -> convert -> uninstall (final solution)

This is the approach adopted by skillsbase:

First install skills into a temporary location with npx skills
Convert the directory structure and add source metadata
Write the result into the target repository
Finally uninstall the temporary files

This approach ensures that repository contents are consistent with the actual installation results seen by consumers, avoids polluting the global environment, standardizes the conversion process, and supports idempotent operations.

This solution was not obvious from the beginning either. We simply learned through enough trial and error what works and what does not.

Architecture decisions

Decision Item	Choice	Reason
Runtime	Node.js ESM	No build step required; `.mjs` is enough to orchestrate the file system
Configuration format	YAML (`sources.yaml`)	Highly readable and suitable for manual maintenance
Naming strategy	Namespace prefix	User skills keep their original names, while system skills receive the `system-` prefix
Workflow	`add` updates the manifest -> `sync` executes synchronization	A single synchronization engine avoids implementing the same rules twice
File management	Managed file markers	Add a comment header to support safe overwrites

These decisions all come down to one goal: making things simple. Simplicity wins in the end.

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

There are not many commands, but they are enough. A tool only needs to be useful.

Core workflow

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│    init     │───▶│    add      │───▶│    sync     │───▶│github_action│
│ initialize  │    │ add source  │    │ sync content│    │ generate CI │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘

Take it one step at a time. No need to rush.

Synchronization flow design

sources.yaml -> parse sources -> npx skills install -> convert structure -> write to skills/ -> uninstall temporary files
                              ↓
                        .skill-source.json (source metadata)

This workflow is fairly clear. At least when I look at it, 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       # Synchronization 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

There are quite a few files, but that is fine. Once the structure is organized clearly, maintenance becomes much easier.

Practice

Initialize a skills repository

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

# 2. Initialize it with 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>

This step generates a lot of files, but there is no need to worry - they are all generated automatically. After that, you can start adding skills.

Add skills

# Add a single skill (this automatically triggers synchronization)
npx skillsbase add frontend-design --source vercel-labs/agent-skills

# Add from a 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

Adding a skill is very simple. One command is enough. Sometimes, though, you may hit unexpected issues such as poor network conditions or permission problems. Those are manageable - just take them one at a time.

Synchronize skills

# Perform synchronization (reconcile all sources)
npx skillsbase sync

# Only check for drift (do not modify files)
npx skillsbase sync --check

# Allow missing sources (CI scenario)
npx skillsbase sync --allow-missing-sources

During synchronization, the system checks every source defined in sources.yaml and reconciles them with the contents under the skills/ directory. If differences exist, it updates them; if there are no differences, it skips them. This prevents the “configuration changed but files did not” problem.

Generate CI configuration

# Generate workflow
npx skillsbase github_action --kind workflow

# Generate action
npx skillsbase github_action --kind action

# Generate everything
npx skillsbase github_action --kind all

The CI configuration is generated automatically as well. You still need to adjust some details yourself, such as trigger conditions and runtime environments, but that is not 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: skills provided by the system
  system:
    type: local
    path: /home/user/.codex/skills/.system
    naming: prefix-system  # Add system- prefix
    includes:
      - imagegen
      - openai-docs
      - skill-creator  # Becomes system-skill-creator

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

This configuration file is the core of the entire system. All sources are defined here. Change this file, and the next synchronization will apply the new state. In that sense, it is truly 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"
}

Every skill directory contains this file, recording its source information. That way, when something goes wrong later, you can quickly locate where it came from and when it was synchronized.

Security and validation

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

# Validate with the skills CLI
npx skills add . --list

# Check for updates
npx skills check

Validation is one of those things that can feel both important and optional. Still, for the sake of safety, it never hurts to run it from time to time. After all, you never know when something unexpected might happen.

GitHub Actions integration

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

Once CI integration is in place, every change to sources.yaml or the skills/ directory automatically triggers validation. That prevents the situation where changes were made locally but synchronization was forgotten.

Best practices

Handle naming conflicts: add the system- prefix to system skills consistently. This keeps every skill available while avoiding naming conflicts.
Idempotent operations: all commands support repeated execution, and running sync multiple times does not produce side effects. This is especially important in CI.
Managed files: generated files include the # Managed by skillsbase CLI comment, making them easy to identify and manage. These files can be safely overwritten, and manual modifications are not preserved.
Non-interactive mode: CI environments use deterministic behavior by default, so interactive prompts do not interrupt execution. All configuration is declared through sources.yaml.
Source traceability: every skill has a .skill-source.json file recording its source information, making troubleshooting much faster.

Team collaboration

# Team members install the shared skills repository
npx skills add your-org/myskills -g --all

# Clone locally and validate
git clone https://github.com/your-org/myskills.git
cd myskills
npx skills add . --list

By managing the skills repository with Git, team members can easily synchronize their skill collection and ensure that everyone uses the same versions of tools and configuration.

This is especially useful in team collaboration. You no longer run into situations where “it works for me but not for you.” Once the environment is unified, half the problems disappear.

Conclusion

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

Security: source validation, conflict detection, and managed file protection
Maintainability: a unified entry point, idempotent operations, and configuration-as-documentation
Standardization: a unified directory structure, naming conventions, and metadata format
Automation: CI/CD integration, automatic synchronization, and automatic validation

With this approach, developers can manage their own Agent Skills the same way they manage npm packages, building a reproducible, shareable, and maintainable skills repository system.

The tools and workflow shared in this article are exactly what we refined through real mistakes and real optimization while building HagiCode. If you find this approach valuable, that is a good sign that our engineering direction is the right one - and that HagiCode itself is worth your attention as well.

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

References

skillsbase repository: github.com/HagiCode-org/skillsbase
HagiCode official website: hagicode.com
HagiCode source code: github.com/HagiCode-org/site
Installation guide: docs.hagicode.com/installation/docker-compose
Quick desktop installation: hagicode.com/desktop/

If this article helped you:

Give us a Star on GitHub: github.com/HagiCode-org/site
Visit the official website to learn more: hagicode.com
Watch the 30-minute hands-on demo: www.bilibili.com/video/BV1pirZBuEzq/
Try one-click installation: docs.hagicode.com/installation/docker-compose
Public beta has started, and you are welcome to try it out

This article was first published on the HagiCode Blog.

Copyright Notice

Thank you for reading. If you found this article useful, you are welcome to like it, save it, and share it in support. This content was created with AI-assisted collaboration, and the final version was reviewed and confirmed by the author.

Author: newbe36524
Original link: https://docs.hagicode.com/blog/2026-04-07-why-use-skillsbase-for-skills-repository/
Copyright notice: Unless otherwise stated, all blog posts on this site are licensed under BY-NC-SA. Please indicate the source when reposting.

Why Use Skillsbase to Maintain Your Own Skills Collection Repository