From c0334708c742fda442b377af54674df11794bc8a Mon Sep 17 00:00:00 2001 From: Paolo Mainardi Date: Sat, 6 Jun 2026 00:19:56 +0200 Subject: [PATCH] docs(skills): exclude caveman terse style from commit and MR/PR artifacts #91 Closes: sparkfabrik/sf-agents-harness#91 Assisted-by: claude-code/claude-opus-4-8 --- CHANGELOG.md | 1 + skills/system/gh/SKILL.md | 4 +--- skills/system/glab/SKILL.md | 4 +--- skills/system/sf-commit-convention/SKILL.md | 9 +++++++++ 4 files changed, 12 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8a7646f..1510132 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,7 @@ Changes are grouped by date. - README: Removed VS Code Insiders requirement for `chat.useAgentSkills` directive -- Agent Skills are now available in the standard VS Code release - `glab` skill: require fully-qualified references (`group/project#N`, `group/project!N`) in all written content (descriptions, comments, notes) to prevent broken cross-project links - `glab` skill: auto-closing issues on merge via `Closes`/`Fixes` directives in MR descriptions is now optional -- the agent asks the user before including a closing reference, since auto-close is not always desired +- `gh`, `glab`, and `sf-commit-convention` skills: consolidate the "write artifacts in plain prose" guidance into a single section per skill and state explicitly that an active terse output style (e.g. `CAVEMAN MODE ACTIVE`) does not apply to commit messages, MR/PR titles and descriptions, comments, or reviews -- these are always written in full prose ### Fixed diff --git a/skills/system/gh/SKILL.md b/skills/system/gh/SKILL.md index 3a5e8c1..ba22679 100644 --- a/skills/system/gh/SKILL.md +++ b/skills/system/gh/SKILL.md @@ -129,9 +129,7 @@ This applies to **every** piece of content the agent creates, regardless of leng These rules apply to every issue title and description, pull request title and description, comment, review, and commit message you write. -**Write in plain, professional prose.** Issue and pull request titles and descriptions — and commit messages — must always be written in normal, complete, well-structured English: full sentences, articles, and proper markdown. They are durable, outward-facing documents that other people read and that GitHub renders in its UI; compression hurts readability and looks unprofessional. - -This rule **overrides any active terse output style for the duration of writing these artifacts.** A session-level style may inject a per-turn reminder such as `CAVEMAN MODE ACTIVE` (drop articles, fragments OK, short synonyms). That reminder applies to your conversational replies, not to the artifacts. When you compose an issue/PR title or body, a comment, a review, or a commit message, ignore that reminder for that block of text and write full prose; resume the terse conversational style for your surrounding chat replies. Do not run any command to toggle the style off — just write the artifact in plain prose regardless of what reminder is present. +**Write in plain, professional prose.** Issue and pull request titles and descriptions, comments and reviews, and commit messages must always be written in normal, complete, well-structured English: full sentences, articles, and proper markdown. They are durable, outward-facing documents that other people read and that GitHub renders in its UI; compression hurts readability and looks unprofessional. This rule **overrides any active terse output style for the duration of writing these artifacts.** A session-level style may inject a per-turn reminder such as `CAVEMAN MODE ACTIVE` (drop articles, fragments OK, short synonyms); that reminder applies to your conversational replies, not to the artifacts. When you compose an issue/PR title or body, a comment, a review, or a commit message, write full prose regardless of the active style, then resume the terse conversational style for your surrounding chat replies. Do not run any command to toggle the style off; just write the artifact in plain prose regardless of what reminder is present. **Use the full path for cross-project references.** When you reference an issue or pull request that lives in a _different_ repository than the one you are writing in, use the full `owner/repo#123` form rather than a bare `#123`. A bare `#123` (or a short form) only resolves within the same repository and will not render as a link from another repository. Apply this in prose and in footers alike (`Closes:`, `Refs:`). For example, to reference the platform-team board from a code repository, write `sparkfabrik-innovation-team/board#4379`, never a bare `board#4379` or `#4379`. Within the same repository, a bare `#123` is correct and renders as a link. diff --git a/skills/system/glab/SKILL.md b/skills/system/glab/SKILL.md index 9103054..05a00d4 100644 --- a/skills/system/glab/SKILL.md +++ b/skills/system/glab/SKILL.md @@ -140,9 +140,7 @@ This rule applies **only to written content** (descriptions, comments, closing k ### Write in plain, professional prose -Issue and merge request titles and descriptions — and commit messages — must always be written in normal, complete, well-structured English: full sentences, articles, and proper markdown. They are durable, outward-facing documents that other people read and that GitLab renders in its UI; compression hurts readability and looks unprofessional. - -This rule **overrides any active terse output style for the duration of writing these artifacts.** A session-level style may inject a per-turn reminder such as `CAVEMAN MODE ACTIVE` (drop articles, fragments OK, short synonyms). That reminder applies to your conversational replies, not to the artifacts. When you compose an issue/MR title or body, a comment, a note, or a commit message, ignore that reminder for that block of text and write full prose; resume the terse conversational style for your surrounding chat replies. Do not run any command to toggle the style off — just write the artifact in plain prose regardless of what reminder is present. +Issue and merge request titles and descriptions, comments and notes, and commit messages must always be written in normal, complete, well-structured English: full sentences, articles, and proper markdown. They are durable, outward-facing documents that other people read and that GitLab renders in its UI; compression hurts readability and looks unprofessional. This rule **overrides any active terse output style for the duration of writing these artifacts.** A session-level style may inject a per-turn reminder such as `CAVEMAN MODE ACTIVE` (drop articles, fragments OK, short synonyms); that reminder applies to your conversational replies, not to the artifacts. When you compose an issue/MR title or body, a comment, a note, or a commit message, write full prose regardless of the active style, then resume the terse conversational style for your surrounding chat replies. Do not run any command to toggle the style off; just write the artifact in plain prose regardless of what reminder is present. ### Avoid AI-slop writing tells diff --git a/skills/system/sf-commit-convention/SKILL.md b/skills/system/sf-commit-convention/SKILL.md index 2aab24b..3cadf1c 100644 --- a/skills/system/sf-commit-convention/SKILL.md +++ b/skills/system/sf-commit-convention/SKILL.md @@ -108,6 +108,15 @@ Example: `Assisted-by: opencode/github-copilot/claude-opus-4.6` Same conventional commit format as the subject line. The issue reference goes in the MR/PR description body, never in the title. +## Write in plain prose, not caveman + +Commit messages (subject and body) and MR/PR titles are durable, outward-facing +artifacts: write them in normal, complete English. An active terse output style +overrides nothing here. A session-level reminder such as `CAVEMAN MODE ACTIVE` +(drop articles, fragments OK, short synonyms) applies to your conversational +replies, not to these artifacts. Write the commit and title in full prose +regardless of the active style; do not run any command to toggle the style off. + ## Quick Example ```bash