From 2a575d4a88fb6e8a28d6d6c824ddc1d5c7899a11 Mon Sep 17 00:00:00 2001 From: JC Date: Wed, 28 Jan 2026 13:58:54 -0500 Subject: [PATCH] =?UTF-8?q?Fix=20terminology:=20"third=20person"=20?= =?UTF-8?q?=E2=86=92=20"passive=20voice"?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The example "This skill should be used when..." is passive voice, not third person. Third person would be "The developer uses this skill when..." - this change corrects the terminology throughout the documentation. Co-Authored-By: Claude Opus 4.5 --- plugins/compound-engineering/CHANGELOG.md | 2 +- plugins/compound-engineering/CLAUDE.md | 4 ++-- .../skills/create-agent-skills/SKILL.md | 2 +- .../create-agent-skills/references/best-practices.md | 2 +- .../create-agent-skills/references/common-patterns.md | 2 +- .../create-agent-skills/references/official-spec.md | 2 +- .../create-agent-skills/references/skill-structure.md | 8 ++++---- .../skills/create-agent-skills/workflows/audit-skill.md | 2 +- .../create-agent-skills/workflows/create-new-skill.md | 2 +- 9 files changed, 13 insertions(+), 13 deletions(-) diff --git a/plugins/compound-engineering/CHANGELOG.md b/plugins/compound-engineering/CHANGELOG.md index dd1c7f9e..2810f82f 100644 --- a/plugins/compound-engineering/CHANGELOG.md +++ b/plugins/compound-engineering/CHANGELOG.md @@ -371,7 +371,7 @@ These updates operationalize a key insight from building agent-native mobile app - **All skills** - Fixed spec compliance issues across 12 skills: - Reference files now use proper markdown links (`[file.md](./references/file.md)`) instead of backtick text - - Descriptions now use third person ("This skill should be used when...") per skill-creator spec + - Descriptions now use passive voice ("This skill should be used when...") per skill-creator spec - Affected skills: agent-native-architecture, andrew-kane-gem-writer, compound-docs, create-agent-skills, dhh-rails-style, dspy-ruby, every-style-editor, file-todos, frontend-design, gemini-imagegen ### Added diff --git a/plugins/compound-engineering/CLAUDE.md b/plugins/compound-engineering/CLAUDE.md index fe08bf2d..5532e358 100644 --- a/plugins/compound-engineering/CLAUDE.md +++ b/plugins/compound-engineering/CLAUDE.md @@ -59,7 +59,7 @@ When adding or modifying skills, verify compliance with skill-creator spec: ### YAML Frontmatter (Required) - [ ] `name:` present and matches directory name (lowercase-with-hyphens) -- [ ] `description:` present and uses **third person** ("This skill should be used when..." NOT "Use this skill when...") +- [ ] `description:` is present and uses **passive voice** ("This skill should be used when..." NOT "Use this skill when...") ### Reference Links (Required if references/ exists) @@ -82,7 +82,7 @@ grep -E '`(references|assets|scripts)/[^`]+`' skills/*/SKILL.md # Check description format grep -E '^description:' skills/*/SKILL.md | grep -v 'This skill' -# Should return nothing if all use third person +# Should return nothing if all use passive voice ``` ## Documentation diff --git a/plugins/compound-engineering/skills/create-agent-skills/SKILL.md b/plugins/compound-engineering/skills/create-agent-skills/SKILL.md index fe690238..ac0ed21a 100644 --- a/plugins/compound-engineering/skills/create-agent-skills/SKILL.md +++ b/plugins/compound-engineering/skills/create-agent-skills/SKILL.md @@ -49,7 +49,7 @@ my-skill/ ### 4. Effective Descriptions -The description field enables skill discovery. Include both what the skill does AND when to use it. Write in third person. +The description field enables skill discovery. Include both what the skill does AND when to use it. Write in passive voice. **Good:** ```yaml diff --git a/plugins/compound-engineering/skills/create-agent-skills/references/best-practices.md b/plugins/compound-engineering/skills/create-agent-skills/references/best-practices.md index 23c76392..d1b517ed 100644 --- a/plugins/compound-engineering/skills/create-agent-skills/references/best-practices.md +++ b/plugins/compound-engineering/skills/create-agent-skills/references/best-practices.md @@ -107,7 +107,7 @@ Use **gerund form** (verb + -ing) for Skill names: ## Writing Effective Descriptions -**Always write in third person.** The description is injected into the system prompt. +**Always write in passive voice.** The description is injected into the system prompt. **Be specific and include key terms:** diff --git a/plugins/compound-engineering/skills/create-agent-skills/references/common-patterns.md b/plugins/compound-engineering/skills/create-agent-skills/references/common-patterns.md index 4f184f7d..59c16649 100644 --- a/plugins/compound-engineering/skills/create-agent-skills/references/common-patterns.md +++ b/plugins/compound-engineering/skills/create-agent-skills/references/common-patterns.md @@ -276,7 +276,7 @@ description: I can help you process Excel files and generate reports description: Processes Excel files and generates reports. Use when analyzing spreadsheets or .xlsx files. ``` -**Why it matters**: Skills must use third person. First/second person breaks the skill metadata pattern. +**Why it matters**: Skills must use passive voice. First/second person breaks the skill metadata pattern. diff --git a/plugins/compound-engineering/skills/create-agent-skills/references/official-spec.md b/plugins/compound-engineering/skills/create-agent-skills/references/official-spec.md index 59bdeabe..fd4214c6 100644 --- a/plugins/compound-engineering/skills/create-agent-skills/references/official-spec.md +++ b/plugins/compound-engineering/skills/create-agent-skills/references/official-spec.md @@ -116,7 +116,7 @@ Benefits: The `description` field enables Skill discovery and should include both what the Skill does and when to use it. -**Always write in third person.** The description is injected into the system prompt. +**Always write in passive voice.** The description is injected into the system prompt. - **Good:** "Processes Excel files and generates reports" - **Avoid:** "I can help you process Excel files" diff --git a/plugins/compound-engineering/skills/create-agent-skills/references/skill-structure.md b/plugins/compound-engineering/skills/create-agent-skills/references/skill-structure.md index 3349d3b5..a9f0f22d 100644 --- a/plugins/compound-engineering/skills/create-agent-skills/references/skill-structure.md +++ b/plugins/compound-engineering/skills/create-agent-skills/references/skill-structure.md @@ -81,7 +81,7 @@ Be consistent within your skill. If you use ``, don't also use ` @@ -107,10 +107,10 @@ description: What it does and when to use it (third person, specific triggers) **Validation rules**: - Non-empty, maximum 1024 characters - No XML tags -- Third person (never first or second person) +- Passive voice (never first or second person) - Include what it does AND when to use it -**Critical rule**: Always write in third person. +**Critical rule**: Always write in passive voice. - ✅ "Processes Excel files and generates reports" - ❌ "I can help you process Excel files" - ❌ "You can use this to process Excel files" @@ -360,7 +360,7 @@ Every skill must have: ``, ``, and `` Before finalizing a skill, verify: -- ✅ YAML frontmatter valid (name matches directory, description in third person) +- ✅ YAML frontmatter valid (name matches directory, description in passive voice) - ✅ No markdown headings in body (pure XML structure) - ✅ Required tags present: objective, quick_start, success_criteria - ✅ Conditional tags appropriate for complexity level diff --git a/plugins/compound-engineering/skills/create-agent-skills/workflows/audit-skill.md b/plugins/compound-engineering/skills/create-agent-skills/workflows/audit-skill.md index 364f78ef..f7adcd4e 100644 --- a/plugins/compound-engineering/skills/create-agent-skills/workflows/audit-skill.md +++ b/plugins/compound-engineering/skills/create-agent-skills/workflows/audit-skill.md @@ -50,7 +50,7 @@ Evaluate against each criterion: - [ ] Name matches directory name - [ ] Has `description:` field - [ ] Description says what it does AND when to use it -- [ ] Description is third person ("Use when...") +- [ ] Description is passive voice ("This skill should be used when...") ### Structure - [ ] SKILL.md under 500 lines diff --git a/plugins/compound-engineering/skills/create-agent-skills/workflows/create-new-skill.md b/plugins/compound-engineering/skills/create-agent-skills/workflows/create-new-skill.md index 1b01bbb1..4fdf8386 100644 --- a/plugins/compound-engineering/skills/create-agent-skills/workflows/create-new-skill.md +++ b/plugins/compound-engineering/skills/create-agent-skills/workflows/create-new-skill.md @@ -144,7 +144,7 @@ Domain knowledge that: Check: - [ ] YAML frontmatter valid - [ ] Name matches directory (lowercase-with-hyphens) -- [ ] Description says what it does AND when to use it (third person) +- [ ] Description says what it does AND when to use it (passive voice) - [ ] No markdown headings (#) in body - use XML tags - [ ] Required tags present: objective, quick_start, success_criteria - [ ] All referenced files exist