castle-x/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 self-developed skills (自研)
• Updating existing skills with new versions
• Validating skill format compliance before submission
• After creating a new skill, ask whether to generate a README (background summary)

---

⚡ Core Principle: No Binary Rebuild Needed for Skills

Adding or updating skills NEVER requires rebuilding or republishing the skills-x binary.

The skills-x tool uses a registry-first architecture:

• The binary only contains the registry index (skill metadata)
• Actual skill content is fetched from GitHub at install time
• The registry is cached locally at ~/.config/skills-x/registry.yaml

This means:

• ✅ Add a self-developed skill → push to git → done
• ✅ Add a third-party skill → push to git → done
• ✅ Users get new skills by running skills-x registry update
• ❌ No version bump, no binary build, no npm publish needed

The only time a full release is needed is when Go source code or CLI behavior changes.

---

Project Structure Overview

skills-x/
├── pkg/registry/        # Skill registry definition
│   └── registry.yaml    # Central index of ALL skills (self-developed + third-party)
├── skills/              # Self-developed skills (自研) source code
│   └── skills-x/        # This contribution skill
├── cmd/skills-x/        # Go source code
│   ├── command/         # CLI commands (list, init, registry)
│   └── i18n/
│       └── locales/     # Language files (zh.yaml, en.yaml)
├── npm/                 # npm package
│   └── package.json     # Version number here
└── Makefile             # Build commands

Architecture summary:

• pkg/registry/registry.yaml — single source of truth for all skills
• skills/<name>/ — self-developed skill content (committed to this repo)
• Third-party skills — content lives in external repos, only metadata in registry.yaml

---

⚠️ 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

For installable skills, descriptions should be defined in pkg/registry/registry.yaml:

- name: new-skill
  path: skills/new-skill
  description: "Brief English description"
  description_zh: "简短的中文描述"

Only add i18n keys when introducing new CLI/TUI message keys.

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

---

User Guide: Keeping Skills Up-to-Date

The registry update Command

skills-x registry update

This command downloads the latest registry.yaml from GitHub and caches it locally at ~/.config/skills-x/registry.yaml.

When to run it:

• After any skill has been added/updated and pushed to GitHub
• To see newly contributed skills before upgrading the binary
• Anytime skills-x list doesn't show a skill you expect

How the cache works: | State | What list / init sees | |-------|--------------------------| | No cache | Registry embedded in the binary (older) | | Cache present | Cached registry from GitHub (newer) | | After registry update | Latest registry from GitHub |

⚠️ Important for local development: After pushing new skills to GitHub, you MUST run skills-x registry update before skills-x list will show the new skill. The locally built binary still has the old registry embedded until the cache is refreshed.

---

Contributing Self-Developed Skills (自研)

No binary release needed. Just create the skill, update the registry, push to git.

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 README.md (background, problem it solves, author goals — no secrets).

Step 3: Update Registry

Add the skill to pkg/registry/registry.yaml under the castle-x-skills-x source:

castle-x-skills-x:
  repo: github.com/castle-x/skills-x
  license: MIT
  skills:
    # ... existing skills ...
    - name: <skill-name>
      path: skills/<skill-name>
      tags: [<relevant-tags>]
      description: "Brief English description"
      description_zh: "简短的中文描述"

Step 4: Add i18n Translations

Add to both cmd/skills-x/i18n/locales/en.yaml and zh.yaml:

skill_<skill-name>: "Brief description"

Step 5: Commit and Push

git add skills/<skill-name>/ pkg/registry/registry.yaml cmd/skills-x/i18n/locales/
git commit -m "feat: add <skill-name> skill"
git push origin main

That’s it — no binary build or npm publish needed!

Step 6: Test Locally (After Pushing)

After pushing, verify the new skill is visible:

# Pull the latest registry from GitHub (REQUIRED to see new skills)
skills-x registry update

# Now the new skill should appear
skills-x list | grep "<skill-name>"

# Try installing it
skills-x init <skill-name> --target /tmp/test-skills
ls /tmp/test-skills/<skill-name>/

⚠️ Without skills-x registry update, your local binary still shows the old embedded registry and the new skill will NOT appear.

---

Contributing Community Skills (Open Source Skills)

No binary release needed. Just validate, update registry, push to git.

Step 1: Find and Validate the 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 to registry, verify:

1. Repository has a valid SKILL.md in the skill directory
2. SKILL.md has proper YAML frontmatter (name + description)
3. Skill name matches directory name (lowercase, hyphens only)
4. License is identifiable

Step 2: Add to Registry

Edit pkg/registry/registry.yaml:

new-source-name:
  repo: github.com/owner/repo-name
  license: MIT
  skills:
    - name: skill-name
      path: path/to/skill/in/repo
      tags: [<relevant-tags>]
      description: "Brief English description"
      description_zh: "简短的中文描述"

Step 3: Commit and Push

git add pkg/registry/registry.yaml
git commit -m "feat: add <skill-name> skill from <source>"
git push origin main

Step 4: Test Locally (After Pushing)

# Pull the latest registry from GitHub (REQUIRED)
skills-x registry update

# Verify the skill appears
skills-x list | grep "<skill-name>"

# Test installing it
skills-x init <skill-name> --target /tmp/test-install
ls /tmp/test-install/<skill-name>/

---

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

Skills are fetched from GitHub at install time. The binary only contains the registry index, not skill content. This means:

• Skills-only changes (add/update skills in registry.yaml) → just commit & push, no release needed
• Tool changes (Go code, CLI behavior, registry format) → full release required

Path A: Skills-only Release (FAST - no version bump needed)

When ONLY pkg/registry/registry.yaml or skill content changes:

# Build and verify
make build
./bin/skills-x init --all --target "$(mktemp -d)"

# Commit and push — done!
git add pkg/registry/registry.yaml
git commit -m "feat: add <skill-name> skill

- Add <skill-name> to registry
- Users can update registry: skills-x registry update"
git push origin main

That's it! Users get the skill immediately by running:

skills-x registry update
skills-x list  # See new skill
skills-x init <skill-name>  # Install it

Path B: Tool Release (FULL - version bump required)

When Go source code, CLI behavior, or registry format changes:

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!

# 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 repository was deleted or made private
   • Action: Remove the entire source from pkg/registry/registry.yaml

3. Clone failed:

   • Network issue (retry)
   • Repository URL changed
   • Action: Update repo URL or remove from registry

After fixing registry.yaml:

# Rebuild and test again
make build-npm
./bin/skills-x init --all --target "$(mktemp -d)"

Step 4: Commit Changes

git add .
git commit -m "feat: add <skill-name> skill

- Add <skill-name> to skills collection
- Add i18n translations (en/zh)
- Update README"

Step 5: Tag and Push

git tag -a v0.1.X -m "Add <skill-name> skill"
git push origin main
git push --tags

Step 6: Create GitHub Release

⚠️ CRITICAL: You MUST upload binary assets to the release!

GitHub Release without binary assets is useless - users cannot download the tool.

# Build all platform binaries first
make build-npm

# Create release WITH binary assets (REQUIRED!)
gh release create v0.1.X \
  --title "v0.1.X - Add <skill-name>" \
  --notes "## Added
- New skill: <skill-name>
- Description: <brief description>" \
  npm/bin/skills-x-linux-amd64 \
  npm/bin/skills-x-linux-arm64 \
  npm/bin/skills-x-darwin-amd64 \
  npm/bin/skills-x-darwin-arm64 \
  npm/bin/skills-x-windows-amd64.exe

❌ WRONG - Release without assets:

# This creates an EMPTY release - USELESS!
gh release create v0.1.X --title "v0.1.X" --notes "..."

✅ CORRECT - Release with all binary assets:

gh release create v0.1.X --title "v0.1.X" --notes "..." \
  npm/bin/skills-x-linux-amd64 \
  npm/bin/skills-x-linux-arm64 \
  npm/bin/skills-x-darwin-amd64 \
  npm/bin/skills-x-darwin-arm64 \
  npm/bin/skills-x-windows-amd64.exe

If you forgot to upload assets, use gh release upload:

gh release upload v0.1.X \
  npm/bin/skills-x-* \
  --clobber

Step 7: Publish to npm

cd npm && npm publish --access public

---

Quick Reference

# ─── After adding a skill and pushing ───────────────────────────────────────
# Pull latest registry from GitHub (REQUIRED before testing new skills)
skills-x registry update

# List all skills (now shows newly added skills)
skills-x list
skills-x list | grep "<skill-name>"

# Install a skill
skills-x init <skill-name> --target /tmp/test-skills

# ─── Local dev build & verify ────────────────────────────────────────────────
make build
SKILLS_LANG=zh ./bin/skills-x list
SKILLS_LANG=en ./bin/skills-x list

# ─── Self-developed skill (自研) — no binary release needed ──────────────────
# 1. Create skills/<skill-name>/SKILL.md + LICENSE.txt
# 2. Add entry to pkg/registry/registry.yaml (under castle-x-skills-x)
# 3. Add i18n keys to en.yaml + zh.yaml
git add skills/<skill-name>/ pkg/registry/registry.yaml cmd/skills-x/i18n/locales/
git commit -m "feat: add <skill-name> skill"
git push origin main
# Users get it with: skills-x registry update

# ─── Third-party skill — no binary release needed ────────────────────────────
# 1. Validate SKILL.md in source repo
# 2. Add entry to pkg/registry/registry.yaml
git add pkg/registry/registry.yaml
git commit -m "feat: add <skill-name> skill from <source>"
git push origin main
# Users get it with: skills-x registry update

# ─── Full tool release (Go code changes only) ────────────────────────────────
make build-npm
./bin/skills-x init --all --target "$(mktemp -d)"  # Test all skills
git add . && git commit -m "feat: ..."
git tag -a v0.1.X -m "..."
git push origin main --tags
gh release create v0.1.X --title "v0.1.X" --notes "..." \
  npm/bin/skills-x-linux-amd64 \
  npm/bin/skills-x-linux-arm64 \
  npm/bin/skills-x-darwin-amd64 \
  npm/bin/skills-x-darwin-arm64 \
  npm/bin/skills-x-windows-amd64.exe
cd npm && npm publish --access public

---

Troubleshooting

| Issue | Solution | |-------|----------| | Open source skill not in list | Check registry.yaml entry (repo, path, name fields) | | Self-developed skill not in list | Check pkg/registry/registry.yaml source entry, skill path, and source repository accessibility | | Mixed language output | Ensure ALL strings use i18n.T(), no hardcoded text | | Missing translation | Add keys to BOTH en.yaml and zh.yaml | | init fails | Verify SKILL.md exists and has valid frontmatter | | Windows fails | Ensure registry path uses / separators and target directories are writable | | Version mismatch | Check npm/package.json version matches build | | Release has no assets | MUST include binary files when running gh release create | | Skill not in README | MUST update BOTH README.md and README_ZH.md with new skill |

---

Summary: Skill Contribution Workflows

| Skill Type | Storage | Description Source | Release needed? | How users get it | |------------|---------|-------------------|-----------------|-----------------| | Self-Developed (自研) | skills/<name>/ in this repo | registry.yaml fields | ❌ No | skills-x registry update | | Third-Party (open source) | External repo only | registry.yaml fields | ❌ No | skills-x registry update | | Tool change (Go code) | n/a | n/a | ✅ Yes (full release) | Install new binary version |

---

Checklists for New Skills

For Self-Developed Skills (自研)

• [ ] Skill directory created at skills/<name>/
• [ ] SKILL.md with valid YAML frontmatter (name, description, license)
• [ ] LICENSE.txt present
• [ ] Entry added to pkg/registry/registry.yaml under castle-x-skills-x source
• [ ] description (English) and description_zh (Chinese) filled in registry.yaml
• [ ] skill_<name> key added to en.yaml and zh.yaml
• [ ] Committed and pushed to origin/main
• [ ] skills-x registry update run locally
• [ ] skills-x list | grep "<name>" shows the skill
• [ ] skills-x init <name> --target /tmp/test installs successfully

For Third-Party / Open Source Skills

• [ ] Source repo has valid SKILL.md with frontmatter
• [ ] Skill name matches directory name in source repo
• [ ] Entry added to pkg/registry/registry.yaml with correct repo, path, license
• [ ] description (English) and description_zh (Chinese) filled in registry.yaml
• [ ] Committed and pushed to origin/main
• [ ] skills-x registry update run locally
• [ ] skills-x list | grep "<name>" shows the skill
• [ ] skills-x init <name> --target /tmp/test installs successfully