AGENT SKILL

tune-skill

Audit and fine-tune an existing agent skill so it triggers when it should and hands off cleanly to its siblings. Reads the real SKILL.md and references, checks the description, sibling overlaps, stale names and counts, handoffs and command routing, makes minimal evidenced edits, validates them with a script, writes near-miss test cases, and re-checks the whole family against a saved baseline. Use whenever the user wants to fine tune, improve, tighten, debug or review a skill, says a skill is not triggering or fires on the wrong requests, wants two skills to work together or split cleanly, asks whether anything in a set of skills got worse, or pastes a SKILL.md or repo link and asks what is wrong with it, even if they never say "audit". Not for creating a skill from scratch (use draft-skill) or from a list of prompts (use prompts-to-skill), or for making a skill run automatically at a moment such as before git push (use skill-to-mod).

License 许可
MIT
最近更新
2026-11-14
Stars
★ 0
Forks
0

01 前言 Front Matter

name
tune-skill
version
1.0.0
description
Audit and fine-tune an existing agent skill so it triggers when it should and hands off cleanly to its siblings. Reads the real SKILL.md and references, checks the description, sibling overlaps, stale names and counts, handoffs and command routing, makes minimal evidenced edits, validates them with a script, writes near-miss test cases, and re-checks the whole family against a saved baseline. Use whenever the user wants to fine tune, improve, tighten, debug or review a skill, says a skill is not triggering or fires on the wrong requests, wants two skills to work together or split cleanly, asks whether anything in a set of skills got worse, or pastes a SKILL.md or repo link and asks what is wrong with it, even if they never say "audit". Not for creating a skill from scratch (use draft-skill) or from a list of prompts (use prompts-to-skill), or for making a skill run automatically at a moment such as before git push (use skill-to-mod).

02 资源文件 7

03 SKILL.md 正文

Tune skill

Fine-tuning is a set of small, evidenced edits to a skill that already exists. It is not a rewrite. The goal is a skill that triggers on the right requests, stays out of its siblings' way, and passes work along in a defined shape.

Ground rules

  • Read the real SKILL.md first. READMEs, repo descriptions and listings drift from the file the agent actually loads. Any claim about a skill must come from its SKILL.md or its references. If you can't open a file, name it and say what you are inferring instead.
  • Check your own claims. If a file you read later contradicts something you said earlier, say so plainly and correct it. Don't quietly route around it.
  • Minimal edits, the author's voice. Change what the audit found and nothing else. Keep frontmatter keys you don't recognise (version, argument-hint, user-invocable). Never weaken honesty, safety or privacy rules.
  • Don't claim what you didn't run. Say which checks ran, which test cases were only written, and which files you never saw.

Workflow

1. Collect

Get the SKILL.md of the target skill and of every sibling it touches, plus any references you can reach. If the user gives a link you can't open, ask for the file text or its URL. If the skill is a folder on disk, run the check script (step 6) now for a first read.

2. Map

Write a short inventory per skill: what its description promises, its modes or commands, the reference files it names, and what it hands off and to whom. Put sibling descriptions and command lists side by side. Overlaps only show up when you can see both.

3. Audit

Work through references/audit-checklist.md. For each finding record the evidence (quote the line), the severity (breaks triggering, confusing, or cosmetic) and the smallest fix. Report the most severe first.

4. Settle boundaries

When two skills claim the same request, give it one owner. Use the split the user's own design already uses (for example verdict versus artifact: one skill judges, the other writes). Ask the user only when their design doesn't settle it, and ask once.

5. Edit

Make the smallest change that fixes each finding. When the user will drop the result straight into a repo, hand back whole replacement files and copy untouched text exactly. When a fix needs a new shared piece (a handoff format, say), add a new reference file instead of editing one you haven't seen. List any reference files that probably need a matching update.

6. Validate

Run the check script on each skill folder:

python scripts/check_skill.py <path-to-skill-folder>

It checks that the name matches the folder, the description fits the 1024-character limit and has trigger and boundary wording, the H1 matches the name, referenced files exist, and the body stays a reasonable length. Fix every FAIL. Judge each WARN. A NOTE means the body ties the skill to a moment Claude does not choose (before pushing, deploying, releasing); see section H of the checklist. The script reads CRLF and BOM files and works without PyYAML; python -I scripts/test_check_skill.py is its self-check. If you only have pasted text, save the SKILL.md into a folder named after the skill and run it there; missing-reference warnings are expected in that case.

7. Write test cases

Follow references/test-cases.md. Every boundary you changed gets one case on each side. Run them by hand against the descriptions. Some agents ship an automated triggering loop in their authoring tooling; if you didn't run one, don't imply you did. Say which you did.

8. Regress the family

One skill's fix can break a sibling: a reworded description now shares a trigger phrase, or a renamed skill leaves "(use old-name)" behind elsewhere. After editing, re-check every skill in the family against the last accepted state:

python scripts/regress.py <folder-of-skills> [more folders] --baseline health.json
python scripts/regress.py <folders> --baseline health.json --write   # accept, once reviewed

It runs check_skill.py on every SKILL.md it finds and adds two family-wide checks: a dangling handoff (a description says "(use X)" and no X is in the family) and a trigger collision (two descriptions quote the same phrase). Anything new since the baseline is a regression and exits 1; anything that went away is an improvement. Pass skills that live elsewhere with --external name,name. Write the baseline only after reading the regressions, never to silence them. Keep health.json next to the family (a site repo, a marketplace) so a scheduled CI job can run the same command and open an issue when it fails; python -I scripts/test_regress.py is its self-check.

9. Report

Keep it short:

  • What changed, per skill, and why (one line each).
  • Corrections to anything you said earlier.
  • What you could not see or did not run.
  • One next step.

Lead with the changes, not with the process.

04 同仓库更多 Skills

arm-pz
arm-pz/caffeinity-skills

tune-and-ship

Takes one published skill at a time from as-is to tuned, fact-checked, released and live, then moves to the next one in the catalog. Each run tunes the skill with tune-skill, checks every version number, flag, price and command it states against the primary source, re-reads its siblings' real SKILL.md files, polishes the listing with findable-polish, writes the version and release notes, opens one PR, and after the merge confirms the site page and marketplace copy are live. Use whenever the user wants to fine-tune their other skills, work through the catalog, give a published skill the full treatment, fact-check a skill's claims, or ship a tune instead of drafting it, even if they never say "ship". Not for a tune with no release (use tune-skill), drafts with nothing pushed (use tune-and-polish), a new skill (use skill-launch), regressions from the nightly health check (use caffeinity-routing's Descale brew), or a whole collection (use skill-estate).

★ 0
arm-pz
arm-pz/caffeinity-skills

skill-estate

Takes a whole collection of agent skill repos from scattered to published, consistent and self-maintaining, in gated phases: inventory every repo, reconcile site, marketplace and README listings, test and tune the family, close workflow gaps, wire publishing so new skill repos go live on their own, bundle a plugin with agents, add trigger tests and directory listings, and leave a maintenance loop and a map. Each phase hands off to the skill that owns it and ends in PRs. Use when someone's skills site and GitHub disagree, wants all their skill repos audited or cleaned up, wants new skills to publish themselves, or wants that cleanup repeated on another org, even if they never say estate. Not for one skill (use tune-skill), one listing (use findable), the site pipeline alone (use publish-pipeline), or weekly upkeep (use caffeinity-routing's Descale brew).

★ 0
arm-pz
arm-pz/caffeinity-skills

paper-trail

Drafts the policy pages a small product needs before it takes money or data (privacy policy, terms of service, refund policy, cookie notice) from a fact sheet about what the product actually collects, stores, shares and charges, then checks the drafts for placeholders, missing sections and facts nobody supplied. Use when someone needs a privacy policy, terms, refund or cookie page for a site, app, SaaS, newsletter or digital product, asks what legal pages they need before launch, or wants existing policy pages checked against what the product really does, even if they never say "legal". Not legal advice and not for contracts, NDAs or employment documents (use a lawyer), and not for the launch plan itself (use solo-income-blueprint) or the site build (use site-prompt).

★ 0
arm-pz
arm-pz/caffeinity-skills

course-builder

Designs a course for a group of learners (a class, cohort, workshop series, bootcamp or internal training): measurable outcomes, a module sequence with prerequisites, activities and assessments aligned to each outcome, a time budget that fits the hours available, and a rubric, then checks the plan with a script so no outcome goes untaught or unassessed. Use when someone is teaching others and asks for a curriculum, syllabus, course outline, module plan, cohort or workshop structure, or wants an existing course checked for gaps and overload, even if they never say "curriculum". Not for one person's own learning plan (use study-system), for being taught the topic (use topic-primer), or for marketing the course (use sales-copy).

★ 0
arm-pz
arm-pz/caffeinity-skills

wordsmith

Write, draft, rewrite, edit, proofread, polish and improve text while preserving the author's intended meaning, facts and voice. Use when the user wants clearer, shorter or better-toned writing; grammar, structure or flow fixes; emails, website or marketing copy, headlines, outlines or summaries; a different reading level; an accessibility, inclusivity or accuracy review; or content prepared for publication, even if they never say "edit". Also handles /wordsmith commands such as draft, critique, audit, tighten, tone and final. Not for resumes, CVs or LinkedIn profiles (use recruiter-lens if installed), not for code or code comments, and not for building .docx or .pdf files (write the text here, then use the file skill).

★ 0
arm-pz
arm-pz/caffeinity-skills

web-preflight

Use when shipping, deploying, publishing, launching, reviewing, or pre-flighting a website or API and you want a lightweight check for accidental exposure of secrets, source or configuration files, admin and debug surfaces, unsafe redirects, missing security controls, and misleading 200 responses. Trigger phrases include "before we ship", "security check", "preflight", "audit the site", "check the production URL", "is my .env exposed", and "why does /.env return 200", including when access-log or analytics evidence is supplied. Checks only sites the user owns or is authorized to assess, with bounded GET and HEAD requests and a fixed compact path set; distinguishes genuine resources from SPA catch-all and blanket WAF responses. Not for penetration testing, exploitation, credential testing, broad port scanning, or application-code review; use a dedicated authorized security-testing or code-review workflow instead.

★ 0