From d9a894f49f56edb63ed97a051a51876d424452b6 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Tue, 26 May 2026 18:57:24 +0000 Subject: [PATCH] =?UTF-8?q?refactor:=20self-compliance=20run=20=E2=80=94?= =?UTF-8?q?=20write-skill=20against=20its=20own=20standard?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Insert explicit self-check step (step 9) before HITL (step 10); self-check runs after write-eval so all items are verifiable - Remove HITL from self-check checklist — HITL may occur across a PR boundary after the session ends - Fix frontmatter constraint and self-check item to acknowledge optional `model:` field alongside `allowed-tools` - Conflict-check sub-agent now also reads factory-integration-decisions.md with explicit precedence rule: integration decisions override factory principles — prevents false positives from deliberately overridden decisions - Bump to v1.5 Co-Authored-By: Claude Sonnet 4.6 --- .agents/skills/write-skill/META.md | 2 +- .agents/skills/write-skill/SKILL.md | 11 ++++++----- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/.agents/skills/write-skill/META.md b/.agents/skills/write-skill/META.md index 9bec5e2..ffd2f54 100644 --- a/.agents/skills/write-skill/META.md +++ b/.agents/skills/write-skill/META.md @@ -1,5 +1,5 @@ ```yaml -version: "1.4" +version: "1.5" updated: 2026-05-26 # when: describes when this skill is loaded — the full trigger context. diff --git a/.agents/skills/write-skill/SKILL.md b/.agents/skills/write-skill/SKILL.md index b068559..8659691 100644 --- a/.agents/skills/write-skill/SKILL.md +++ b/.agents/skills/write-skill/SKILL.md @@ -20,7 +20,7 @@ Negative trigger cases are NOT a required input. The agent proposes them based o ## Constraints - Write two files for every skill: `SKILL.md` at `.agents/skills//SKILL.md` and `META.md` alongside it -- Frontmatter has three fields only: `name`, `description`, and `metadata.category` — add `allowed-tools` only when the skill has a narrow, well-defined tool surface +- 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 @@ -38,7 +38,7 @@ Negative trigger cases are NOT a required input. The agent proposes them based o 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` and `docs/research/ai-coding-factory/ai-coding-factory-principles.md`, then check the agreed skill purpose and design against both documents. Return a numbered list of tensions or conflicts, or confirm none found. An empty list is a valid result — it confirms the design is clean before writing begins. Hard gate: resolve any findings before proceeding. +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. @@ -50,7 +50,9 @@ Negative trigger cases are NOT a required input. The agent proposes them based o 8. **Invoke `write-eval`.** Do not mark the skill complete without an eval file. -9. **Prompt for HITL.** Ask the user to open a fresh session, trigger the skill, and confirm output before committing. +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 @@ -81,11 +83,10 @@ For placeholder conversions, `SKILL.md` replaces the existing file entirely — - [ ] 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 only `name`, `description`, and `metadata.category` (plus `allowed-tools` if applicable) +- [ ] 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 -- [ ] User prompted for HITL behavioral test