agent-skill-kit-description-optimizer
Optimize a SKILL.md description for trigger quality — generate synthetic positive and negative queries, score the current description by hit-rate vs false-positive, and propose three ranked rewrites. Use when the user asks to auto-tune, improve, or rewrite a skill description, fix a skill that never fires, or measure description quality.
- License 许可
- Apache-2.0
- 最近更新
- 2026-08-25
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- agent-skill-kit-description-optimizer
- tier
- app
- license
- Apache-2.0
- description
- Optimize a SKILL.md description for trigger quality — generate synthetic positive and negative queries, score the current description by hit-rate vs false-positive, and propose three ranked rewrites. Use when the user asks to auto-tune, improve, or rewrite a skill description, fix a skill that never fires, or measure description quality.
- compatibility
- requires `skills-ref` CLI
03 SKILL.md 正文
Agent Skill Description Optimizer
Wraps skills-ref optimize. Generates trigger queries, scores the current description against the F04 rubric, and proposes three deterministic rewrites. The --apply N flag commits the chosen variant back to disk with byte-preservation of every other line.
When to use
- "Improve this description"
- "Why doesn't my skill ever fire?"
- "Optimize the SKILL.md descriptions in this tree"
- "Rewrite this description to score higher"
- "Measure description quality before shipping"
Where LLM-quality variants come from
The CLI ships deterministic variants only — three template-based transforms, < 200 ms, no network, no API keys, no provider config. This is intentional: when the skill runs inside an AI harness (Claude Code, an SDK agent, etc.), the calling harness is itself an LLM with provider credentials already attached. Asking the CLI to hold a separate API key duplicates auth surface for no benefit.
When higher-quality rewrites are wanted, the harness does the work:
- Run
skills-ref optimize <dir> --baseline-only --format jsonto get the current score + breakdown. - The harness reads the SKILL.md and generates its own three improved descriptions, using whatever model/auth it already has.
- The harness writes the chosen description directly into the YAML frontmatter (Edit / Write).
- Run
skills-ref validate <dir>to confirm the post-edit file passes (the same gate--applyuses internally).
--apply N remains useful for the deterministic case — it preserves bytes and auto-rolls back on validation failure.
Invocation
# Score the current description only (no rewrites)
skills-ref optimize /path/to/skill-dir --baseline-only
# Score + propose three ranked variants (sorted by F04 score desc)
skills-ref optimize /path/to/skill-dir
# Apply variant 0 in-place (with re-validation safety + auto-rollback)
skills-ref optimize /path/to/skill-dir --apply 0
# Machine-readable output for the CI gate
skills-ref optimize /path/to/skill-dir --format json
Output shape
Human format reports the baseline and each variant on its own block:
/abs/path/SKILL.md
provider: none
baseline: score=98/100 hit=6/8 false=1/8
variants:
[0] score=99/100 hit=5/8 false=1/8
rationale: lead-with-verb + append trigger phrase
text: <rewritten description>
JSON format is canonical sorted-key output containing baseline, variants, queries, provider, path. Both runtimes emit byte-identical JSON (parity-tested against the frozen .agents/skills/agent-skill-kit-commons/fixtures/optimize/expected/low-score-vague.json snapshot).
Two scores per variant
score— F04's description-quality score (0–100). The deterministic ranker sorts variants by this.hit_rate.score—(positive_hits / positive_total - false_positives / false_total) * 100, clamped to 0–100. Surfaced for CI gating without re-running F04's scorer.
Safety contract for --apply
- The
description:line in the YAML frontmatter is replaced; every other line is byte-preserved. - A
.bakfile is created before write. - After write, the validator runs against the same directory.
- On validation failure, the backup restores the original and the
.bakis removed; the CLI exits 1. - On success, the
.bakis deleted; the CLI exits 0.
Limits
- The deterministic rewriter is intentionally conservative — three template-based transforms, no LLM. For higher-quality variants, see "Where LLM-quality variants come from" above; the harness generates them, the CLI does not.
- The
chars / 4token estimate from the prompt emitter is not used here; the optimizer's input is bounded by the body excerpt (first 1000 chars) and the query JSON. - The trigger-phrase regex re-uses F04's; both share the same edge cases (e.g. "for " inside "helpful for" matches as a trigger). The lint pipeline is the canonical filter; this skill defers to it.
Reference
Full specification: see the canonical spec at ../../../docs/agentskills.io.md.
04 同仓库更多 Skills
validation_handoff
Forces the agent to conclude its response by generating a strict validation checklist and outlining pending actions, focusing heavily on defensive execution and edge-case testing.
project-ployglot-project-scafford
Scaffold a polyglot library project as TypeScript + Python twin packages under `packages/ts/` + `packages/py/`, with a shared `SPEC.md`, cross-language `tests/parity/fixtures.json`, side-by-side `examples/sdk/` + `examples/api/` documentation, per-package `Makefile`, and a root orchestrator that exposes `make ci`. Open-source friendly — no organization-specific paths or scopes baked in. Use when starting a new polyglot library, porting a single-language library to a twin, or auditing/regularizing an existing two-language repo against the canonical layout.
playwright-ui-locator
Auto-heal Playwright tests after a frontend developer changes a div's class, id, or other selector. Catches a failing Playwright test, captures the old vs new DOM tree, finds the element that drifted, derives the most stable replacement locator, and proposes the fix as a GitHub pull request (confident heals) or files a GitHub issue (ambiguous / element-removed cases) — never editing the working tree directly. Trigger when Playwright tests fail with "locator resolved to 0 elements", "Timeout waiting for selector", or after a UI refactor / class rename / Tailwind cleanup broke previously-passing tests.
org-learn-context-window
Distill the current conversation into a reusable command or skill artifact. Use when the user wants to capture a workflow they just executed (create a reusable slash command) or formalize a resolution/mistake/correction into a reusable skill so the same class of issue never recurs.
org-agent-skill-creator
Scaffold and validate scope-aware agent skills (company, enterprise, org, team, project, application). Use when the user asks to create a new agent skill, generate a SKILL.md file, scaffold a skill directory, or validate that existing skill directories meet SKILL_SPEC.md (frontmatter, naming rules, structure, scope/tier).
app-workshop-session-pdf-recap-next
Extract content from a workshop session PDF and produce a structured recap focused on (1) what was learned, (2) next steps, and (3) possible enhancements. Ingests a single PDF file path, parses session material (slides, transcripts, exercises, Q&A), and emits a Markdown report with Learning Recap, Next Steps, and Enhancement Opportunities sections with page-level traceability. Use when the user asks to "summarize a workshop", "recap a training PDF", "pull next steps from a session deck", or provides a workshop/seminar/tutorial PDF and wants a learn-and-act summary.