From 2540e50fcc03bf1b92e5473e92ec5db360723dce Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Sun, 16 Aug 2026 16:40:19 +0000 Subject: [PATCH] feat(kyberforge): give skill-author a procedure for the #99 retrofit MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ADR-0020 shipped its gates hot with no baseline file, so 26 of 39 descriptions and 9 of 39 bodies are over their FAIL tier and editing any of them for any reason requires bringing the skill into contract first. `references/improve.md` said exactly that and stopped there — it mandated a retrofit and supplied no procedure for one. Four dry-run retrofits confirmed what that costs. Asked the same questions — what to cut first, when a body is two flows rather than one, what else has to change alongside — they invented six to ten different answers, so the same skill retrofitted twice produced two different skills and neither run could be reviewed against anything. `references/retrofit.md` fixes the answers: an ordered cut list ranked by tokens removed against behaviour lost (inverting that order is how a retrofit deletes the instruction the skill existed to carry), the test for whether a body holds two mutually exclusive flows, the reference-file conventions, the collateral checklist for `README.md` and `references/sources.md`, and a worked description retrofit. It also states the trap the dry runs kept hitting: retrofit the skill in place, inside its package. The boundary-target universe is built by walking up from the file being checked, so a scratch copy has no authoring root above it, the check prints `INFO ... DID NOT RUN`, and the run still exits 0 — a line that reads as a pass and is not one. A retrofit signed off on a copy carries an unverified boundary target into the corpus. Loaded from the improve flow only when a budget is actually exceeded, so a routine improvement pays nothing for it. Refs: ADR-0020, #99 --- .../.apm/skills/skill-author/README.md | 1 + .../skills/skill-author/references/improve.md | 6 + .../skill-author/references/retrofit.md | 152 ++++++++++++++++++ .../skills/skill-author/references/sources.md | 4 +- .../kyberforge/skills/skill-author/README.md | 1 + .../skills/skill-author/references/improve.md | 6 + .../skill-author/references/retrofit.md | 152 ++++++++++++++++++ .../skills/skill-author/references/sources.md | 4 +- 8 files changed, 322 insertions(+), 4 deletions(-) create mode 100644 plugins/kyberforge/.apm/skills/skill-author/references/retrofit.md create mode 100644 plugins/kyberforge/skills/skill-author/references/retrofit.md diff --git a/plugins/kyberforge/.apm/skills/skill-author/README.md b/plugins/kyberforge/.apm/skills/skill-author/README.md index 26a24de..f169f44 100644 --- a/plugins/kyberforge/.apm/skills/skill-author/README.md +++ b/plugins/kyberforge/.apm/skills/skill-author/README.md @@ -47,6 +47,7 @@ If the destination resolves inside an APM package, read `references/deployment-m | `references/create.md` | The create flow end to end — prerequisites, package-intent gate, scaffold, frontmatter, scripts, references, sources (loaded on demand) | | `references/improve.md` | The improve flow end to end — signal verification, root-cause grouping, announcement, edits (loaded on demand) | | `references/contract.md` | The ADR-0020 description and body contract, the Gotchas constraint, the two size gates, body patterns, and org-policy embedding (loaded on demand) | +| `references/retrofit.md` | Bringing a pre-ADR-0020 skill into contract — ordered cut procedure, the mutually-exclusive-flows test, reference-file conventions, the collateral checklist, and a worked description retrofit (loaded from the improve flow when a budget is exceeded) | | `references/deployment-modes.md` | APM package vs standalone differences and self-containment/cache-isolation rules (loaded on demand) | | `references/scripts.md` | Package runners, inline dependency patterns, and full script contract (loaded on demand) | | `references/sources.md` | Upstream research sources and which skill files each contributed to | diff --git a/plugins/kyberforge/.apm/skills/skill-author/references/improve.md b/plugins/kyberforge/.apm/skills/skill-author/references/improve.md index 5d4004e..ad4cb5e 100644 --- a/plugins/kyberforge/.apm/skills/skill-author/references/improve.md +++ b/plugins/kyberforge/.apm/skills/skill-author/references/improve.md @@ -76,6 +76,12 @@ contract first — the gates are hot and carry no baseline file, so a one-line f non-compliant skill cannot be committed until the description and body meet `references/contract.md`. Treat that retrofit as part of the same change, not a follow-up. +If the skill's description exceeds 250 characters, or its body-only word count exceeds 600, read +`references/retrofit.md` before editing. It carries the ordered cut procedure, the +mutually-exclusive-flows test, the reference-file conventions this flow needs, the collateral +checklist for `README.md` and `references/sources.md`, and a worked description retrofit. Do not +improvise the cuts — four dry runs invented six to ten different answers to the same questions. + If a signal points to a script or reference file, edit that file directly rather than adding a workaround in SKILL.md. diff --git a/plugins/kyberforge/.apm/skills/skill-author/references/retrofit.md b/plugins/kyberforge/.apm/skills/skill-author/references/retrofit.md new file mode 100644 index 0000000..7eeae03 --- /dev/null +++ b/plugins/kyberforge/.apm/skills/skill-author/references/retrofit.md @@ -0,0 +1,152 @@ +--- +source_keys: + - agentskills-best-practices + - agentskills-optimizing-descriptions +--- + +# Retrofitting a skill to the ADR-0020 contract + +Read this when `references/improve.md` Step 4 sends you here: the skill you are editing is over +the description or body budget and has to come into contract before any other change can be +committed. The gates are hot and carry no baseline file, so a one-line fix to a non-compliant +skill is blocked until this is done. + +Measure first. Do not guess which gate fired: run `/skill-audit` on the directory and read its +`### Structure` dimension, which reports the description characters and the **body-only** word +count separately from the whole-file spec backstop. Retrofit against the number that actually +fired — a skill can sit a thousand words inside the whole-file backstop while failing the body +budget. + +**Validate in place.** Audit the skill's real directory inside its package. Never audit a copy in a +scratch directory, and never move a skill out to work on it: the boundary-target universe is built +by walking up *from the file being checked*, so a copy with no authoring root above it resolves +against nothing and the check declines rather than running — + +```text +INFO boundary-target resolution DID NOT RUN — no skill universe could be determined for +this path ... Unchecked target(s): totally-fake-target +``` + +The run still exits 0, so that line reads as a pass and is not one. Treat `DID NOT RUN` as **not +checked**, always. A retrofit signed off on a scratch copy carries an unverified boundary target +into the corpus, which is precisely the failure this gate exists to catch. + +## Cut in this order + +Work the list top down and stop as soon as the gate clears. The order is by ratio of tokens +removed to behaviour lost — inverting it is how a retrofit ends up deleting the one instruction +the skill existed to carry. + +1. **Gotchas that paraphrase a step in the body below.** Zero information, and already a FAIL on + its own. Delete the Gotcha, keep the step. +2. **Spec restatements** — text that repeats a published specification, a tool's `--help`, or a + ceiling the validator already enforces. The agent gets this right without it. Delete, or move + the table to `references/` if a flow genuinely needs to look it up. +3. **Capability enumeration** — in a description, the feature list after the trigger clause; in a + body, the paragraph that recites what the skill can do. One capability clause survives in the + description; the rest belongs in `README.md`. +4. **Per-flow prose** — anything only one branch of the procedure ever reaches. This is the + largest single win in most bodies, and it is a *move*, not a delete: each flow gets its own + self-contained `references/` file, wired from a dispatch table. + +If the body is still over after all four, the skill is doing two jobs. Split it, and say so +rather than compressing prose until it stops being readable. + +## What "mutually exclusive flows" means + +Two or more flows that a single invocation cannot both take. The three-way test, copied verbatim +from the body-discipline rubric `/skill-audit` judges against — nothing to load, it is quoted in +full here: + +> separate subcommands, separate input types, separate lifecycle stages + +Any one of the three is enough. Two flows that differ only in a parameter value are one flow. +At two or more mutually exclusive flows a dispatch table is **mandatory** regardless of word +count, because every invocation otherwise pays for every branch it did not take. + +## Reference-file conventions + +The create flow owns these rules, and this flow is forbidden from reading `references/create.md`, +so what a retrofit needs is restated here: + +- **One topic per file.** A file mixing two concerns gets loaded for one of them and spends the + caller's context on the other. +- **Kebab-case filenames**, named after the topic rather than the flow that reads it — + `body-discipline.md`, not `step-3.md`. +- **Wire every file with the literal conditional form** ``If , read + `references/.md` ``. A generic pointer ("see `references/` for details") is a Vale error. +- **Two hops from `SKILL.md`, never three.** A flow file may route on to a shared contract file; + a file reachable only through two intermediates is rarely loaded when it is needed. +- **`source_keys` frontmatter.** If the content you are moving drew on a research source, the new + file needs top-level `source_keys:` frontmatter listing those slugs, and every slug must already + exist as an `## ` heading in `references/sources.md`. Moving sourced content out of + `SKILL.md` without carrying its slugs across breaks the provenance chain, and `/skill-audit` + reports the new file as an INFO with no `source_keys`. + +## Collateral is mandatory, not optional + +Moving content out of a `SKILL.md` leaves three files describing a structure that no longer +exists. `/skill-audit`'s provenance check exits clean on all three of these, so nothing catches +them for you. After every retrofit that adds, removes or renames a file: + +- [ ] **`README.md` file table** — a row for every new `references/` file, and no row left for a + file that is gone. Say what triggers the load, not just what the file contains. +- [ ] **`references/README.md`**, where the skill has one — same update, same reason. +- [ ] **`references/sources.md` → `Contributing files`** — add the new file to every slug whose + content moved into it, and remove any file the retrofit deleted. This is the one that gets + missed: `sources.md` keeps citing sections of `SKILL.md` that no longer exist, the + provenance check still exits 0, and the stale claim survives review. +- [ ] Re-run `/skill-audit` and confirm its `### Provenance` dimension does not report the new + file as missing `source_keys`. + +## Worked example — a description retrofit + +`gitea-issues` before, 827 characters, the single most common shape in the corpus: + +```text +Use when reading or writing Gitea issues: listing repo issues, getting a single issue's details/ +comments/labels, creating an issue, updating its state, adding or editing comments, applying +labels via issue_write, or searching issues/PRs across repositories. Triggers on "create an +issue", "what issues are open", "get issue #N", "close issue #N", "comment on issue #N", "search +issues for X" — even when the user doesn't say "Gitea" explicitly. Composes gitea-labels- +milestones for all label inference/resolution and milestone lookup — do not use this skill to +manage label or milestone definitions themselves (create/edit/delete a label, create/close a +milestone), that's gitea-labels-milestones directly. Do not use for pull requests (use gitea-prs) +or for local git branch/commit work (use gitea-branches or git-branches). +``` + +After, 240 characters: + +```text +Use when reading or writing Gitea issues — list, read, create, comment on, label, close, or +search — even when the user does not say "Gitea". Not pull requests -> `gitea-prs`. Not label or +milestone definitions -> `gitea-labels-milestones`. +``` + +What came out, and why: + +| Removed | Why | +|---|---| +| The second trigger register — `Triggers on "create an issue", "what issues are open", …` | The same triggers restated as quoted user phrasings. Two registers of one trigger list is a FAIL, not a suggestion. | +| `applying labels via issue_write` | Implementation detail. The router does not choose a skill by which MCP call it makes. | +| `Composes gitea-labels-milestones for all label inference/resolution and milestone lookup` | A composition note. It changes no routing decision and belongs in `README.md`. | +| The parenthetical `(create/edit/delete a label, create/close a milestone)` | Capability enumeration inside a boundary clause. The boundary needs the target, not its feature list. | +| The `gitea-branches` / `git-branches` boundary | Dropped entirely. Neither was ever going to win an issue request, so the clause defended against nothing — an invented boundary costs characters and buys no routing accuracy. | +| `Do not use for pull requests (use gitea-prs)` prose form | Kept, but rewritten as `Not pull requests -> \`gitea-prs\`.` The rewrite buys characters and one uniform shape for the router — not safety. Both forms are parsed **and** target-checked, so a typo in the prose form dangles exactly as an arrow typo does. | + +What stayed: one trigger clause, one capability clause, the indirect trigger (genuinely warranted +here — people say "create an issue", not "create a Gitea issue"), and the boundary clauses. + +## Two rules the gates enforce but the prose does not spell out + +**Boundary clauses may be plural.** Write one per genuine near-miss — the example above carries +two, because two different skills could each steal activations. "A boundary clause" in the +contract means *at least one*, not *exactly one*. What is banned is a boundary clause invented for +a skill that was never going to compete, not a second real one. + +**Never let a hyphenated routing target wrap across lines in a folded `>` scalar.** YAML folding +replaces the newline with a space, so `gitea-labels-` at the end of one line and `milestones` at +the start of the next fold into `gitea-labels- milestones`. `validate.sh` then reads the target as +`gitea-labels`, finds no such skill, and reports a dangling boundary target — the live finding on +`gitea-issues` today. Reflow the line so the whole name sits on one of them. The same applies to +any backticked skill or agent name in a description. diff --git a/plugins/kyberforge/.apm/skills/skill-author/references/sources.md b/plugins/kyberforge/.apm/skills/skill-author/references/sources.md index 2d169d7..54b9f6d 100644 --- a/plugins/kyberforge/.apm/skills/skill-author/references/sources.md +++ b/plugins/kyberforge/.apm/skills/skill-author/references/sources.md @@ -34,7 +34,7 @@ source_keys: - **URL:** https://agentskills.io/skill-creation/best-practices.md - **Research doc:** plugins/kyberforge/docs/research/docs/agentskillsio/sources.md - **Description:** Best practices for skill creators — starting from real expertise, spending context wisely, calibrating control, instruction patterns (gotchas, templates, checklists, validation loops) -- **Contributing files:** SKILL.md, references/create.md, references/improve.md, references/contract.md +- **Contributing files:** SKILL.md, references/create.md, references/improve.md, references/contract.md, references/retrofit.md - **Status:** `extracted` ## agentskills-optimizing-descriptions @@ -42,7 +42,7 @@ source_keys: - **URL:** https://agentskills.io/skill-creation/optimizing-descriptions.md - **Research doc:** plugins/kyberforge/docs/research/docs/agentskillsio/sources.md - **Description:** How to systematically test and improve skill descriptions for triggering accuracy — eval queries, trigger rate testing, train/validation splits, optimization loop -- **Contributing files:** SKILL.md, references/improve.md, references/contract.md +- **Contributing files:** SKILL.md, references/improve.md, references/contract.md, references/retrofit.md - **Status:** `extracted` ## agentskills-evaluating-skills diff --git a/plugins/kyberforge/skills/skill-author/README.md b/plugins/kyberforge/skills/skill-author/README.md index 26a24de..f169f44 100644 --- a/plugins/kyberforge/skills/skill-author/README.md +++ b/plugins/kyberforge/skills/skill-author/README.md @@ -47,6 +47,7 @@ If the destination resolves inside an APM package, read `references/deployment-m | `references/create.md` | The create flow end to end — prerequisites, package-intent gate, scaffold, frontmatter, scripts, references, sources (loaded on demand) | | `references/improve.md` | The improve flow end to end — signal verification, root-cause grouping, announcement, edits (loaded on demand) | | `references/contract.md` | The ADR-0020 description and body contract, the Gotchas constraint, the two size gates, body patterns, and org-policy embedding (loaded on demand) | +| `references/retrofit.md` | Bringing a pre-ADR-0020 skill into contract — ordered cut procedure, the mutually-exclusive-flows test, reference-file conventions, the collateral checklist, and a worked description retrofit (loaded from the improve flow when a budget is exceeded) | | `references/deployment-modes.md` | APM package vs standalone differences and self-containment/cache-isolation rules (loaded on demand) | | `references/scripts.md` | Package runners, inline dependency patterns, and full script contract (loaded on demand) | | `references/sources.md` | Upstream research sources and which skill files each contributed to | diff --git a/plugins/kyberforge/skills/skill-author/references/improve.md b/plugins/kyberforge/skills/skill-author/references/improve.md index 5d4004e..ad4cb5e 100644 --- a/plugins/kyberforge/skills/skill-author/references/improve.md +++ b/plugins/kyberforge/skills/skill-author/references/improve.md @@ -76,6 +76,12 @@ contract first — the gates are hot and carry no baseline file, so a one-line f non-compliant skill cannot be committed until the description and body meet `references/contract.md`. Treat that retrofit as part of the same change, not a follow-up. +If the skill's description exceeds 250 characters, or its body-only word count exceeds 600, read +`references/retrofit.md` before editing. It carries the ordered cut procedure, the +mutually-exclusive-flows test, the reference-file conventions this flow needs, the collateral +checklist for `README.md` and `references/sources.md`, and a worked description retrofit. Do not +improvise the cuts — four dry runs invented six to ten different answers to the same questions. + If a signal points to a script or reference file, edit that file directly rather than adding a workaround in SKILL.md. diff --git a/plugins/kyberforge/skills/skill-author/references/retrofit.md b/plugins/kyberforge/skills/skill-author/references/retrofit.md new file mode 100644 index 0000000..7eeae03 --- /dev/null +++ b/plugins/kyberforge/skills/skill-author/references/retrofit.md @@ -0,0 +1,152 @@ +--- +source_keys: + - agentskills-best-practices + - agentskills-optimizing-descriptions +--- + +# Retrofitting a skill to the ADR-0020 contract + +Read this when `references/improve.md` Step 4 sends you here: the skill you are editing is over +the description or body budget and has to come into contract before any other change can be +committed. The gates are hot and carry no baseline file, so a one-line fix to a non-compliant +skill is blocked until this is done. + +Measure first. Do not guess which gate fired: run `/skill-audit` on the directory and read its +`### Structure` dimension, which reports the description characters and the **body-only** word +count separately from the whole-file spec backstop. Retrofit against the number that actually +fired — a skill can sit a thousand words inside the whole-file backstop while failing the body +budget. + +**Validate in place.** Audit the skill's real directory inside its package. Never audit a copy in a +scratch directory, and never move a skill out to work on it: the boundary-target universe is built +by walking up *from the file being checked*, so a copy with no authoring root above it resolves +against nothing and the check declines rather than running — + +```text +INFO boundary-target resolution DID NOT RUN — no skill universe could be determined for +this path ... Unchecked target(s): totally-fake-target +``` + +The run still exits 0, so that line reads as a pass and is not one. Treat `DID NOT RUN` as **not +checked**, always. A retrofit signed off on a scratch copy carries an unverified boundary target +into the corpus, which is precisely the failure this gate exists to catch. + +## Cut in this order + +Work the list top down and stop as soon as the gate clears. The order is by ratio of tokens +removed to behaviour lost — inverting it is how a retrofit ends up deleting the one instruction +the skill existed to carry. + +1. **Gotchas that paraphrase a step in the body below.** Zero information, and already a FAIL on + its own. Delete the Gotcha, keep the step. +2. **Spec restatements** — text that repeats a published specification, a tool's `--help`, or a + ceiling the validator already enforces. The agent gets this right without it. Delete, or move + the table to `references/` if a flow genuinely needs to look it up. +3. **Capability enumeration** — in a description, the feature list after the trigger clause; in a + body, the paragraph that recites what the skill can do. One capability clause survives in the + description; the rest belongs in `README.md`. +4. **Per-flow prose** — anything only one branch of the procedure ever reaches. This is the + largest single win in most bodies, and it is a *move*, not a delete: each flow gets its own + self-contained `references/` file, wired from a dispatch table. + +If the body is still over after all four, the skill is doing two jobs. Split it, and say so +rather than compressing prose until it stops being readable. + +## What "mutually exclusive flows" means + +Two or more flows that a single invocation cannot both take. The three-way test, copied verbatim +from the body-discipline rubric `/skill-audit` judges against — nothing to load, it is quoted in +full here: + +> separate subcommands, separate input types, separate lifecycle stages + +Any one of the three is enough. Two flows that differ only in a parameter value are one flow. +At two or more mutually exclusive flows a dispatch table is **mandatory** regardless of word +count, because every invocation otherwise pays for every branch it did not take. + +## Reference-file conventions + +The create flow owns these rules, and this flow is forbidden from reading `references/create.md`, +so what a retrofit needs is restated here: + +- **One topic per file.** A file mixing two concerns gets loaded for one of them and spends the + caller's context on the other. +- **Kebab-case filenames**, named after the topic rather than the flow that reads it — + `body-discipline.md`, not `step-3.md`. +- **Wire every file with the literal conditional form** ``If , read + `references/.md` ``. A generic pointer ("see `references/` for details") is a Vale error. +- **Two hops from `SKILL.md`, never three.** A flow file may route on to a shared contract file; + a file reachable only through two intermediates is rarely loaded when it is needed. +- **`source_keys` frontmatter.** If the content you are moving drew on a research source, the new + file needs top-level `source_keys:` frontmatter listing those slugs, and every slug must already + exist as an `## ` heading in `references/sources.md`. Moving sourced content out of + `SKILL.md` without carrying its slugs across breaks the provenance chain, and `/skill-audit` + reports the new file as an INFO with no `source_keys`. + +## Collateral is mandatory, not optional + +Moving content out of a `SKILL.md` leaves three files describing a structure that no longer +exists. `/skill-audit`'s provenance check exits clean on all three of these, so nothing catches +them for you. After every retrofit that adds, removes or renames a file: + +- [ ] **`README.md` file table** — a row for every new `references/` file, and no row left for a + file that is gone. Say what triggers the load, not just what the file contains. +- [ ] **`references/README.md`**, where the skill has one — same update, same reason. +- [ ] **`references/sources.md` → `Contributing files`** — add the new file to every slug whose + content moved into it, and remove any file the retrofit deleted. This is the one that gets + missed: `sources.md` keeps citing sections of `SKILL.md` that no longer exist, the + provenance check still exits 0, and the stale claim survives review. +- [ ] Re-run `/skill-audit` and confirm its `### Provenance` dimension does not report the new + file as missing `source_keys`. + +## Worked example — a description retrofit + +`gitea-issues` before, 827 characters, the single most common shape in the corpus: + +```text +Use when reading or writing Gitea issues: listing repo issues, getting a single issue's details/ +comments/labels, creating an issue, updating its state, adding or editing comments, applying +labels via issue_write, or searching issues/PRs across repositories. Triggers on "create an +issue", "what issues are open", "get issue #N", "close issue #N", "comment on issue #N", "search +issues for X" — even when the user doesn't say "Gitea" explicitly. Composes gitea-labels- +milestones for all label inference/resolution and milestone lookup — do not use this skill to +manage label or milestone definitions themselves (create/edit/delete a label, create/close a +milestone), that's gitea-labels-milestones directly. Do not use for pull requests (use gitea-prs) +or for local git branch/commit work (use gitea-branches or git-branches). +``` + +After, 240 characters: + +```text +Use when reading or writing Gitea issues — list, read, create, comment on, label, close, or +search — even when the user does not say "Gitea". Not pull requests -> `gitea-prs`. Not label or +milestone definitions -> `gitea-labels-milestones`. +``` + +What came out, and why: + +| Removed | Why | +|---|---| +| The second trigger register — `Triggers on "create an issue", "what issues are open", …` | The same triggers restated as quoted user phrasings. Two registers of one trigger list is a FAIL, not a suggestion. | +| `applying labels via issue_write` | Implementation detail. The router does not choose a skill by which MCP call it makes. | +| `Composes gitea-labels-milestones for all label inference/resolution and milestone lookup` | A composition note. It changes no routing decision and belongs in `README.md`. | +| The parenthetical `(create/edit/delete a label, create/close a milestone)` | Capability enumeration inside a boundary clause. The boundary needs the target, not its feature list. | +| The `gitea-branches` / `git-branches` boundary | Dropped entirely. Neither was ever going to win an issue request, so the clause defended against nothing — an invented boundary costs characters and buys no routing accuracy. | +| `Do not use for pull requests (use gitea-prs)` prose form | Kept, but rewritten as `Not pull requests -> \`gitea-prs\`.` The rewrite buys characters and one uniform shape for the router — not safety. Both forms are parsed **and** target-checked, so a typo in the prose form dangles exactly as an arrow typo does. | + +What stayed: one trigger clause, one capability clause, the indirect trigger (genuinely warranted +here — people say "create an issue", not "create a Gitea issue"), and the boundary clauses. + +## Two rules the gates enforce but the prose does not spell out + +**Boundary clauses may be plural.** Write one per genuine near-miss — the example above carries +two, because two different skills could each steal activations. "A boundary clause" in the +contract means *at least one*, not *exactly one*. What is banned is a boundary clause invented for +a skill that was never going to compete, not a second real one. + +**Never let a hyphenated routing target wrap across lines in a folded `>` scalar.** YAML folding +replaces the newline with a space, so `gitea-labels-` at the end of one line and `milestones` at +the start of the next fold into `gitea-labels- milestones`. `validate.sh` then reads the target as +`gitea-labels`, finds no such skill, and reports a dangling boundary target — the live finding on +`gitea-issues` today. Reflow the line so the whole name sits on one of them. The same applies to +any backticked skill or agent name in a description. diff --git a/plugins/kyberforge/skills/skill-author/references/sources.md b/plugins/kyberforge/skills/skill-author/references/sources.md index 2d169d7..54b9f6d 100644 --- a/plugins/kyberforge/skills/skill-author/references/sources.md +++ b/plugins/kyberforge/skills/skill-author/references/sources.md @@ -34,7 +34,7 @@ source_keys: - **URL:** https://agentskills.io/skill-creation/best-practices.md - **Research doc:** plugins/kyberforge/docs/research/docs/agentskillsio/sources.md - **Description:** Best practices for skill creators — starting from real expertise, spending context wisely, calibrating control, instruction patterns (gotchas, templates, checklists, validation loops) -- **Contributing files:** SKILL.md, references/create.md, references/improve.md, references/contract.md +- **Contributing files:** SKILL.md, references/create.md, references/improve.md, references/contract.md, references/retrofit.md - **Status:** `extracted` ## agentskills-optimizing-descriptions @@ -42,7 +42,7 @@ source_keys: - **URL:** https://agentskills.io/skill-creation/optimizing-descriptions.md - **Research doc:** plugins/kyberforge/docs/research/docs/agentskillsio/sources.md - **Description:** How to systematically test and improve skill descriptions for triggering accuracy — eval queries, trigger rate testing, train/validation splits, optimization loop -- **Contributing files:** SKILL.md, references/improve.md, references/contract.md +- **Contributing files:** SKILL.md, references/improve.md, references/contract.md, references/retrofit.md - **Status:** `extracted` ## agentskills-evaluating-skills