AGENT SKILL

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:

  1. Run skills-ref optimize <dir> --baseline-only --format json to get the current score + breakdown.
  2. The harness reads the SKILL.md and generates its own three improved descriptions, using whatever model/auth it already has.
  3. The harness writes the chosen description directly into the YAML frontmatter (Edit / Write).
  4. Run skills-ref validate <dir> to confirm the post-edit file passes (the same gate --apply uses 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 .bak file is created before write.
  • After write, the validator runs against the same directory.
  • On validation failure, the backup restores the original and the .bak is removed; the CLI exits 1.
  • On success, the .bak is 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 / 4 token 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

carlosmarte
carlosmarte/ai-agent-artifacts

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.

★ 0
carlosmarte
carlosmarte/ai-agent-artifacts

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.

★ 0
carlosmarte
carlosmarte/ai-agent-artifacts

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.

设计师代码审查测试与质量
★ 0
carlosmarte
carlosmarte/ai-agent-artifacts

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.

Skill与智能体开发
★ 0
carlosmarte
carlosmarte/ai-agent-artifacts

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

Skill与智能体开发
★ 0
carlosmarte
carlosmarte/ai-agent-artifacts

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.

文档处理
★ 0