skills-x

Skills-X Contribution Guide

This skill provides a standardized workflow for contributing new skills to the skills-x collection.

When to Use This Skill

• Adding new community skills from external sources (agentskills.io, anthropics/skills, etc.)
• Creating x original skills
• Updating existing skills with new versions
• Validating skill format compliance before submission
• After creating a new skill, ask whether to generate a REAEDME (background summary)

Project Structure Overview

skills-x/
├── pkg/registry/        # Skill registry definition
│   └── registry.yaml    # Indexes skills from external sources
├── skills/              # Self-developed skills (自研)
│   └── skills-x/        # This skill (embedded in binary)
├── cmd/skills-x/        # Go source code
│   ├── command/         # CLI commands (list, init)
│   └── i18n/
│       └── locales/     # Language files (zh.yaml, en.yaml)
├── npm/                 # npm package
│   └── package.json     # Version number here
└── Makefile             # Build commands

Key Changes:

• No local skills/ directory - Skills are fetched directly from external repositories
• Central registry - All skill sources defined in pkg/registry/registry.yaml
• Dynamic fetching - Skills are cloned on-demand, not bundled with binary

---

⚠️ Internationalization (i18n) Rules - CRITICAL

skills-x supports bilingual (Chinese/English) output. Follow these rules strictly:

Rule 1: NO Mixing Languages in a Single String

❌ FORBIDDEN - Never mix Chinese and English in the same string:

// BAD: Mixed languages
desc = "🔄 套娃! Contribution guide (not for regular use)"
tag = "⭐ 作者自研 Original"

✅ CORRECT - Use separate i18n keys:

// GOOD: Use i18n.T() to get localized string
desc = i18n.T("list_skillsx_desc")
tag = i18n.T("list_castlex_tag")

Rule 2: All User-Facing Strings Must Use i18n

Any text displayed to users MUST go through the i18n system:

1. Add keys to both language files:

cmd/skills-x/i18n/locales/zh.yaml:

my_message: "这是中文消息"

cmd/skills-x/i18n/locales/en.yaml:

my_message: "This is English message"

2. Use in Go code:

import "github.com/castle-x/skills-x/cmd/skills-x/i18n"

// Simple string
msg := i18n.T("my_message")

// With format arguments
msg := i18n.Tf("my_format_msg", arg1, arg2)

Rule 3: i18n Key Naming Convention

Type	Key Prefix	Example
Category names	cat_	cat_creative, cat_document
Skill descriptions	skill_	skill_pdf, skill_docx
Command descriptions	cmd_	cmd_list_short
List output	list_	list_header, list_total
Init output	init_	init_success
Error messages	err_	err_skill_not_found

Rule 4: Adding New Skill Descriptions

When adding a new skill, you MUST add descriptions to BOTH language files:

Step 1: Add English description to en.yaml:

skill_new-skill: "Brief description in English"

Step 2: Add Chinese description to zh.yaml:

skill_new-skill: "简短的中文描述"

Step 3: The code automatically picks up translations via:

desc := i18n.T("skill_" + skillName)

Rule 5: Testing Bilingual Output

Always test BOTH languages after any UI changes:

# Test Chinese
SKILLS_LANG=zh ./bin/skills-x list

# Test English  
SKILLS_LANG=en ./bin/skills-x list

Rule 6: Environment Variable Priority

Language is detected in this order:

1. SKILLS_LANG (highest priority, skills-x specific)
2. LANG (system locale)
3. LC_ALL (system locale)
4. Default: zh (Chinese)

---

Skill Directory Structure Requirements

All skills MUST follow the Agent Skills specification:

skill-name/
├── SKILL.md          # Required: Instructions + metadata
├── LICENSE.txt       # Required: License file
├── scripts/          # Optional: Executable code
├── references/       # Optional: Documentation
└── assets/           # Optional: Templates, resources

SKILL.md Format Requirements

The SKILL.md file MUST contain YAML frontmatter with required fields:

---
name: skill-name        # Required: lowercase, hyphens only, max 64 chars
description: ...        # Required: max 1024 chars, describe what and when
license: MIT            # Optional: license identifier
metadata:               # Optional: additional metadata
  author: example
  version: "1.0"
---

Name Field Rules

• Length: 1-64 characters
• Characters: lowercase letters, numbers, hyphens only
• Must NOT start or end with hyphen
• Must NOT contain consecutive hyphens (--)
• Must match parent directory name

Valid: pdf-processing, data-analysis, code-review Invalid: PDF-Processing, -pdf, pdf--processing

Description Field Rules

• Length: 1-1024 characters
• Should clearly describe what the skill does AND when to use it
• Include keywords that help AI agents identify relevant tasks

---

Contributing Community Skills (Open Source Skills)

NEW WORKFLOW: To add a new open source skill to the registry, you only need to edit pkg/registry/registry.yaml. No manual downloading or local copying required!

Step 1: Find and Validate Source Skill

Search for skills at:

• https://agentskills.io/
• https://github.com/anthropics/skills
• https://github.com/vercel-labs/agent-skills
• https://github.com/remotion-dev/skills
• Other GitHub repositories with proper skill structure

Before adding a skill to registry, verify:

1. The repository has a valid SKILL.md file in the skill directory
2. The SKILL.md has proper YAML frontmatter with name and description fields
3. The skill name matches directory name (lowercase, hyphens only)
4. License information is available

Step 2: Add Skill Source to Registry

Edit pkg/registry/registry.yaml and add a new source entry:

# Example: Adding a new skill source
new-source-name:
  repo: github.com/owner/repo-name
  license: MIT  # or Apache-2.0, etc.
  skills:
    - name: skill-name
      path: path/to/skill/in/repo  # e.g., "skills/pdf" or "packages/skills/pdf"
      description: "Brief English description"
      description_zh: "简短的中文描述"

Required fields for each source:

• repo: GitHub repository URL (without https://)
• license: License type (MIT, Apache-2.0, etc.)
• skills: List of skills available from this source

Required fields for each skill:

• name: Skill name (must match directory name in repo)
• path: Path to skill directory within repository
• description: English description (max 1024 chars)
• description_zh: Chinese description (optional, max 1024 chars)

Step 3: Verify Skill Installation (Always)

After updating the registry, ALWAYS build and run list/init tests (no need to ask).

# Build the binary
make build

# Test listing the skill
./bin/skills-x list | grep "skill-name"

# Test installing the skill
./bin/skills-x init skill-name --target /tmp/test-install
ls /tmp/test-install/skill-name/

Validation checks:

• Skill appears in list output
• Skill can be installed with init
• English and Chinese descriptions display correctly
• License information is accurate

Step 4: Ask for Release Actions

After tests finish, ask the user whether they want to:

• Commit and push
• Create GitHub release
• Publish to npm

---

Contributing Self-Developed Skills (自研)

Self-developed skills should be placed in the skills/ directory at the project root.

Step 1: Create Skill Directory

mkdir -p skills/<skill-name>

Step 2: Create Required Files

1. Create SKILL.md with proper frontmatter:

---
name: <skill-name>
description: <what this skill does and when to use it>
license: MIT
metadata:
  author: x
  version: "1.0"
---

# <Skill Name>

<Detailed instructions for the AI agent>

2. Add LICENSE.txt (copy from project root or create)

3. Ask the user whether to add a summary document named REAEDME.md.

   • Purpose: describe the skill’s background, the problem it solves, and the author's goals.
   • Do NOT include any secrets or API keys.

Step 3: Add i18n Translations

Same as community skills - add to both en.yaml and zh.yaml:

skill_new-skill: "Description"

Note: Self-developed skills are automatically assigned category skills-x and marked with IsX: true.

---

Build and Test

# Build the binary
make build

# Test Chinese output
SKILLS_LANG=zh ./bin/skills-x list | grep "<skill-name>"

# Test English output
SKILLS_LANG=en ./bin/skills-x list | grep "<skill-name>"

# Test downloading the skill
./bin/skills-x init <skill-name> --target /tmp/test-skills
ls /tmp/test-skills/<skill-name>/

---

Release Workflow

Step 1: Update Version

Increment version in npm/package.json:

"version": "0.1.X"  // increment patch version

Step 2: Build for npm

make build-npm

Step 3: Pre-Release Testing (CRITICAL)

⚠️ IMPORTANT: Always run this test before releasing to catch broken or missing skills!

Test all skills can be installed successfully:

# Use a clean temporary directory
TEST_DIR=$(mktemp -d)
echo "Testing in: $TEST_DIR"

# Test installing all skills
./bin/skills-x init --all --target "$TEST_DIR"

# Check for failures
if [ $? -ne 0 ]; then
  echo "❌ Some skills failed to install!"
  echo "Review the output above for skills that are:"
  echo "  - Not found in repository"
  echo "  - Have incorrect paths"
  echo "  - Repository no longer exists"
  exit 1
fi

# Clean up
rm -rf "$TEST_DIR"
echo "✅ All skills tested successfully"

If any skills fail:

1. Skill not found in repo (⚠ 在仓库中未找到 skill 路径):

   • The skill path in registry.yaml is incorrect
   • The skill was removed/renamed in the source repository
   • Action: Remove from pkg/registry/registry.yaml or fix the path

2. Repository not accessible:

   • The re

---

Content truncated.