Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

docs(kyberforge): preserve old write-skill as reference example

Browse Source 
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 <noreply@anthropic.com>
This commit is contained in:
Defame1297
2026-06-22 18:51:09 +00:00
parent 672fd25890
commit 6317b5c844
7 changed files with 320 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
plugins/kyberforge/docs/examples/skill-write/write-skill/CATEGORIES.md Normal file
View File

@@ -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 |

27
plugins/kyberforge/docs/examples/skill-write/write-skill/META-TEMPLATE.md Normal file
View File

@@ -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: <describe the invocation conditions here>
# 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: <full SHA> # 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
```

16
plugins/kyberforge/docs/examples/skill-write/write-skill/META.md Normal file
View File

@@ -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
```

93
plugins/kyberforge/docs/examples/skill-write/write-skill/SKILL-TEMPLATE.md Normal file
View File

@@ -0,0 +1,93 @@
---
name: <skill-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: <trigger description>
metadata:
category: <category — see CATEGORIES.md>
# allowed-tools: <add only when the skill has a narrow, well-defined tool surface; omit otherwise>
# 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.
---
<requirements>
## Required inputs
<!-- List each required input as a bullet: name, what it is, how the agent obtains it.
Negative trigger cases are NOT listed here — the agent proposes them during trigger testing.
Example:
- **Skill name** — kebab-case slug; inferred from user description if not stated explicitly, ask if ambiguous
- **Existing SKILL.md path** — for placeholder conversions only; read before writing -->
- **<Input name>** — <description; how obtained>
## Constraints
<!-- One rule per bullet. State the boundary condition inline. Plain English, no jargon.
Do not include a constraint about body section structure — the template enforces that.
Example:
- Frontmatter has three fields only: `name`, `description`, and `metadata.category` — add `allowed-tools` only when the skill has a narrow, well-defined tool surface
- Body ≤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). File references must be one level deep. Wire each sub-file with an explicit step instruction (e.g. "See references/lookup.md for error codes") — without wiring, the file is never loaded -->
- <constraint>
</requirements>
<steps>
## Process
<!-- Numbered steps with a bold action label. Short, direct sentences — state what to do and
what happens as a result. Call out hard gates explicitly (steps that block all progress
until satisfied). No preamble, no meta-commentary about the steps themselves.
Example:
1. **Scan for overlap.** Check `.agents/skills/` 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 to reach shared understanding of: skill name, category, purpose, and use cases. One question at a time, with a recommendation for each. -->
1. **<Step name>.** <what to do and what happens as a result>
## Output format
<!-- Describe the files or artifacts produced. Include paths and how they are created
(copy-fill from template, generated, etc.). State the template used for structured file output.
Example:
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/<name>/SKILL.md`
- `META.md` — copy-filled from `META-TEMPLATE.md` at `.agents/skills/<name>/META.md`
- `scripts/`, `references/`, or `assets/` — created only when needed; each file wired with an explicit step instruction -->
<description of output>
</steps>
<checks>
## Failure handling
<!-- One bullet per failure mode. Lean — no overlap with constraints or process.
Format: condition — action.
Example:
- Template file missing — stop, report the path searched, do not write from memory
- `write-eval` fails or is unavailable — flag, do not mark the skill complete -->
- <failure condition> — <what to do>
## Self-check
<!-- Verifiable checklist the agent runs before declaring the skill complete.
Each item must be checkable, not aspirational.
Example:
- [ ] Overlap check completed before any content was written
- [ ] Trigger description tested against all three cases — all passed before body content was written -->
- [ ] <check>
</checks>

98
plugins/kyberforge/docs/examples/skill-write/write-skill/SKILL.md Normal file
View File

@@ -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
---
<requirements>
## 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/<name>/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
</requirements>
<steps>
## 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/<name>/SKILL.md`. Copy `META-TEMPLATE.md` to `.agents/skills/<name>/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/<name>/SKILL.md`
- `META.md` — copy-filled from `META-TEMPLATE.md` at `.agents/skills/<name>/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.
</steps>
<checks>
## 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
</checks>

69
plugins/kyberforge/docs/examples/skill-write/write-skill/evals/eval.yaml Normal file
View File

@@ -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"

1
plugins/kyberforge/docs/examples/skill-write/write-skill/sources.md Normal file
View File

@@ -0,0 +1 @@
I created this myself :)