From 104bf68e869bd6438405b824e9606cb54c337858 Mon Sep 17 00:00:00 2001 From: Christopher Tso Date: Thu, 26 Mar 2026 11:11:03 +1100 Subject: [PATCH 1/2] Add domain-specific vs universal content guidelines to skill quality checklist Skills should only contain domain-specific knowledge (internal conventions, business patterns, context for WHY rules exist) and exclude universal concepts AI agents already know (SOLID, DRY, obvious examples, standard best practices). Co-Authored-By: Claude Opus 4.6 (1M context) --- plugins/agentic-engineering/skills/agent-plugin-review/SKILL.md | 1 + .../agent-plugin-review/references/skill-quality-checklist.md | 2 ++ 2 files changed, 3 insertions(+) diff --git a/plugins/agentic-engineering/skills/agent-plugin-review/SKILL.md b/plugins/agentic-engineering/skills/agent-plugin-review/SKILL.md index 3be083561..9ba106df0 100644 --- a/plugins/agentic-engineering/skills/agent-plugin-review/SKILL.md +++ b/plugins/agentic-engineering/skills/agent-plugin-review/SKILL.md @@ -45,6 +45,7 @@ For each SKILL.md, check against `references/skill-quality-checklist.md`: - Description starts with "Use when..." and describes triggering conditions only (not workflow) - Description does NOT summarize the skill's process — this causes agents to follow the description instead of reading the SKILL.md body - Body is concise — only include what the agent doesn't already know +- Content is domain-specific (internal conventions, business patterns, context for WHY) — universal concepts AI agents already know are excluded - Imperative/infinitive form, not second person - Heavy reference (100+ lines) moved to `references/` files - One excellent code example beats many mediocre ones diff --git a/plugins/agentic-engineering/skills/agent-plugin-review/references/skill-quality-checklist.md b/plugins/agentic-engineering/skills/agent-plugin-review/references/skill-quality-checklist.md index 1a8f279ca..e4f8f66fd 100644 --- a/plugins/agentic-engineering/skills/agent-plugin-review/references/skill-quality-checklist.md +++ b/plugins/agentic-engineering/skills/agent-plugin-review/references/skill-quality-checklist.md @@ -46,6 +46,8 @@ description: Use when tests have race conditions, timing dependencies, or pass/f ### Conciseness (Claude Search Optimization) - [ ] SKILL.md body is concise — only include what Claude doesn't already know +- [ ] Content is domain-specific: technology preferences, internal conventions, business domain patterns, industry constraints, context explaining WHY rules exist +- [ ] Universal concepts excluded: standard programming principles (SOLID, DRY, etc.), obvious examples, verbose explanations, best practices AI agents already know - [ ] Challenge each paragraph: "Does Claude really need this explanation?" - [ ] Target word counts: - Frequently-loaded skills: < 200 words From 36ff9fc4cc36da163df3c5fadfba0bf00117aee3 Mon Sep 17 00:00:00 2001 From: Christopher Tso Date: Thu, 26 Mar 2026 11:12:48 +1100 Subject: [PATCH 2/2] Replace Claude-specific references with agent-agnostic language The skill quality checklist applies to any AI agent (Claude, Codex, Copilot, etc.), not just Claude. Replace "Claude" with "the agent" throughout. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../references/skill-quality-checklist.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/plugins/agentic-engineering/skills/agent-plugin-review/references/skill-quality-checklist.md b/plugins/agentic-engineering/skills/agent-plugin-review/references/skill-quality-checklist.md index e4f8f66fd..d3e95575c 100644 --- a/plugins/agentic-engineering/skills/agent-plugin-review/references/skill-quality-checklist.md +++ b/plugins/agentic-engineering/skills/agent-plugin-review/references/skill-quality-checklist.md @@ -14,12 +14,12 @@ Derived from [Superpowers writing-skills](https://github.com/obra/superpowers/) ### Why description must not summarize workflow -Testing revealed that when a description summarizes the skill's workflow, Claude may follow the description instead of reading the full SKILL.md content. A description saying "code review between tasks" caused Claude to do ONE review, even though the SKILL.md flowchart clearly showed TWO reviews. When the description was changed to just triggering conditions, Claude correctly read and followed the full skill. +Testing revealed that when a description summarizes the skill's workflow, the agent may follow the description instead of reading the full SKILL.md content. A description saying "code review between tasks" caused the agent to do ONE review, even though the SKILL.md flowchart clearly showed TWO reviews. When the description was changed to just triggering conditions, the agent correctly read and followed the full skill. ### Description examples ```yaml -# BAD: Summarizes workflow - Claude may follow this instead of reading skill +# BAD: Summarizes workflow - the agent may follow this instead of reading skill description: Use when executing plans - dispatches subagent per task with code review between tasks # BAD: Too much process detail @@ -43,12 +43,12 @@ description: Use when tests have race conditions, timing dependencies, or pass/f ## Content Quality -### Conciseness (Claude Search Optimization) +### Conciseness (Agent Search Optimization) -- [ ] SKILL.md body is concise — only include what Claude doesn't already know +- [ ] SKILL.md body is concise — only include what the agent doesn't already know - [ ] Content is domain-specific: technology preferences, internal conventions, business domain patterns, industry constraints, context explaining WHY rules exist - [ ] Universal concepts excluded: standard programming principles (SOLID, DRY, etc.), obvious examples, verbose explanations, best practices AI agents already know -- [ ] Challenge each paragraph: "Does Claude really need this explanation?" +- [ ] Challenge each paragraph: "Does the agent really need this explanation?" - [ ] Target word counts: - Frequently-loaded skills: < 200 words - Standard skills: < 500 words @@ -114,7 +114,7 @@ Match specificity to the task's fragility: | Generic labels (helper1, step2) | No semantic meaning | | Version printing instructions | Fragile, rely on git history | | Hardcoded local paths | Machine-specific, not portable | -| Description summarizes workflow | Claude follows description, skips SKILL.md body | +| Description summarizes workflow | the agent follows description, skips SKILL.md body | ## Discipline-Enforcing Skills (Additional Checks)