Lovstudio Skill Creator

lovstudio:skill-creator

Scaffold a new lovstudio skill as an independent GitHub repo under lovstudio/{name}-skill. The lovstudio ecosystem is no longer a monorepo — each skill is its own repo, and a central index at ~/lovstudio/coding/skills/index/ tracks them.

Architecture

~/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. Use AskUserQuestion — one question at a time, in the order below. Do not skip or reorder. The distribution model decides the architecture, so it has to come before any implementation question.

Required question order:

Q1. Distribution model — ALWAYS ask first

Even for "obvious" simple skills, ask. Users may have future monetization plans you can't infer from the initial request.

这个 skill 的分发定位?

>

1. Free (public) — 任何人 git clone 就能用。适合引流、通用工具、开源贡献。

2. Paid, 普通 IP — 核心逻辑是流程/模板/prompt 编排,用户 grep 出来不心疼。用加密分发 + license 鉴权。

3. Paid, 敏感 IP — 含算法参数/业务规则/调好的 prompt/API 密钥,用户反编译会心疼。用 cloud-split:核心逻辑放云端,本地只有瘦客户端。

>

提示:不确定 → 选 2。未来升级到 3 比降级容易。

这个答案决定后续流程分支:

• 选 1 → 走标准公开 repo 流程
• 选 2 → 走 encrypted skill 流程(README 里坦诚说明 "加密 = 鉴权闸门,不保证反提取")
• 选 3 → 停下来读 `references/cloud-split.md`,然后走 cloud-split 流程

Q2. Problem & shape

• 解决什么问题?输入 → 输出是什么?
• 2-3 个具体使用示例
• 触发短语(中文 + English)

Q2.5. Decompose into protected vs public layers ⟵ MANDATORY, do not skip

Before any file is created, decompose the skill into two layers and show the user the decomposition for confirmation. This step catches two common failures: (a) cloud-split chosen with empty protected layer (over-engineering), (b) encrypted chosen but real secrets exist (under-protection).

Present like this:

我先拆解一下这个 skill 的结构:

>

公开层(瘦客户端 SKILL.md 会暴露这些):

- [具体列出:对话流、输入解析、输出渲染、错误处理]

>

保护层(需要藏起来的):

- [具体列出:算法/阈值/规则/prompt 工程/密钥/数据]

- 或明确写 "无 — 这个 skill 没有需要保护的核心逻辑"

>

按这个拆解,你选的 [Q1 答案] [合理 / 不合理,建议改成 X]。确认继续?

Consistency check — if decomposition contradicts Q1, challenge it:

对琐碎 demo(如"两数之和")尤其要质询 —— cloud-split 的服务端成本 + 部署复杂度 对"其实没东西可保护"的 skill 是净负收益。除非用户明确说"做模板/教学样本", 否则建议降级。

Q2.7. Naming — de-business the name ⟵ MANDATORY for paid skills

Bad naming leaks the logic through the API surface. Even with cloud-split, if the skill name + op name + input schema together describe the business logic, grep on jsonl reveals intent.

Rule: name the capability domain, not the specific logic.

Propose 2-3 de-businessed names and let the user pick via AskUserQuestion. For the op names inside the handler, same rule — op: "score" beats op: "check_if_sum_exceeds_10".

Skip this step only if Q1 == Free and the user doesn't care about future paid upgrades.

Q3. Implementation type

• 纯指令 SKILL.md,还是需要 Python CLI 脚本?
• (如果 Q1 选了 3:这一问跳过。cloud-split 的"实现"就是云端 handler,不是本地脚本。)

Protection model — what each tier actually buys you

Be honest about what each tier protects against. Do not market encrypted skills as "IP protection" — it's a gate, not a vault.

核心逻辑真正不下发到用户机器的 只有 cloud-split。其他 tier 都不要对用户承诺"加密保护"。

Step 2: Plan Contents

Analyze the examples and identify:

1. Scripts — deterministic operations → scripts/ 2. References — domain knowledge Claude needs while working → references/ 3. 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).

If Q1 chose cloud-split (tier 3): after running init_skill.py, don't put your real logic in scripts/. Instead: 1. Read references/cloud-split.md end-to-end before writing any code (this is not optional — the rules for non-leaky payloads are there, not here) 2. Start from `threshold-check` as the reference pattern, NOT paid-add. paid-add is an architecture demo with an intentionally leaky payload (for teaching). Copying its return shape into a real skill defeats the whole point of cloud-split. 3. Write the handler at ~/lovstudio/coding/web/supabase/functions/skill_call/handlers/<name>.ts — return a minimal symbolic payload ({verdict: "A" | "B"} style), not descriptive strings or narrative display fields 4. Write the thin SKILL.md per the threshold-check template — rendering via a symbol → text table, never via a computed algorithm 5. MANDATORY pre-flight audit — before registering the handler in the dispatcher, before deploying, before telling the user "done": run the checklist in references/cloud-split.md → "MANDATORY pre-flight audit" section. Report each item's result to the user. If any item fails, rewrite before moving on. 6. Skip the normal Step 4 "write scripts" — there usually aren't any for cloud-split skills (unless you need client-side rendering of server output)

Why the audit is mandatory: a real incident during skill-creator development produced a cloud-split skill whose handler returned {score, verdict: "below", display: "2+6=8 (below 10)"}. Architecture was correct; protection was zero. The audit catches this class of bug before it ships.

Step 4: Implement

1. Write scripts in scripts/ — test by running directly 2. 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

3. 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

1. In a new conversation, invoke /lovstudio:<name> — confirm it triggers 2. Notice struggles → edit SKILL.md / scripts in the source repo 3. 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: 1. Check user memory and conversation context first 2. Pre-fill what you can 3. 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

Changelog

All notable changes to this skill are documented here. Format: Keep a Changelog · Versioning: SemVer

[2.0.0] - 2026-04-18

Changed

• Rewrite for per-skill-repo architecture. Each skill is now an independent repo at lovstudio/{name}-skill instead of a subdirectory of a monorepo.
• Default scaffold path: ~/lovstudio/coding/skills/{name}-skill/ (was skills/lovstudio-{name}/).
• Install hint: git clone each skill repo (replaces npx skills add lovstudio/skills).
• init_skill.py: accepts --paid, auto-creates .gitignore, and prints gh repo create + symlink + index-registration next-steps instead of monorepo-dev-flow hints.

Added

• Step 5b: PR to lovstudio/skills central index (skills.yaml + README.md).
• Step 5d: lovstudio.ai ISR cache revalidation via skills-index tag.
• Migration note for legacy skills still in the monorepo structure.

Removed

• Step 0 (repo choice): lovstudio/pro-skills was archived 2026-04-16. paid now lives only in index/skills.yaml as a business classification, not as a skill property.

[1.2.0] - 2026-04-15

Added

• Add Step 0: repo selection (lovstudio/skills vs lovstudio/pro-skills)
• Step 5c: create PR to chosen target repo instead of push to main

[1.1.1] - 2026-04-14

Fixed

• Add publish workflow: symlink chain + git push to Step 5

[1.1.0] - 2026-04-14

Added

• Fix init_skill.py repo detection — prefer lovstudio-skills over cwd
• README template now includes version badge
• Remove CHANGELOG from 'What NOT to Include' (managed by skill-optimizer)

lovstudio:skill-creator

Scaffold new skills for the lovstudio ecosystem. Each skill is an independent GitHub repo at lovstudio/{name}-skill, registered in the central index at `lovstudio/skills`.

Part of lovstudio skills — by lovstudio.ai

Install

git clone https://github.com/lovstudio/skill-creator-skill ~/.claude/skills/lovstudio-skill-creator

What It Does

┌────────────────────────────────────────────────────────────┐
│  You: "封装成 wcx skill"                                    │
└────────────────────────────┬───────────────────────────────┘
                             │
                             ▼
┌────────────────────────────────────────────────────────────┐
│  init_skill.py wcx                                          │
│                                                             │
│  ~/lovstudio/coding/skills/wcx-skill/                       │
│  ├── SKILL.md      ← AI reads this                          │
│  ├── README.md     ← Humans read this on GitHub             │
│  ├── .gitignore                                             │
│  └── scripts/      ← Python CLI scripts                     │
└────────────────────────────┬───────────────────────────────┘
                             │
                             ▼
┌────────────────────────────────────────────────────────────┐
│  Implement → gh repo create lovstudio/wcx-skill --push      │
│           → PR into index/skills.yaml + index/README.md     │
│           → symlink to ~/.claude/skills/lovstudio-wcx       │
└────────────────────────────────────────────────────────────┘

Quick Start

# Scaffold
python3 ~/.claude/skills/lovstudio-skill-creator/scripts/init_skill.py wcx

# → ~/lovstudio/coding/skills/wcx-skill/
#     ├── SKILL.md       (TODO placeholders)
#     ├── README.md      (version badge + install stub)
#     ├── .gitignore
#     └── scripts/

Then:

1. Implement scripts/ and fill the TODOs in SKILL.md / README.md 2. cd ~/lovstudio/coding/skills/wcx-skill && git init && git add -A && git commit -m "feat: initial release" 3. gh repo create lovstudio/wcx-skill --public --source=. --push 4. Add an entry to ~/lovstudio/coding/skills/index/skills.yaml + a row to its README.md, then PR 5. Symlink into ~/.claude/skills/lovstudio-wcx for local use

Architecture

The lovstudio skill ecosystem (2026-04-16 refactor):

paid: true/false lives only in index/skills.yaml — never in SKILL.md.

Differences from Official skill-creator

License

MIT

Templates

SKILL.md Template

---
name: lovstudio:<name>
description: >
  <What it does — 1-2 sentences.>
  <When to trigger — specific scenarios, file types, user phrases.>
  Also trigger when the user mentions "<中文触发词>", "<english trigger>".
license: MIT
compatibility: >
  Requires Python 3.8+ and <library> (`pip install <library>`).
  Cross-platform: macOS, Windows, Linux.
metadata:
  author: lovstudio
  version: "0.1.0"
  tags: <space-separated tags>
---

# <name> — <Short Title>

<1-2 sentence overview.>

## When to Use

- <Scenario 1>
- <Scenario 2>

## Workflow (MANDATORY)

### Step 1: <First action>

python3 ~/.claude/skills/lovstudio-<name>/scripts/<script>.py --flag value

### Step 2: Ask the user

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

### Step 3: Execute

python3 ~/.claude/skills/lovstudio-<name>/scripts/<script>.py --input <path> --output <path>

## CLI Reference

| Argument | Default | Description |
|----------|---------|-------------|
| `--input` | (required) | ... |
| `--output` | `output.ext` | ... |

## Dependencies

pip install <library> --break-system-packages

README.md Template

# lovstudio:<name>

![Version](https://img.shields.io/badge/version-0.1.0-CC785C)

<One-line description.>

Part of [lovstudio skills](https://github.com/lovstudio/skills) — by [lovstudio.ai](https://lovstudio.ai)

## Install

git clone https://github.com/lovstudio/<name>-skill ~/.claude/skills/lovstudio-<name>

Requires: Python 3.8+ and `pip install <library>`

## Usage

python3 ~/.claude/skills/lovstudio-<name>/scripts/<script>.py --input file.ext --output result.ext

## Options

| Option | Default | Description |
|--------|---------|-------------|
| `--input` | (required) | ... |
| `--output` | `output.ext` | ... |

## License

MIT

Notes

• Version source of truth: README.md badge. SKILL.md frontmatter

metadata.version is kept in sync by skill-optimizer.

• Start at 0.1.0, not 1.0.0 — per repo release conventions (stay in 0.x

unless explicitly promoted).

• paid is not in SKILL.md frontmatter. It lives only in

~/lovstudio/coding/skills/index/skills.yaml.