Skill 精修师 · Skill Refiner

This is a non-interactive maintenance workflow. It infers the target and prioritizes issues from the current conversation, then supplements them with a generic lint pass. When several Skills are named in one request, process them in the order named and emit a separate result block for each Skill.

Target and source resolution

Prefer an explicit canonical path whenever the Skill is outside a conventional skills repository:

python3 scripts/lint_skill.py --path /absolute/path/to/skill --json
python3 scripts/inspect_layout.py --path /absolute/path/to/skill --json

For a name, accept foo, lov-foo, or foo-skill. Resolution may find a source checkout, an installed copy, or a catalog entry. Before editing:

1. Resolve symlinks and record the actual path.
2. Identify the Git root, branch, and dirty worktree state.
3. Treat a source checkout as canonical. If the target is an installed copy, locate a matching source checkout; when no source exists, report that the supplied path itself is canonical instead of silently editing another copy.
4. Record every discovered installation and catalog path. A copy is synced only when its content digest matches the source; a missing location is not_discovered, never complete. A symlink is synced only when it resolves to the canonical source.

Paid/encrypted repositories may keep the authored specification at src/SKILL.md and the installable payload under public/. Treat the repository root as canonical, lint and version the authored spec, and compare or sync only the public/ payload to installations. Never copy plaintext src/ content into an installed paid Skill.

Do not absorb pre-existing edits into a maintenance commit. If a target file is already dirty, review the overlap before editing it and stage only the exact files changed by this optimization.

Workflow (mandatory)

Step 0: Classify feedback scope

When the optimization is triggered by a user correction, classify it before choosing targets:

• task-specific: applies only to the current artifact or one-off value. Do not edit a Skill.
• skill-specific reusable: applies to future runs of one domain or platform. Optimize the relevant canonical Skill.
• global reusable: changes how every Skill should handle feedback, authorization, sequencing, or handoff. Update the host's active user-level shared instruction artifact once (for example the applicable user-level AGENTS.md); do not paste the same policy into every domain SKILL.md.

If a global policy was previously placed in one domain Skill, move it to the shared layer and remove the domain duplicate while preserving any genuinely domain-specific rule learned in the same incident. A shared policy file may be outside the Skill repository; report its path and verification state explicitly instead of pretending it is part of the Skill package.

Any reusable correction invalidates prior terminal approval for the active task. Finish the policy/Skill optimization and validation first, then apply the correction to the current artifact, report the new state, and stop for the user's next instruction. Do not continue into publishing, submission, or another external write using a pre-correction “confirm”, “continue”, or “go ahead”.

Step 1: Extract targets and context

Normalize every explicitly named Skill and preserve the user's order. Strip the lov- prefix only for lookup; keep the public Skill identifier in reports. Collect the current-conversation fix list first: broken flags, trigger misses, wrong paths, confusing output, missing modules, compatibility requirements, or other concrete symptoms.

For every correction, distinguish four pieces of evidence: the observed defect, the latest user-approved baseline, the requested delta, and any remedy the user rejected. A rejected remedy is negative evidence, not a reusable best practice. Preserve the approved baseline outside the requested delta, and do not encode a failed over-correction into the target Skill.

Step 2: Baseline lint

For each target, run the linter against the resolved canonical path:

python3 scripts/lint_skill.py --path /absolute/path/to/skill --json

Prioritize findings in this order:

1. Fixes explicitly mentioned in the conversation;
2. error findings;
3. warn findings;
4. cheap, low-risk info findings.

The baseline must include version-source drift between README.md, SKILL.md frontmatter, and skill.yaml. Portability findings are high priority for a reusable Skill: move personal paths to flags, environment variables, or references/user-config.md, or mark a genuinely author-only dependency in compatibility.

Classify the Skill's normal output before editing. If it generates, edits, reviews, renders, packages, or publishes text visible to an end user or reader, top-level depends_on must contain lov-branding-consistency. This dependency gates authored presentation copy only; it must not rewrite quotations, transcripts, source data, legal text, identifiers, or code without permission.

Step 3: Apply focused fixes

Edit only the canonical source. Keep the Skill's public trigger surface, compatibility aliases, storage contracts, and user-facing semantics explicit. Use progressive disclosure when SKILL.md grows beyond roughly 500 lines. Add a script or reference file only when it resolves a concrete audit finding or conversation issue.

When the user has already approved an artifact and then requests a localized fix, optimize the domain Skill around a minimal-delta contract: lock accepted layout, copy, data, and behavior as invariants; change only the defective region; verify the whole artifact afterward. A broad redesign requires an explicit new request, not an inferred opportunity.

The linter checks both root SKILL.md repositories and paid/encrypted src/SKILL.md repositories:

• Agent Skills-compatible frontmatter and trigger phrases;
• README version badge and installation command;
• metadata.version, README badge, and skill.yaml version consistency;
• CLI use of argparse and obvious script hygiene;
• TODO placeholders and oversized instruction bodies;
• personal paths, fixed runtime paths, and missing user configuration;
• source/install/catalog layout evidence.
• missing lov-branding-consistency dependency for audience-visible text Skills.

Step 4: Bump semver and changelog

Use the path-aware version tool so all version surfaces move together:

python3 scripts/bump_version.py \
  --path /absolute/path/to/skill \
  --type minor \
  --message "add guarded project rename workflow" \
  --change "report source, installation, and catalog synchronization state"

Choose patch for bug, wording, frontmatter, or lint fixes; minor for a new flag, reference, module, or expanded workflow; major for a breaking CLI or removed behavior. Stay in 0.x unless the user explicitly requests otherwise. The tool updates README.md, the authored SKILL.md, paid-skill public wrappers, skill.yaml, and CHANGELOG.md and refuses to duplicate an existing changelog version.

Step 5: Re-lint and inspect layout

python3 scripts/lint_skill.py --path /absolute/path/to/skill --json
python3 scripts/inspect_layout.py --path /absolute/path/to/skill --json

Do not report remaining lint warnings: none unless the final JSON was read. Do not report synchronization as complete unless every discovered distribution copy and required catalog check has been verified after the source change. Keep distribution_state, catalog_state, and the aggregate sync_state separate: an installed copy can be complete while an undiscovered catalog keeps the aggregate state partial. A discovered catalog is complete only when its matching Skill payload digest is synced.

Step 6: Synchronize discovered distributions

inspect_layout.py checks conventional and configured installation roots: AGENT_SKILLS_DIR, CLAUDE_SKILLS_DIR, CODEX_SKILLS_DIR, SKILLS_DIR, plus the host's agent-managed fallback roots. It also checks explicit --install-root and --catalog-root values plus the nearby unified lovstudio-skills catalog and legacy general/dev catalog names. Use an environment variable or explicit flag when the installation root is outside the conventional layout.

For a non-symlink installation copy, first run a read-only sync plan. Paid repositories automatically use their public/ payload:

python3 scripts/sync_installation.py \
  --source /absolute/path/to/canonical-skill \
  --target /absolute/path/to/installed-skill \
  --json

After reviewing missing, changed, and extra, apply the exact copy with:

python3 scripts/sync_installation.py \
  --source /absolute/path/to/canonical-skill \
  --target /absolute/path/to/installed-skill \
  --apply --json

Use --prune only when removing extra files from the installation copy is explicitly part of the task. Symlink installations are verified, not copied. For a catalog, use its own scripts only when they are actually present:

python3 scripts/sync-skills.py
python3 scripts/render-marketplace.py
python3 scripts/render-readme.py
python3 scripts/validate_deps.py

Run only the commands that exist in that catalog checkout. If no catalog is discovered, report not_discovered; if source and installation are updated but the catalog is stale or unavailable, report partial. Never invent a catalog path or claim a live-site update from a local source commit.

Step 7: Commit and push exact source changes

Inspect git diff --check, then stage the listed changed files explicitly:

git add -- SKILL.md README.md CHANGELOG.md skill.yaml scripts references
git diff --cached --name-only
git commit -m "fix(<skill-name>): <one-line summary>"
git push origin HEAD

Use feat for a minor feature and feat! for a breaking change. If the source checkout has no remote, commit on its current branch and report push: not_configured; do not imply that a remote release happened. If a catalog is a separate repository, commit and push it independently after its own validation.

Final report contract

Return one block per optimized target, with no trailing summary:

optimized: lov-<name>
version:   <old> → <new>
source:    <canonical path> (<clean|dirty>)
distribution:
  - <path>: <synced|drifted|not_discovered>
catalog:
  - <path>: <synced|partial|not_discovered>
fixes:
  - <bullet 1>
  - <bullet 2>
remaining lint warnings: <count>  (or "none")
sync state: <complete|partial|not_discovered>

The keys stay stable for machine parsing; the values and fix bullets follow the user's language. A failed or skipped push, installation sync, or catalog sync must appear in the relevant state rather than being omitted.

Runtime context

Read this Skill's skill.yaml when the host supplies skill-runtime/v1. Use only fields declared there. Profile data is for public identity facts and preferences are for output language/timezone; neither replaces the canonical source, installation, or catalog evidence collected by this workflow.

CLI reference

python3 scripts/lint_skill.py --path PATH [--json]
python3 scripts/lint_skill.py --all --root PATH [--json]
python3 scripts/bump_version.py --path PATH --type patch|minor|major -m MESSAGE
python3 scripts/inspect_layout.py --path PATH [--install-root PATH] [--catalog-root PATH] [--json]
python3 scripts/sync_installation.py --source PATH --target PATH [--apply] [--prune] [--json]

All bundled tools use Python's standard library only.

通用反馈闭环

用户在 Skill 驱动任务中提出修改意见时，继续当前产物前必须执行：

1. 先判断意见是 task-specific（仅本次）还是 reusable（可跨任务复用）。
2. task-specific 只修改当前任务，不改 Skill。
3. reusable 先确定作用域：领域规则先更新对应 canonical Skill；适用于所有 Skill 的规则先更新共享规范。
4. 完成规则更新、版本、lint 与分发核验后，再把修改应用到当前任务。
5. reusable 修改会使此前的“确认”“继续”“发吧”失效；完成当前产物修改和回读后必须停下，等待用户下一步指示，不自动进入发布、提交或其他外部写入。