bmottin/claude_mac
1
0
Fork 0
forked from bchanot/claude
Code Pull Requests Activity

refactor(skills): compress 8 SKILL.md descriptions per writing-skills spec

Browse Source 
Two issues fixed across personal skills:

1. Five skills had frontmatter > 1024 chars (spec limit per agentskills.io):
   - client-handover: 1920 → 924
   - doc: 1390 → 734
   - seo: 1378 → 885
   - geo: 1189 → 734
   - validate: 1050 → 742
   All now compliant.

2. Three orchestrators had workflow-summary descriptions that create
   "shortcut" risk per writing-skills CSO (Claude may follow the
   description instead of reading the full skill body, skipping steps):
   - ship-feature: "design → plan → implement (TDD) → review → finish"
     → "Use when shipping a feature end-to-end — needs… (9-step pipeline)"
   - init-project: "interview → design → scaffold → implement (TDD)"
     → "Use when initializing a brand-new project from scratch — needs…"
   - onboard: "detect archetype, install claude-config, run full audit…"
     → "Use when bringing an existing repo into the framework — needs…"

Descriptions now follow "Use when [triggers]…" pattern. Workflow detail
preserved in skill body where it belongs. Triggers consolidated and
trimmed of duplicates.

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
bastien
2026-05-11 16:09:21 +02:00
co-authored by Claude
parent 7db8f01074
commit 0fb634deca
8 changed files with 46 additions and 88 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/doc/SKILL.md
+8 -16
View File
@@ -1,22 +1,14 @@
---
name: doc
description: |
Full documentation audit and sync. Auto-detects what doc files the project
actually has — root docs (README, CLAUDE.md, INSTALL.md, CONFIGURE.md,
USAGE.md, DEPLOY.md, CONTRIBUTING.md, CHANGELOG.md), docs/**/*.md, project-state
files in .claude/{tasks,audits,memory}/, and inline comments (JSDoc, docstrings,
rustdoc, godoc). Stack-aware: detects framework + deploy complexity, proposes
DEPLOY.md only when non-trivial (Docker, fly.toml, k8s, multi-stage CI), skips
for trivial deploys (FTP push, single scp, plain static). Enforces README
presence with typical GitHub layout (title, quick start, links to existing
sub-docs). Cross-references git history for drift; detects added features
missing from docs and removed features still documented (feature delta
detection). Reports drift with commit refs, proposes fixes, patches approved
items.
Trigger: "doc", "sync docs", "audit docs", "update readme", "check documentation",
"are docs up to date", "documentation drift", "stale docs", "new feature not documented",
"removed feature still in docs", "create README", "should I have a DEPLOY doc".
Replaces the old /readme skill with broader scope.
Use when documentation may be out of sync with code — added features
missing from docs, removed features still documented, or README / INSTALL
/ DEPLOY / CHANGELOG drift detected. Stack-aware audit, cross-references
git history, patches approved items.
Triggers: "doc", "sync docs", "audit docs", "update readme", "check
documentation", "are docs up to date", "documentation drift", "stale docs",
"new feature not documented", "removed feature still in docs",
"create README", "should I have a DEPLOY doc".
argument-hint: [leave empty for full audit, or list specific files/docs to check]
disable-model-invocation: false
allowed-tools: