DEV Community

Evan Lin
Evan Lin

Posted on • Originally published at evanlin.com on

Building an Agent Skill Hub: From Skill Development to Automated Multilingual Documentation Deployment on GitHub Pages

#agents #automation #documentation #github

image-20260322225856161

Reference links:

This article documents how I built a skill description specification from scratch and created a GitHub Pages documentation site that supports both Chinese and English, drawing inspiration from minimalist aesthetics, while developing the Agent Skill Hub (2026 Skill Library).

Background

With the popularity of AI Agents (such as OpenClaw or Gemini CLI), we found that "how to quickly understand and execute specific tasks for the Agent" has become key. Instead of writing long prompts every time, it's better to package common operations into standardized Skills.

To facilitate community communication and Agent reading, I created agent-skill-hub. But code alone is not enough; we also need a decent "facade" – a document website that is both aesthetically pleasing and has technical details.

🛠️ Step 1: Standardize Skill Descriptions (SKILL.md)

In agent-skill-hub, each skill (such as gcp-helper or n8n-executor) has a SKILL.md. The structure of this file is crucial because it's not just for humans to read, but also for LLMs to read:

  • Name & Description: Let the Agent know what this is.
  • When to Use: Define trigger scenarios.
  • Core Pattern: Provide standard instruction examples.
  • Common Mistakes: Reduce errors caused by Agent hallucinations.

🎨 Step 2: Design Style — Tribute to Minimalist Aesthetics

When designing the web pages under the docs directory, I referenced the style of whisperASR. That design of a dark background with bright accent colors (Teal) is very in line with the aesthetics of modern developers:

Visual Element Highlights:

  1. Gradient Title: Use linear-gradient to create a high-end texture.
  2. Teal Accent Color: Use #14b8a6 as the highlight color for key buttons and titles.
  3. Card-style Layout: Clearly present the icons and introductions of each skill, with good responsive design.

🌐 Step 3: Multilingual Support and Automatic Switching

To make it available to developers worldwide, I adopted a directory-structured language management method:

docs/
├── index.html (Language detection and redirection)
├── en/ (English version)
│ └── skills/
└── zh/ (Traditional Chinese version)
    └── skills/
Enter fullscreen mode Exit fullscreen mode

I added a simple JavaScript snippet to the root directory's index.html, which automatically redirects to the correct language based on the user's browser settings:

const lang = navigator.language || navigator.userLanguage;
if (lang.startsWith('zh')) {
    window.location.href = './zh/index.html';
} else {
    window.location.href = './en/index.html';
}
Enter fullscreen mode Exit fullscreen mode

🚀 Step 4: GitHub Pages Deployment Process

In 2026, the most recommended deployment method is to put the content in the docs/ directory of the main branch, which can keep the main branch clean while keeping development and documentation synchronized.

1. Prepare the Directory Structure

Create all the necessary directories at once using the command:

mkdir -p docs/en/skills docs/zh/skills docs/assets/css
Enter fullscreen mode Exit fullscreen mode

2. Git Commit and Push

After completing HTML/CSS development, execute the standard Git process:

git add docs/
git commit -m "docs: add GitHub Pages documentation in English and Chinese"
git push origin main
Enter fullscreen mode Exit fullscreen mode

3. Enable GitHub Pages Settings

  1. Go to Settings > Pages in the GitHub repository.
  2. Under Build and deployment, in Branch, select the main branch and the /docs folder.
  3. Click Save, and the website will be online in a few minutes.

image-20260322225932252

🛠️ Common Pitfalls and Troubleshooting

❓ Why can't the webpage style (CSS) be loaded?

Reason: In HTML files under subdirectories (such as en/skills/), the referenced paths must correctly use relative paths. Correction:

<!-- In the home page index.html -->
<link rel="stylesheet" href="../assets/css/style.css">
<!-- In the skill detail page -->
<link rel="stylesheet" href="../../assets/css/style.css">
Enter fullscreen mode Exit fullscreen mode

❓ How to ensure that the Agent can correctly read the document?

We have retained a large number of semantic tags (article, h2, pre, code) in the HTML, so that the Agent can more accurately capture the core logic when performing RAG (Retrieval-Augmented Generation) or directly reading the webpage.

🏁 Conclusion

Through this development, I have realized the importance of "documentation as product". A good AI skill library, in addition to powerful program logic, also needs a clear, intuitive, and multilingual-friendly navigation system.

If you also want to create a professional facade for your AI project, you might as well refer to the docs/ structure layout. Happy Coding! 🦞

Top comments (0)