~/lovstudio/coding/skills/
├── index/                     ← central catalog (lovstudio/skills repo)
│   ├── skills.yaml            ← machine-readable manifest (paid flag lives here)
│   └── README.md              ← human-readable catalog
├── {name}-skill/              ← each skill is an independent repo
│   ├── SKILL.md
│   ├── README.md
│   ├── CHANGELOG.md           ← managed by skill-optimizer
│   ├── scripts/               ← standalone Python CLI scripts
│   └── references/            ← optional progressive-disclosure docs
└── ...

~/.claude/skills/lovstudio-{name}  ← symlink → ~/.agents/skills/lovstudio-{name}
                                                 → ~/lovstudio/coding/skills/{name}-skill/

Key facts:

GitHub repo name: lovstudio/{name}-skill (with -skill suffix)
Local source path: ~/lovstudio/coding/skills/{name}-skill/ (no lovstudio- prefix)
Claude Code reads: ~/.claude/skills/lovstudio-{name}/ (with lovstudio- prefix, via symlink)
Frontmatter name: lovstudio:{name} (with : separator)
paid: true/false lives only in index/skills.yaml, never in SKILL.md

Skill Creation Process

Step 1: Understand the Skill

Ask the user what the skill should do. Start with the most important question via AskUserQuestion — don't dump everything at once.

Key questions:

What problem does it solve? What's the input → output?
2-3 concrete usage examples?
What user phrases should trigger this skill (中文 + English)?
Pure-instruction skill, or does it need a Python script?
Free (public repo) or paid (private repo)?

Step 2: Plan Contents

Analyze the examples and identify:

Scripts — deterministic operations → scripts/
References — domain knowledge Claude needs while working → references/
Assets — files used in output (templates, fonts, etc.) → assets/

Rules:

Python scripts must be standalone single-file CLIs with argparse
No package structure, no setup.py, no __init__.py
CJK text handling is a core concern if the skill deals with documents

Step 3: Initialize

Run the init script (it auto-detects the target directory):

python3 ~/.claude/skills/lovstudio-skill-creator/scripts/init_skill.py <name>

This creates ~/lovstudio/coding/skills/{name}-skill/ with:

{name}-skill/
├── SKILL.md          ← frontmatter + TODO workflow
├── README.md         ← human-readable docs with version badge
└── scripts/          ← empty, ready for implementation

Pass --paid if this is a paid skill (adjusts README + metadata hints).

Step 4: Implement

Write scripts in scripts/ — test by running directly
Write SKILL.md — instructions for AI assistants:
- Frontmatter description is the trigger mechanism — cover what + when + concrete trigger phrases (中文 + English)
- Body contains workflow steps, CLI reference, field mappings
- Use AskUserQuestion for interactive prompts before running scripts
- Keep SKILL.md under 500 lines; split to references/ if longer
Write README.md — docs for humans on GitHub:
- Version badge (source of truth for version)
- Install command: git clone https://github.com/lovstudio/{name}-skill ~/.claude/skills/lovstudio-{name}
- Dependencies
- Usage examples, options table
- ASCII diagrams if useful

See references/templates.md for SKILL.md / README.md templates.

Step 5: Publish

5a. Initialize & push the skill's own repo

cd ~/lovstudio/coding/skills/<name>-skill
git init
git add -A
git commit -m "feat: initial release of <name> skill"

# Free skill (public):
gh repo create lovstudio/<name>-skill --public --source=. --push

# Paid skill (private):
gh repo create lovstudio/<name>-skill --private --source=. --push

5b. Register in the central index

Edit ~/lovstudio/coding/skills/index/skills.yaml — append under the right category (category order in the yaml determines display order on the website):

  - name: <name>
    repo: lovstudio/<name>-skill
    paid: false                         # or true for paid skills
    category: "<Category>"              # must match an existing category heading
    version: "0.1.0"
    description: "<One-line description matching SKILL.md tagline>"

Also add a row to ~/lovstudio/coding/skills/index/README.md under the matching category section. Then PR against lovstudio/skills:

cd ~/lovstudio/coding/skills/index
git checkout -b add/<name>
git add skills.yaml README.md
git commit -m "add: <name> skill"
git push -u origin HEAD
gh pr create --fill

5c. Symlink for local availability

Make the skill immediately usable in Claude Code:

# Layer 1: source → .agents
ln -s ~/lovstudio/coding/skills/<name>-skill \
      ~/.agents/skills/lovstudio-<name>

# Layer 2: .agents → .claude/skills (where Claude Code reads)
ln -s ../../.agents/skills/lovstudio-<name> \
      ~/.claude/skills/lovstudio-<name>

Verify: ls ~/.claude/skills/lovstudio-<name>/SKILL.md resolves.

5d. Trigger lovstudio.ai cache refresh (optional)

After the skill is indexed in skills.yaml, the lovstudio.ai /agent page caches the index for 1 hour (Next.js ISR). Trigger on-demand revalidation so the new skill appears immediately:

if [ -n "$LOVSTUDIO_REVALIDATE_SECRET" ]; then
  curl -sfX POST https://lovstudio.ai/api/revalidate \
    -H "x-revalidate-secret: $LOVSTUDIO_REVALIDATE_SECRET" \
    -H "content-type: application/json" \
    -d '{"tags":["skills-index"]}' \
    && echo "✓ cache refreshed" \
    || echo "⚠ revalidate failed (will appear within 1h)"
fi

Known tags (see lovstudio/web:src/data/skills.ts):

skills-index — the yaml index (invalidates all list pages)
skill:<id> — detail for a single skill
skill-cases:<id> — cases.json for a skill

Step 6: Test & Iterate

In a new conversation, invoke /lovstudio:<name> — confirm it triggers
Notice struggles → edit SKILL.md / scripts in the source repo
Commit & push (the symlink chain means no local copy to sync)

Design Patterns

Interactive Pre-Execution (MANDATORY for generation/conversion skills)

**IMPORTANT: Use `AskUserQuestion` to collect options BEFORE running.**

Use `AskUserQuestion` with the following template:
[options list]

### Mapping User Choices to CLI Args
[table mapping choices to --flags]

Progressive Disclosure

Keep SKILL.md lean. Split to references when:

Multiple themes/variants → references/themes.md
Complex API docs → references/api.md
Large examples → references/examples.md

Reference from SKILL.md: "For theme details, see references/themes.md"

Context-Aware Pre-Fill

For skills that fill or generate content:

Check user memory and conversation context first
Pre-fill what you can
Only ask for fields you truly don't know

What NOT to Include

INSTALLATION_GUIDE.md — clutter; install instructions go in README.md
Test files — scripts are tested by running, not with test frameworks
__pycache__/, *.pyc, .DS_Store — add to .gitignore
paid field in frontmatter — it lives only in index/skills.yaml

Migration Note (2026-04)

The ecosystem was refactored from a monorepo (lovstudio/skills containing skills/lovstudio-<name>/) + mirror (lovstudio/pro-skills) into independent per-skill repos + central index. The old lovstudio/pro-skills was archived. If working on a legacy skill still in the old structure, migrate it first:

# 1. Extract from monorepo subdirectory
cp -r ~/projects/lovstudio-skills/skills/lovstudio-<name> \
      ~/lovstudio/coding/skills/<name>-skill
cd ~/lovstudio/coding/skills/<name>-skill
# (remove the lovstudio- prefix from the directory by creating fresh)

# 2. Fresh git history
rm -rf .git
git init && git add -A && git commit -m "import: <name> from monorepo"

# 3. Create independent repo
gh repo create lovstudio/<name>-skill --public --source=. --push

lovstudio:skill-creator

lovstudio:skill-creator

Architecture