custom-skills-dev

name

custom-skills-dev

description

Guide development workflow for the custom-skills project (ai-dev CLI tool). Use when: (1) adding/modifying skills, commands, or agents, (2) modifying CLI code in script/, (3) updating copy/distribution logic, (4) releasing new versions, (5) integrating upstream resources. Triggers: "develop custom-skills", "modify ai-dev", "add skill to project", "update copy logic", "release version", "開發 custom-skills", "修改複製邏輯", "發布版本".

custom-skills-dev

Development guide for the custom-skills project (ai-dev CLI tool).

Project Overview

This project is a Configuration as Code repository providing:

• Unified AI development standards (Skills, Commands, Agents)
• CLI tool (ai-dev) for managing AI tool configurations
• Three-stage copy architecture for resource distribution

Quick Reference

Key Directories

Directory	Purpose
script/	Python CLI implementation
skills/	Shared skills (all AI tools)
commands/	Tool-specific commands (claude/, gemini/, etc.)
agents/	Tool-specific agents (claude/, opencode/)
sources/	Upstream resource integration (ecc/)
upstream/	Upstream tracking system

Three-Stage Copy Flow

Stage 1: Clone     GitHub repos → ~/.config/
Stage 2: Integrate ~/.config/* → ~/.config/custom-skills/
Stage 3: Distribute ~/.config/custom-skills/ → ~/.claude/, ~/.gemini/, etc.

For details, see references/copy-architecture.md.

Common Development Tasks

Adding a New Skill

1. Create skills/<skill-name>/SKILL.md
2. Add optional references/ for detailed docs
3. Run ai-dev update to distribute
4. Update CHANGELOG.md

Adding a New CLI Command

1. Create script/commands/<command>.py
2. Register in script/main.py
3. Update README.md command table
4. Update CHANGELOG.md
5. Bump version in pyproject.toml

For details, see references/cli-development.md.

Releasing a New Version

1. Update version in pyproject.toml
2. Add CHANGELOG entry with date
3. Commit: git commit -m "chore(release): v0.X.Y"
4. Tag: git tag v0.X.Y
5. Push: git push && git push --tags

For details, see references/release-workflow.md.

Integrating Upstream Resources

1. Add source to upstream/sources.yaml
2. Clone to ~/.config/
3. Run /custom-skills-upstream-ops audit to analyze
4. Create integration proposal via /openspec:proposal
5. Place resources in sources/<name>/

Language Convention

• Documentation: 繁體中文 (Traditional Chinese)
• Technical terms preserved in English: Skill, Command, Agent, Hook, MCP
• Commit messages: 繁體中文 with Conventional Commits format

Testing Changes

# Install locally for testing
uv tool install . --force

# Verify installation
ai-dev --version
ai-dev status

# Test specific command
ai-dev install --only state,targets --target claude

References

• Copy Architecture - Three-stage flow details
• CLI Development - Python CLI guide
• Release Workflow - Version release process