lov-skill-optimizer

skill-optimizer — automatically optimizes Agent Skills and maintains version and distribution status

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:

Resolve symlinks and record the actual path.
Identify the Git root, branch, and dirty worktree state.
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.
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:

Fixes explicitly mentioned in the conversation;
error findings;
warn findings;
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.

General feedback loop

When a user raises modification feedback during a Skill-driven task, before continuing with the current artifact you must do the following:

First determine whether the feedback is task-specific(this time only) or reusable(reusable across tasks).
task-specific Modify only the current task; do not change the Skill.
reusable First determine the scope: for domain rules, first update the corresponding canonical Skill; for rules that apply to all Skills, first update the shared specification.
After completing the rule update, versioning, lint, and distribution verification, then apply the modification to the current task.
reusable The modification invalidates previous "confirm," "continue," and "go ahead" instructions; after completing the modification of the current artifact and reading it back, you must stop and wait for the user's next instruction, and must not automatically proceed to publishing, committing, or any other external write.