From 6317b5c844d00a0c7fb9d818766c47ab863e4540 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Mon, 22 Jun 2026 18:51:09 +0000 Subject: [PATCH] docs(kyberforge): preserve old write-skill as reference example Moves the previous write-skill implementation to docs/examples/skill-write/write-skill/ for reference. The skill has been superseded by the spec-compliant skill-write rewrite. Co-Authored-By: Claude Sonnet 4.6 --- .../skill-write/write-skill/CATEGORIES.md | 16 +++ .../skill-write/write-skill/META-TEMPLATE.md | 27 +++++ .../examples/skill-write/write-skill/META.md | 16 +++ .../skill-write/write-skill/SKILL-TEMPLATE.md | 93 ++++++++++++++++++ .../examples/skill-write/write-skill/SKILL.md | 98 +++++++++++++++++++ .../skill-write/write-skill/evals/eval.yaml | 69 +++++++++++++ .../skill-write/write-skill/sources.md | 1 + 7 files changed, 320 insertions(+) create mode 100644 plugins/kyberforge/docs/examples/skill-write/write-skill/CATEGORIES.md create mode 100644 plugins/kyberforge/docs/examples/skill-write/write-skill/META-TEMPLATE.md create mode 100644 plugins/kyberforge/docs/examples/skill-write/write-skill/META.md create mode 100644 plugins/kyberforge/docs/examples/skill-write/write-skill/SKILL-TEMPLATE.md create mode 100644 plugins/kyberforge/docs/examples/skill-write/write-skill/SKILL.md create mode 100644 plugins/kyberforge/docs/examples/skill-write/write-skill/evals/eval.yaml create mode 100644 plugins/kyberforge/docs/examples/skill-write/write-skill/sources.md diff --git a/plugins/kyberforge/docs/examples/skill-write/write-skill/CATEGORIES.md b/plugins/kyberforge/docs/examples/skill-write/write-skill/CATEGORIES.md new file mode 100644 index 0000000..5aaf491 --- /dev/null +++ b/plugins/kyberforge/docs/examples/skill-write/write-skill/CATEGORIES.md @@ -0,0 +1,16 @@ +# Skill Categories + +| Category | Scope | +|---|---| +| `design` | grill-me, grill-with-docs, to-prd, prototype, architecture-review | +| `plan` | to-issues, triage | +| `implement` | tdd, diagnose, implement-feature, refactor, write-docs | +| `test` | write-tests, generate-test-data, review-test-coverage | +| `review` | improve-codebase-architecture, code-review, security-review, pr-description, changelog-entry | +| `deploy` | write-ci-pipeline, write-deployment-config, write-ai-review-workflow, deployment-checklist | +| `operate` | write-runbook, incident-diagnosis, post-mortem, inspect-deployment | +| `iac` | write-ansible-role, write-terraform-module, write-k8s-manifest, write-docker-compose, proxmox-vm-spec, iac-security-review, write-molecule-test | +| `cross-cutting` | zoom-out, caveman, session-handoff, governance-check, git-guardrails, git-commit-message | +| `factory` | write-skill, write-agent, write-adr, write-workflow, write-eval, validate-skill, upgrade-skill, write-issue-spec | +| `marketplace` | marketplace-architect — plugin and skill distribution tooling for Claude Code / GitHub Copilot CLI | +| `roles` | architect, developer, reviewer, security, qa, ops — Chunk 5 | diff --git a/plugins/kyberforge/docs/examples/skill-write/write-skill/META-TEMPLATE.md b/plugins/kyberforge/docs/examples/skill-write/write-skill/META-TEMPLATE.md new file mode 100644 index 0000000..ebfdbd6 --- /dev/null +++ b/plugins/kyberforge/docs/examples/skill-write/write-skill/META-TEMPLATE.md @@ -0,0 +1,27 @@ +```yaml +version: "1.0" # increment on meaningful changes to the skill +updated: YYYY-MM-DD # ISO date of last update + +# when: describes when this skill is loaded — the full trigger context. +# More detail than the description field; not used for routing. +when: + +# source: tracks content you ADOPTED from an upstream repo. +# Adopt = you read someone else's code or docs and incorporated text or logic directly. +# Omit this field entirely if the skill is self-authored — absence means original work. +# Present only when content was actually taken, tracked at commit-level for upgrade reviews. +source: + - repo: org/repo-name # GitHub slug — no URL, slug is stable and searchable + commit: # exact commit reviewed at time of adoption + files: + - path/to/file.md # inline comment: what was taken from this file + - path/to/other.md # inline comment: what was taken from this file + updated: YYYY-MM-DD # date this source entry was last reviewed + +# references: tracks content you CITED but did not adopt verbatim. +# Cite = you read it and it informed the skill, but nothing was copied or adapted. +# Examples: a spec you followed, a paper that shaped the approach, external documentation. +# Distinct from source: source = took content; references = informed by content. +references: + - https://example.com/relevant-doc +``` diff --git a/plugins/kyberforge/docs/examples/skill-write/write-skill/META.md b/plugins/kyberforge/docs/examples/skill-write/write-skill/META.md new file mode 100644 index 0000000..ffd2f54 --- /dev/null +++ b/plugins/kyberforge/docs/examples/skill-write/write-skill/META.md @@ -0,0 +1,16 @@ +```yaml +version: "1.5" +updated: 2026-05-26 + +# when: describes when this skill is loaded — the full trigger context. +# More detail than the description field; not used for routing. +when: invoked by explicit trigger ("write a new skill for X", "create a SKILL.md that does Y") or implicit request to author a skill file or convert an existing placeholder to the canonical authoring standard + +# source: omitted — self-authored original; no upstream content adopted +# Absence of source means self-authored. If content is adopted from upstream, +# add a source entry per the META-TEMPLATE.md schema. + +references: + - https://agentskills.io/specification.md + - https://agentskills.io/skill-creation/optimizing-descriptions +``` diff --git a/plugins/kyberforge/docs/examples/skill-write/write-skill/SKILL-TEMPLATE.md b/plugins/kyberforge/docs/examples/skill-write/write-skill/SKILL-TEMPLATE.md new file mode 100644 index 0000000..853412a --- /dev/null +++ b/plugins/kyberforge/docs/examples/skill-write/write-skill/SKILL-TEMPLATE.md @@ -0,0 +1,93 @@ +--- +name: +# description: routing-only field — loaded at startup for every skill scan to decide whether +# to activate this skill. Write in imperative phrasing ("Use when X", not "This skill does X"). +# Must cover: (1) what the skill does, (2) when to invoke it, (3) negative triggers — what +# adjacent tasks must NOT activate it. No behavioral or role framing; that belongs in the body. +# Max 1024 characters. The `when:` detail that lived here previously now lives in META.md. +# Example: "Use when the user wants to create a new SKILL.md file or convert a placeholder to +# canonical format. Do NOT use when updating an existing well-formed skill — use upgrade-skill." +description: +metadata: + category: +# allowed-tools: +# model: sonnet | opus | haiku — Claude Code extension; overrides session model for this skill's turn. +# Omit to inherit the active session model. Factory §9 routing: haiku=formatting/classification, +# sonnet=most coding/review, opus=adversarial/complex reasoning. +--- + + + +## Required inputs + + + +- **** — + +## Constraints + + + +- + + + + + +## Process + + + +1. **.** + +## Output format + + + + + + + + + +## Failure handling + + + +- — + +## Self-check + + + +- [ ] + + diff --git a/plugins/kyberforge/docs/examples/skill-write/write-skill/SKILL.md b/plugins/kyberforge/docs/examples/skill-write/write-skill/SKILL.md new file mode 100644 index 0000000..1f6321e --- /dev/null +++ b/plugins/kyberforge/docs/examples/skill-write/write-skill/SKILL.md @@ -0,0 +1,98 @@ +--- +name: write-skill +description: >- + Use when the user wants to author a new skill file or convert an existing + placeholder to the canonical authoring standard. Triggers: "write a new skill + for X", "create a SKILL.md that does Y", "build a skill to handle Z". Do NOT + use when fixing or updating an existing well-formed skill (use upgrade-skill), + running existing evals (use write-eval), refactoring application code, or + writing documentation for non-skill artifacts. +metadata: + category: factory +model: sonnet +--- + + + +## Required inputs + +- **Skill name** — kebab-case slug; inferred from user description if not stated explicitly, ask if ambiguous +- **Category** — from the category table in `CATEGORIES.md`; ask if unclear +- **Purpose + use cases** — what the skill does and what tasks it handles; source for the trigger description +- **For placeholder conversions:** existing SKILL.md path — read before writing + +Negative trigger cases are NOT a required input. The agent proposes them based on the skill's purpose and adjacent skills found during the overlap scan. The user confirms or refines before trigger testing begins. + +## Constraints + +- Write two files for every skill: `SKILL.md` at `.agents/skills//SKILL.md` and `META.md` alongside it +- Frontmatter required fields: `name`, `description`, `metadata.category` — add `allowed-tools` only when the skill has a narrow, well-defined tool surface; add `model:` only when the skill's task complexity warrants a specific model tier (see SKILL-TEMPLATE.md for routing guidance) +- Keep the body under 500 lines — content that explains rather than directs belongs in sub-files, not the body +- Sub-files use three spec-defined optional directories: `scripts/` (executable code), `references/` (on-demand docs), `assets/` (templates, data files, lookup tables); additional files (e.g. `META.md`) are valid at the skill root. File references must be one level deep — no nested chains. Wire each sub-file with an explicit instruction in the step that needs it (e.g. `"See references/lookup.md for error codes"`) — without a wiring instruction the file is never loaded +- Use XML tags only when the body has three or more logical sections and exceeds 500 tokens — default to plain prose +- Test the trigger description against all three cases — explicit, implicit, negative — before writing any body content. Hard gate: a failed case means revise and retest, not proceed +- Check for overlapping skills in `.agents/skills/` before writing anything — if overlap is found, surface it and wait for direction +- For placeholder conversions: read the existing SKILL.md first and remove all stale or outdated content + + + + + +## Process + +1. **Scan for overlap.** Check for skills with similar purpose or trigger phrases. If overlap is found, surface it and wait for explicit direction — do not continue. + +2. **Grill.** Run a focused grill with the /grill-me skill to reach shared understanding of: skill name, category, purpose, and use cases. One question at a time, with a recommendation for each. + +3. **Conflict check.** Spawn a sub-agent: read `docs/ai-constitution.md`, `docs/research/ai-coding-factory/ai-coding-factory-principles.md`, and `docs/notes/factory-integration-decisions.md`, then check the agreed skill purpose and design against all three. Where a factory principle is superseded by an integration decision, the decision takes precedence — do not flag it as a conflict. Return a numbered list of genuine unresolved tensions, or confirm none found. An empty list is a valid result. Hard gate: resolve any findings before proceeding. + +4. **Write and test the trigger description.** Using the agreed name, category, purpose, and use cases from the grill, draft `description:`. Propose negative trigger cases based on the skill's purpose and adjacent skills — get explicit user confirmation before running tests. Test all three cases and show per-case PASS/FAIL. A failed case means revise and retest — do not proceed. + +5. **Walk through each section.** For each section in `SKILL-TEMPLATE.md`: propose content, state where it comes from, present alternatives if they exist. Wait for explicit human confirmation before moving to the next section. + +6. **Copy both templates.** Copy `SKILL-TEMPLATE.md` to `.agents/skills//SKILL.md`. Copy `META-TEMPLATE.md` to `.agents/skills//META.md`. Do not modify content yet — copy first, fill second. + +7. **Fill both files.** Fill in the copied `SKILL.md` with confirmed section content. Fill in the copied `META.md` with version, updated date, when, source (if applicable), and references (if applicable). + +8. **Invoke `write-eval`.** Do not mark the skill complete without an eval file. + +9. **Run self-check.** Work through every item in the Self-check section below. Do not proceed until all items pass. + +10. **Prompt for HITL.** Ask the user to open a fresh session, trigger the skill, and confirm output before committing. + +## Output format + +Two files produced for every skill, plus optional sub-files if the skill requires them: + +- `SKILL.md` — copy-filled from `SKILL-TEMPLATE.md` at `.agents/skills//SKILL.md` +- `META.md` — copy-filled from `META-TEMPLATE.md` at `.agents/skills//META.md` +- `scripts/`, `references/`, or `assets/` — created only when needed; each file wired with an explicit step instruction + +For placeholder conversions, `SKILL.md` replaces the existing file entirely — no partial edits. + + + + + +## Failure handling + +- Template file missing — stop, report the path searched, do not write from memory +- Existing SKILL.md not found for a placeholder conversion — stop, report the path searched +- `write-eval` fails or is unavailable — flag, do not mark the skill complete + +## Self-check + +- [ ] Overlap check completed before any content was written +- [ ] Conflict check sub-agent ran against constitution and factory principles — findings resolved before any writing began +- [ ] Trigger description tested against all three cases — all passed before body content was written +- [ ] Negative trigger cases confirmed by user before testing +- [ ] Each section confirmed explicitly by user before SKILL.md was written +- [ ] SKILL.md copy-filled from `SKILL-TEMPLATE.md` at correct path +- [ ] `META.md` copy-filled from `META-TEMPLATE.md` at correct path +- [ ] Frontmatter contains `name`, `description`, and `metadata.category`; optional `allowed-tools` and `model:` only where justified +- [ ] Body is under 500 lines +- [ ] If sub-files exist: placed in correct directory type (`scripts/`, `references/`, or `assets/`) and wired with an explicit instruction in the relevant step +- [ ] For placeholder conversions: existing files read, all stale content removed, old directory deleted if renamed +- [ ] `write-eval` invoked — eval file exists at correct path, covers trigger cases (explicit, implicit, negative) and at least one output case + + diff --git a/plugins/kyberforge/docs/examples/skill-write/write-skill/evals/eval.yaml b/plugins/kyberforge/docs/examples/skill-write/write-skill/evals/eval.yaml new file mode 100644 index 0000000..1fee481 --- /dev/null +++ b/plugins/kyberforge/docs/examples/skill-write/write-skill/evals/eval.yaml @@ -0,0 +1,69 @@ +skill_name: write-skill + +trigger_tests: + - id: explicit-trigger-new-skill + name: Explicit — new skill phrase + query: "Write a new skill for handling database migrations" + should_trigger: true + + - id: implicit-trigger-no-phrase + name: Implicit — no trigger phrase + query: "I want to add a skill that automates our deploy process" + should_trigger: true + + - id: implicit-trigger-conversion + name: Implicit — placeholder conversion + query: "The grill-me skill is a Pocock placeholder, can you convert it to our standard?" + should_trigger: true + + - id: negative-trigger-upgrade + name: Negative — existing skill fix + query: "The tdd skill is producing wrong output, fix it" + should_trigger: false + + - id: negative-trigger-code-refactor + name: Negative — code refactor + query: "Refactor this module to use the new API client" + should_trigger: false + + - id: negative-trigger-write-eval + name: Negative — eval request + query: "Write evals for the diagnose skill" + should_trigger: false + +output_tests: + - id: output-has-all-sections + name: All 8 body sections present in order + type: deterministic + prompt: "Write a new skill for linting markdown files, category: implement" + expected_output: A complete SKILL.md containing all 8 required body sections in the prescribed order. + assertions: + - "Output contains '## Role'" + - "Output contains '## When to use / When not to use'" + - "Output contains '## Required inputs'" + - "Output contains '## Constraints'" + - "Output contains '## Process'" + - "Output contains '## Output format'" + - "Output contains '## Failure handling'" + - "Output contains '## Self-check'" + - "Sections appear in this order: ## Role, ## When to use / When not to use, ## Required inputs, ## Constraints, ## Process, ## Output format, ## Failure handling, ## Self-check" + + - id: output-path-correct + name: Output path and frontmatter fields correct + type: deterministic + prompt: "Write a new skill for sending Slack notifications on deploy events, category: deploy" + expected_output: A SKILL.md with correct output path stated and all required frontmatter fields present. + assertions: + - "Output contains '.agents/skills/' in the stated output path" + - "Output contains 'metadata:' and 'category:' in frontmatter" + - "Output contains 'version:'" + - "Output contains 'when:'" + + - id: output-trigger-tested-before-body + name: Trigger description tested before body content written + type: llm-rubric + prompt: "Write a new skill for summarising pull request diffs" + expected_output: The skill presents a trigger description and tests it against at least 3 cases (explicit, implicit, negative) before proposing or writing any body section content. + assertions: + - "The skill proposes a trigger description and explicitly tests it against an explicit query, an implicit query, and a negative query before writing any body section" + - "The skill walks through each body section individually and seeks confirmation before writing the file" diff --git a/plugins/kyberforge/docs/examples/skill-write/write-skill/sources.md b/plugins/kyberforge/docs/examples/skill-write/write-skill/sources.md new file mode 100644 index 0000000..cacb546 --- /dev/null +++ b/plugins/kyberforge/docs/examples/skill-write/write-skill/sources.md @@ -0,0 +1 @@ +I created this myself :) \ No newline at end of file