lovstudio-skill-creator

lovstudio-skill-creator

Scaffold every new lovstudio skill as an independent GitHub repo under lovstudio/{name}-skill. lovstudio/dev-skills is a generated distribution bundle: its skills/{name}/ directories mirror tagged releases and must not be edited as source.

Architecture

<configured workspace>/
├── lovstudio-general-skills/     ← general skills index (lovstudio/general-skills repo)
│   ├── skills.yaml                ← machine-readable manifest (paid flag lives here)
│   └── README.md                  ← human-readable catalog
├── lovstudio-dev-skills/          ← generated aggregate for meta/dev skills
│   ├── skills.yaml
│   ├── .claude-plugin/marketplace.json
│   └── skills/{name}/             ← mirrors the latest independent release
│       ├── SKILL.md
│       ├── README.md
│       ├── scripts/
│       └── references/
├── skills/                        ← independent per-skill source repos
│   └── {name}-skill/
│       ├── SKILL.md
│       ├── README.md
│       ├── CHANGELOG.md           ← managed by skill-optimizer
│       ├── scripts/               ← standalone Python CLI scripts
│       └── references/            ← optional progressive-disclosure docs
└── ...

<agent skills dir>/lovstudio-{name}  ← install or symlink to the source checkout

Key facts:

• Default GitHub repo name: lovstudio/{name}-skill (with -skill suffix)
• Default local source root: LOVSTUDIO_SKILL_CREATOR_REPOS_ROOT, profile lovstudio.skill_repos_root, or the current directory.
• General skills checkout path: configured by the maintainer's local checkout.
• Dev-skills catalog entries point to the independent lovstudio/{name}-skill repo. Its synchronization workflow mirrors the latest GitHub Release.
• Agent runtimes read an installed directory named lovstudio-{name}/.
• Frontmatter name: lovstudio-{name} (Agent Skills-compatible). Legacy namespace-style names are kept only for older skills and should not be copied into new templates.
• Frontmatter depends_on: optional list of required skill names from those skills' own SKILL.md frontmatter. Use it when one skill must reuse another instead of duplicating implementation. In skills.yaml, use catalog names such as find-logo.
• paid: true/false lives only in lovstudio-general-skills/skills.yaml, never in SKILL.md
• User-specific paths, brand profiles, design guides, and output directories must be initialized through explicit CLI flags, environment variables, or ~/.lovstudio/skills/profile.json. Do not hard-code personal workspace paths in reusable workflows.

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 commercial model decides the architecture, so it has to come before any implementation question.

Source repository invariant — do not ask: every skill source lives in its own lovstudio/{name}-skill repository. Never ask the user to choose a source repository or scaffold target. Catalog and bundle registration are downstream distribution decisions inferred from category and commercial model.

Required question order:

Q1. Commercial / protection model — ALWAYS ask first

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

What is this skill's distribution positioning?

1. Free (public) — Anyone can use it with git clone. Suitable for lead generation, general-purpose tools, open-source contributions.
2. Paid, ordinary IP — The core logic is process/template/prompt orchestration; users won't feel bad grepping it out. Use encrypted distribution + license authentication.
3. Paid, sensitive IP — Contains algorithm parameters/business rules/tuned prompts/API keys; users would feel bad decompiling it. Use cloud-split: core logic in the cloud, only a thin client locally.

Hint: If unsure → choose 2. Upgrading to 3 later is easier than downgrading.

This answer determines the subsequent process branches:

• Choose 1 → follow the standard public repo process
• Choose 2 → follow the encrypted skill process (be candid in the README: "encryption = authentication gate, does not guarantee anti-extraction")
• Choose 3 → stop and read references/cloud-split.md, then follow the cloud-split process

Q2. Problem & shape

• What problem does it solve? What is the input → output?
• 2-3 concrete usage examples
• Trigger phrases (Chinese + 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:

Let me first break down this skill's structure:

Public layer (the thin-client SKILL.md will expose these):

• [List specifically: conversation flow, input parsing, output rendering, error handling]

Protected layer (what needs to be hidden):

• [List specifically: algorithms/thresholds/rules/prompt engineering/keys/data]
• Or explicitly write "none — this skill has no core logic that needs protection"

Based on this breakdown, your choice of [Q1 answer] is [reasonable / unreasonable, suggest changing to X]. Confirm to continue?

Consistency check — if decomposition contradicts Q1, challenge it:

Q1 choice	Protected layer content	Judgment
Free	Any	✓ No protection issue
Encrypted	Non-empty	⚠️ Warning: encrypted does not prevent L2 grep; if truly sensitive, upgrade to cloud-split
Encrypted	Empty	✓ Reasonable (typical scenario: paid templates/workflows)
Cloud-split	Non-empty and substantive	✓ Reasonable
Cloud-split	Empty or trivial	✗ Stop and ask the user whether this is over-engineering, suggest downgrading to encrypted or free

Especially challenge trivial demos (like "sum of two numbers") — cloud-split's server-side cost + deployment complexity is a net negative for a skill that "actually has nothing to protect." Unless the user explicitly says "making a template/teaching sample," suggest downgrading.

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.

✗ Logic self-description (bad)	✓ Capability domain (good)
sum-gt-ten	threshold-check
extract-chinese-poem-style	text-style-analyzer
detect-viral-headline	text-scorer
calculate-compatibility	profile-matcher

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

• Pure instruction SKILL.md, or does it need a Python CLI script?
• (If Q1 chose 3: skip this question. cloud-split's "implementation" is a cloud handler, not a local script.)

Q4. User initialization layer — mandatory for reusable skills

Ask whether the skill needs user-specific workspace, output, identity, brand, or design-guide settings. If yes, design the initialization layer before writing scripts:

Does this skill need to read the user's own workspace, brand materials, design specs, or output directory?

1. No user config — Only processes the current input file/current directory.
2. User profile — Requires the user to initialize their own workspace/brand/output.
3. LovStudio internal only — Explicitly serves only the Mark/LovStudio private workspace.

Rules:

• Option 1: no absolute user paths in SKILL.md or scripts.
• Option 2: follow references/user-config.md; use CLI flags > env vars > shared profile > safe defaults > ask once.
• Option 3: mark compatibility and README as author-only, and keep all LovStudio paths in one configuration section instead of scattering them.

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.

Tier	Protects against	Does NOT protect against
Free	None	None
Paid / encrypted	Any random person git clone can use it (L1)	Technical users retrieve plaintext from local conversation logs (L2)
Paid / cloud-split	L1 + L2 + disassembling the client	Reverse-engineering the I/O to make an inferior clone

Core logic is truly not delivered to the user's machine only cloud-split. For other tiers, do not promise users "encryption protection."

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
• Any user-specific path, brand asset, design guide, or output root needs a configuration plan. Read references/user-config.md and include references/user-config.md in the scaffold for public/reusable skills.

Step 3: Initialize

Run the init script. Independent repo is the default:

python3 "$SKILL_DIR/scripts/init_skill.py" <name>

Independent repo creates <configured repos root>/{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 in the configured web repo's 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 (Chinese + English)
   • Body contains workflow steps, CLI reference, field mappings
   • Use AskUserQuestion for interactive prompts before running scripts
   • Add a user configuration section when the workflow touches paths, personal data, brand assets, or workspace conventions
   • Never assume personal workspace paths or a fixed agent runtime path in reusable workflow steps
   • 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 using the user's chosen agent skills directory
   • Dependencies
   • Usage examples, options table
   • ASCII diagrams if useful

See references/templates.md for SKILL.md / README.md templates. See references/user-config.md for the portable profile/env contract. See references/skill-standard.md for the current LovStudio skill standard.

Step 5: Publish

Always publish the skill's own repository first. Then infer distribution:

• Register general, public-facing, and paid skills in lovstudio/general-skills.
• Free Meta / Dev Tools skills may additionally be registered in lovstudio/dev-skills; its checked-in skill directory is a generated mirror of the independent release.
• Do not ask the user where the source should live.

Single Source Repository

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

cd <configured-repos-root>/<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 general-skills index

Edit the configured lovstudio-general-skills/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 the configured lovstudio-general-skills/README.md under the matching category section. Then PR against lovstudio/general-skills:

cd <general-skills-checkout>
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. Install for local availability

Make the skill immediately usable by installing or symlinking the source checkout into the user's agent skills directory as lovstudio-<name>.

5d. Synchronize to lovstudio.ai/skills (MANDATORY)

Publishing is incomplete until the skill is visible at https://lovstudio.ai/skills/<name>. After the catalog change reaches main, read references/publishing.md and run its cache-revalidation and live verification workflow.

Do not report the skill as published until /skills lists it, /skills/<name> returns HTTP 200, and the visible version and content match the release.

Dev-Skills Distribution Mirror

For a free Meta / Dev Tools skill, register its independent source in the configured lovstudio-dev-skills/skills.yaml:

Edit the configured lovstudio-dev-skills/skills.yaml:

- name: <name>
  repo: lovstudio/<name>-skill
  name_zh: <中文名>
  paid: false
  category: "Dev Tools"                 # or "Meta"
  version: "0.1.0"
  description: "<Agent-facing trigger description>"
  tagline_en: "<Human-facing English tagline>"
  tagline_zh: "<Human-facing Chinese tagline>"

Also update .claude-plugin/marketplace.json so the correct plugin includes "./skills/<name>", and add the repo to independent-skills.json. The mirror directory is populated from the latest release by scripts/sync-independent-skills.py; do not edit it manually.

• Meta skills → plugins[].name == "meta"
• Dev tooling → plugins[].name == "dev-tools"

Then render the READMEs:

GITHUB_TOKEN="$(gh auth token)" python3 scripts/sync-independent-skills.py sync
python3 scripts/render-readme.py

Install for local availability

Install or symlink the bundled skill directory into the user's agent skills directory as lovstudio-<name>.

Commit and push the aggregate metadata

git add independent-skills.json skills.yaml README.md README.en.md .claude-plugin/marketplace.json skills/<name>
git commit -m "chore(skills): mirror <name> release"
git push -u origin HEAD
gh pr create --fill

Do not register dev-skills-only skills in the general-skills index unless the user explicitly asks for the main Lovstudio skills index to list the bundle entry.

Step 6: Test & Iterate

1. In a new conversation, invoke lovstudio-<name> or a documented trigger phrase — confirm it triggers
2. Notice struggles → edit SKILL.md / scripts in the source repo
3. Commit, tag, and push in the independent source repo; aggregate mirrors are updated from releases

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 lovstudio-general-skills/skills.yaml
• Hard-coded personal workspace paths or private LovStudio brand files in reusable workflows

Migration Notes

For historical repo-layout migrations, read references/migration.md.