yzr-skill-management

Inputs and Outputs

Inputs: the user's request and the target skill directory (creation may have no target; the target of standard maintenance is the template and this file)
Outputs: audit delivers only a report and does not change files; creation / improvement delivers skill changes. For details seesection

Execution Principles

Design Principles

Single source: the same rule or fact is written in only one place: shape belongs to the template, automatically decidable checks belong to scripts (scripts read from the template and do not embed a copy of the definition); all other content belongs to SKILL.md by default, and when it is large enough to be worth splitting, it goes into ref/ (see "create directories on demand"); other locations only reference it, never restate it
Script mechanical work: checks that can automatically judge right from wrong, and judgment-free enumerable repetitive actions (such as generating skeletons and batch conversions), are all written as scripts. Do not rely on reminders in the prose, and do not make the agent redo them by hand every time; doing it by hand a hundred times yields a hundred different results. Do not do what does not pay off: do not establish checks with too many false positives or that are heavier than the rule; do not write an action as a script when one line of shell can finish it and it runs only a few times a year
Simplify the execution path: when designing a workflow, count how many tool calls the agent needs to follow it and how many files it reads; what can be done in one call should not be split into multiple steps, what can be read in one pass should not be read twice, and what can be launched in parallel should not be serialized
Text first, then scripts: needs in structure and expression should first be solved with textual means such as prose, templates, and subsections; only when textual means are truly insufficient should scripts and checkers be used
Black-box scripts: the agent calls scripts without reading the source code; the external contract is fully written in --help (parameters, input shape, exit codes)
Create directories on demand: ref/ = execution details exceed one screen, or several places need to read it; tools/ = there are checks or repetitive actions worth writing as scripts (smoke tests go in tools/tests/); assets/ = there are templates or static resources that can be copied; eval/ = qualitative tests need to be run. These directories hold only content read on demand; content that must be read on every activation stays in the main text
Dependencies do not form cycles: dependencies between skills are one-way; if A depends on B, B must not depend on A (going around through a third skill also counts). Criterion: apart from the other party, can this skill's work still be completed? If it can be completed, it is only a passing mention of the name and does not count as a dependency. This is judged semantically, with no automated check
Do not design on the user's behalf: do not fill in defaults on your own for details not covered by the material (conversations / old directories / raw run records) and the user's confirmation; list decision points that the material does not answer as open questions for the user to decide. Every rule written into the main text must be able to answer where it came from: which conversation, which raw run record, which exact words; if it cannot answer, do not write it

Writing Principles

Line-deletion test: description is injected at every session, and the body is loaded in full every time it is activated, so text efficiency requirements are high. For each line ask: if it is deleted, would a competent agent do the wrong thing? If not, delete it. The "why" of a rule stays in the body only when it changes boundary behavior; the rest goes into the commit. All gates green only proves formal compliance
Do not write evolution history: evolution history such as modification dates, reasons for changes, and old-vs-new comparisons goes into the commit; the body only states the currently effective rules and facts
State directly: write in declarative sentences directly; do not coin nicknames or invent headline-style new terms; name something only when it needs to be referred to by name elsewhere
Keep punctuation minimal: do not add a period at the end of an item sentence; full-width punctuation is used as usual, but full-width symbols are not used (graphic / decorative symbols such as ★, ▶, →); write relations such as contrast and continuation in words; use punctuation within a sentence only when it helps delimit structure; quotations, code, and template slots are left untouched
Layout is not rendered: the reader is an agent, which reads the raw text rather than the rendered result; do not write layout syntax such as tables, mermaid, or ASCII diagrams
Section content boundaries: each section writes only the content indicated by its section name:输入与输出 write only the prerequisites and deliverables that cannot be inferred from the description (if there are none, close it off in one line);执行原则 write only judgment rules common across entry points; once there are many items, split further into design / writing subsections; 工作流 write only operational steps; branch-selection criteria for multiple entry points go at the start of the workflow section. Trigger timing is written only in the description
References do not use numbers: cross-references use names or links, not numbers or line numbers. For cross-section references write [章节](#节名); bold items have no anchor, so to reference one write its name. When mentioning another skill, write only that skill's name, not the names / paths of sections inside it. One concept keeps one name throughout
How to write the description: serves only trigger determination; for the three-line pattern see the template slots. Each keyword corresponds to a class of requests users really make, not whole-sentence quoted example sentences; each negative example corresponds to a class of requests that are really easy to trigger by mistake; add proactive declarations where the cost of a missed trigger is high; do not write step-by-step narration
Agent-neutral: the body and description refer to the execution environment generically by default; when naming a specific agent or its unique mechanism, explain on the spot why

Workflow

To make a new skill, go through creation, steps see ref/create.md; to rewrite the body of an existing skill as a whole (rework), go through creation, and the rework-scenario clauses of each step apply; to change an existing skill (including this skill's templates and design principles / writing principles), go through improvement; to check whether a skill conforms to the standard, go through audit. The last step of both creation and improvement isclosing：check all green; if the target repository has lint / format gates, run those too; if there is a tools/, run its smoke tests; hand it to the user for review

Improvement

Read through the target skill, locate the sections involved in the change, and place the new content according to "Section content boundaries"; the change surface is the entire skill directory (frontmatter / body / ref / tools / eval in coordination)
When changing the description, recheck the correspondence between keywords and real requests according to "How to write the description"; when a sentence is questioned, first try the "delete-line test" to see whether it can be deleted outright, and rewrite only if it cannot be deleted; do not respond to the question by adding explanatory words
Effectiveness verification (for behavioral changes; ask the user before starting, subagents have a cost): rerun with the failure scenario that triggered this change, and it must no longer fail that way; if there is eval/evals.json also run the regression together, and append the reproduction cases into it; for changes to the description, run both positive and negative cases, for the method see ref/qualitative-loop.md. Single-point edits are exempt
When the change targets this skill's templates or design principles / writing principles: first get user confirmation, and finish changing the templates and the main text in the same batch; after the change, run check across the whole repository; if it fails, list the old skills that fail as a checklist and hand it to the user to decide how to handle them
When a batch of changes touches multiple sections / multiple files, before delivery propose a full audit of the target skill (execute only after the user agrees); single-point edits are exempt

Audit

Run python3 yzr-skill-management/tools/skeleton.py check <skill-dir>; if the target skill has tools/, also run the smoke test and include any failures in the report
Read all files in the skill directory closely and compare structure items againstsections, and compare text items againstsectionsand give a conclusion for each item, attaching the file and the original quote as evidence for each
Every item in the report has a disposition and a destination; do not finish while any item is undisposed: for violations attach a suggested fix, and after the user agrees to the fix, proceed via improvement; items that fail the "line-deletion test" are listed as deletion candidates; pure text-quality issues go to yzr-writing-review, tools/ code and scripts go to yzr-coding-review