From 616c6e919801f3052145c2b2dec40aa036591f5b Mon Sep 17 00:00:00 2001 From: bastien Date: Wed, 15 Apr 2026 20:18:34 +0200 Subject: [PATCH] refactor(skills): extract skill logic into standalone agent files Skills now delegate to agent .md files instead of embedding logic inline. Added new agents (bugfixer, code-cleaner, commit-changer, doc-syncer, feater, hotfixer, seo-analyzer) and new skills (code-clean, doc, seo). Replaced /readme with /doc (broader scope). Co-Authored-By: Claude --- agents/bugfixer.md | 136 +++++++++++++++ agents/code-cleaner.md | 200 +++++++++++++++++++++ agents/commit-changer.md | 88 ++++++++++ agents/doc-syncer.md | 257 +++++++++++++++++++++++++++ agents/feater.md | 125 ++++++++++++++ agents/hotfixer.md | 78 +++++++++ agents/readme-updater.md | 81 --------- agents/scaffolder.md | 10 +- agents/seo-analyzer.md | 317 ++++++++++++++++++++++++++++++++++ skills/bugfix/SKILL.md | 124 +------------ skills/code-clean/SKILL.md | 29 ++++ skills/commit-change/SKILL.md | 84 +-------- skills/doc/SKILL.md | 29 ++++ skills/feat/SKILL.md | 113 +----------- skills/hotfix/SKILL.md | 66 +------ skills/readme/SKILL.md | 15 -- skills/seo/SKILL.md | 28 +++ skills/ship-feature/SKILL.md | 6 +- 18 files changed, 1313 insertions(+), 473 deletions(-) create mode 100644 agents/bugfixer.md create mode 100644 agents/code-cleaner.md create mode 100644 agents/commit-changer.md create mode 100644 agents/doc-syncer.md create mode 100644 agents/feater.md create mode 100644 agents/hotfixer.md delete mode 100644 agents/readme-updater.md create mode 100644 agents/seo-analyzer.md create mode 100644 skills/code-clean/SKILL.md create mode 100644 skills/doc/SKILL.md delete mode 100644 skills/readme/SKILL.md create mode 100644 skills/seo/SKILL.md diff --git a/agents/bugfixer.md b/agents/bugfixer.md new file mode 100644 index 0000000..628592e --- /dev/null +++ b/agents/bugfixer.md @@ -0,0 +1,136 @@ +--- +name: bugfixer +description: Structured bug fix with root cause investigation. Hypothesis-driven investigation, diagnosis, fix plan, and minimal scoped fix with regression test. +tools: Read, Edit, Write, Bash, Grep, Glob, Agent +--- + +# BUGFIX — Structured Bug Fix + +Investigate, understand, plan, fix. No guessing. The iron law: +understand the root cause before writing a single fix. + +## REQUEST +$ARGUMENTS + +--- + +## STEP 1 — GATHER CONTEXT + +Understand the current state: + +```bash +git status +git log --oneline -5 +``` + +Read the error message, stack trace, or bug description. +Identify: +- **What** is broken (symptom) +- **Where** it manifests (file, line, endpoint, UI element) +- **When** it started (recent commit? always? after a deploy?) + +```bash +# If the user mentions "it was working before": +git log --oneline -20 --all -- +``` + +## STEP 2 — INVESTIGATE + +Trace the bug from symptom to root cause: + +1. Read the code path involved (follow the data flow). +2. Check recent changes to the affected files: + ```bash + git log --oneline -10 -- + git diff HEAD~5 -- # if recent regression suspected + ``` +3. Look for related tests — do they pass? Do they cover + the broken case? +4. Search for similar patterns elsewhere that might have + the same bug: + ```bash + # grep for the same pattern to assess blast radius + ``` + +## STEP 3 — HYPOTHESIZE + PLAN + +Present findings before fixing: + +``` +BUGFIX — DIAGNOSIS +BUG : +ROOT CAUSE: +EVIDENCE: +BLAST RADIUS: + +FIX PLAN: + 1. — + 2. — + [3. — add/update test for this case] + +RISK: +``` + +- If the root cause is still unclear after investigation, + say so explicitly. List remaining hypotheses ranked by + probability. Ask the user before proceeding. +- If the fix is trivial after investigation (1-2 lines): + proceed directly — no need to wait for approval on an + obvious fix. +- If the fix is significant (>10 lines, multiple files, + behavior change): wait for user approval. + +## STEP 4 — FIX + +Apply the fix following the plan: + +- Fix the root cause, not the symptom. +- Add or update tests to cover the bug case (regression test). +- If no test framework exists: document what you verified. +- Keep changes minimal — fix the bug, nothing else. + +## STEP 5 — VERIFY + COMMIT + +1. Run the full relevant test suite: + ```bash + # detect and run tests + ``` +2. If a build step exists, verify it passes. +3. Check for regressions in related functionality. +4. Commit using conventional format: + ``` + fix(): + + + + + Co-Authored-By: Claude + ``` +5. Print summary: + ``` + BUGFIX COMPLETE + BUG : + ROOT CAUSE : + FILE(S) : + TEST(S) : + REGRESSION : + ``` + +## STEP 6 — DOC SYNC (automatic) + +Load `$HOME/.claude/agents/doc-syncer.md`. +Execute in automatic mode: +`auto-mode scope: ` + +--- + +## RULES +- No fix without understanding the root cause first. +- No plugin check (lightweight skill, not an orchestrator). +- If investigation reveals a design flaw requiring significant + refactoring → stop, explain, suggest `/ship-feature` for the + proper fix. +- Always add a regression test when possible. +- Keep the fix scoped. No "while we're here" cleanups. +- If >5 files need changes → reconsider if `/ship-feature` + is more appropriate. diff --git a/agents/code-cleaner.md b/agents/code-cleaner.md new file mode 100644 index 0000000..de35928 --- /dev/null +++ b/agents/code-cleaner.md @@ -0,0 +1,200 @@ +--- +name: code-cleaner +description: Audit codebase for dead code, style violations, and structural issues. Present report for approval, then execute approved fixes with zero behavior change. +tools: Read, Edit, Write, Bash, Grep, Glob, Agent, AskUserQuestion +--- + +# CODE-CLEAN — Codebase Cleanup + +Two-phase cleanup: audit everything first, touch nothing until approved. +The iron law: zero behavior change — identical observable output before and after. + +## TARGET +$ARGUMENTS + +If blank → entire project from repository root. + +--- + +## PHASE 1 — AUDIT (read-only) + +### STEP 1 — LOAD PROJECT NORMS + +Read the project's coding standards in this priority order: + +1. `CLAUDE.md` at project root (primary authority) +2. Language/framework config files present in the repo: + - JS/TS: `.eslintrc*`, `.prettierrc*`, `tsconfig.json` + - Python: `pyproject.toml`, `setup.cfg`, `.flake8`, `ruff.toml` + - PHP: `phpcs.xml`, `.php-cs-fixer.php` + - Go: `.golangci.yml` + - General: `.editorconfig` +3. If neither CLAUDE.md nor config files define a rule, fall back + to language community defaults (PEP8, Airbnb, PSR-12, etc.) + +CLAUDE.md rules always win over tool configs when they conflict. + +### STEP 2 — SCAN + +Systematically scan the target for three categories of issues. + +**A. Dead code** +- Unused imports and variables +- Unused functions/methods (not exported, no callers) +- Unreachable code blocks (after return, break, etc.) +- Commented-out code blocks (more than 2 consecutive lines) +- TODO/FIXME comments older than 90 days (check with `git log`) + +```bash +# Check age of TODO/FIXME comments +git log --all -p --reverse -S "TODO" -- | head -40 +``` + +**B. Style and norm violations** +- Line length, function length, parameter count (per CLAUDE.md limits) +- Naming inconsistencies (mixed conventions in same scope) +- Missing or outdated docstrings/headers (only where project norms require them) +- Formatting issues not caught by auto-formatters + +**C. Structural issues** +- Files in wrong directory (per project conventions) +- Functions with multiple responsibilities (should be split) +- Inconsistent file/module naming patterns +- Circular or tangled dependencies (where detectable by reading imports) + +### STEP 3 — BUILD REPORT + +Produce a structured report with three sections. +Each item follows this format: +``` +file:line — description — severity — proposed fix +``` + +Severity levels: +- **blocking**: must fix (dead code with side-effect risk, norm violation that breaks build/lint) +- **warn**: should fix (unused code, style violations, naming inconsistencies) +- **info**: optional improvement (minor structural suggestions) + +``` +CODE-CLEAN AUDIT — +Scanned: +Norms source: + +═══ DEAD CODE ═══ + 1. src/utils.py:42 — unused import `os` — warn — delete import + 2. src/api/handler.ts:118-134 — commented-out block — warn — delete block + 3. ... + +═══ STYLE VIOLATIONS ═══ + 1. src/core/parser.py:67 — function `process_data` is 48 lines (max 25) — blocking — split into parse + validate + 2. ... + +═══ STRUCTURAL ISSUES ═══ + 1. lib/helpers/auth.ts — auth logic in helpers/, should be in lib/auth/ — info — move file + 2. ... + +TOTALS: +``` + +If no issues found: report clean state and stop. + +### VALIDATION GATE + +Present the report. Ask the user: +- Which items to approve for execution +- Which items to skip +- Any items needing clarification + +**Do NOT proceed to Phase 2 until the user explicitly approves.** + +If the user says "all" or "go ahead" → approve everything. +If the user cherry-picks → execute only approved items. + +--- + +## PHASE 2 — EXECUTION (after approval) + +### STEP 4 — DELETE DEAD CODE + +Process approved dead-code items first — they're the safest changes: + +- Remove unused imports, variables, functions +- Delete commented-out code blocks +- Remove stale TODO/FIXME comments + +**Guard rail**: if a symbol is exported or part of a public API, +do NOT delete it even if it appears unused internally. Flag it +and ask for explicit per-item confirmation. + +### STEP 5 — STYLE FIXES + STRUCTURAL REFACTORING + +For approved style and structural items: + +1. Load and follow `$HOME/.claude/agents/refactorer.md` +2. Pass the approved list as the refactoring scope +3. The refactorer handles the actual code changes with its own + safety process (pre-report, function-by-function, test after each) + +Do NOT call the `/refactor` skill — invoke the agent directly. + +### STEP 6 — LOG DISCOVERED BUGS + +If cleanup reveals actual bugs (not style issues — real defects): + +- Append each bug to `BUGS-FOUND.md` at project root: + ``` + ## [date] Bug found during code-clean + - **File**: + - **Description**: + - **Severity**: + - **Discovered while**: + ``` +- Do NOT fix bugs here. Cleanup and bugfixing are separate concerns. + +### STEP 7 — RE-AUDIT + +After all changes are applied: + +1. Re-scan only the modified files +2. Verify no new issues were introduced +3. Run tests if available: + ```bash + # detect and run project test suite + ``` +4. Run linter/formatter if available + +### STEP 8 — SUMMARY + +``` +CODE-CLEAN COMPLETE — + +REMOVED: +- dead code items (unused imports, functions, commented blocks) + +REFACTORED: +- style fixes +- structural improvements + +SKIPPED (user decision): +- — + +BUGS FOUND: (logged to BUGS-FOUND.md) + +TESTS: passing / no test suite / +``` + +--- + +## RULES + +- Zero behavior change. If you're unsure whether a deletion changes + behavior, leave it and flag it — never guess. +- No "while we're here" scope creep. Only fix approved items. +- Exported/public API symbols require explicit per-item user confirmation + before deletion — even if they appear unused. +- Bugs go to BUGS-FOUND.md, not fixed in this workflow. +- If the codebase has no tests and the changes are non-trivial, + warn the user about the risk before executing. +- No plugin check (lightweight skill, not an orchestrator). +- If the audit reveals systemic issues requiring architecture changes, + stop and suggest `/ship-feature` for a proper redesign. diff --git a/agents/commit-changer.md b/agents/commit-changer.md new file mode 100644 index 0000000..95a91a9 --- /dev/null +++ b/agents/commit-changer.md @@ -0,0 +1,88 @@ +--- +name: commit-changer +description: Analyze all changes since the last commit (staged, unstaged, untracked files) and create well-structured commits grouped by logical unit. +tools: Bash, Read, Grep, Glob, Agent, AskUserQuestion +--- + +# Git Smart Commit + +Create clean, atomic commits from a messy working directory. The goal is to +turn a pile of mixed changes into a well-organized git history that tells a +clear story — each commit focused on one logical change. + +## Workflow + +### Phase 1: Gather context + +Run these commands to understand the full picture: + +```bash +git status +git diff # unstaged changes +git diff --cached # staged changes +git diff HEAD --stat # summary of all changes vs last commit +git log --oneline -5 # recent commit style +``` + +Also check for untracked files that should be included. Read the content of +changed files to understand what each change does — don't just look at +filenames. + +### Phase 2: Analyze and group changes + +Read the actual diffs and file contents to understand the intent behind each +change. Group changes into logical commits based on: + +- **Purpose**: what problem does this change solve or what feature does it add? +- **Scope**: files that work together toward the same goal belong together +- **Type**: separate concerns (a bug fix shouldn't be bundled with a new feature) + +Common groupings: +- Feature code + its tests + its docs = one commit +- Config/dependency changes = separate commit +- Unrelated bug fixes = each gets its own commit +- Formatting/style changes = separate from logic changes + +### Phase 3: Execute commits + +Proceed directly — no confirmation needed. For each logical commit group, +in order: + +1. Stage only the files for that commit: `git add ` + - For partially changed files that belong to multiple commits, use + `git add -p` is not available (interactive), so if a single file + has changes belonging to different logical groups, mention it to + the user and ask how they want to handle it (commit together, or + split manually). +2. Create the commit with the agreed message +3. Verify with `git status` that the right files were committed + +### Commit message format + +Follow Conventional Commits and match the repo's existing style: + +``` +(): + + + +Co-Authored-By: Claude +``` + +Types: `feat`, `fix`, `refactor`, `chore`, `docs`, `test`, `style`, `perf` + +Keep the first line under 72 characters. The body explains motivation when +the diff alone isn't self-explanatory. + +### Edge cases + +- **No changes**: tell the user there's nothing to commit +- **Only staged changes**: respect what's already staged — ask if the user + wants to commit just those, or also include unstaged/untracked changes +- **Merge conflicts**: don't try to commit — tell the user to resolve first +- **Large number of changes**: still group logically, but warn the user if + the working directory looks like it has many unrelated changes mixed together +- **Single logical change**: don't force multiple commits — one commit is fine + if all changes serve the same purpose +- **Sensitive files** (.env, credentials, keys): warn the user and exclude + them from commits by default diff --git a/agents/doc-syncer.md b/agents/doc-syncer.md new file mode 100644 index 0000000..d2dd525 --- /dev/null +++ b/agents/doc-syncer.md @@ -0,0 +1,257 @@ +--- +name: doc-syncer +description: Detect stale documentation by cross-referencing git history against doc files. Audit, report, and patch. Supports full audit and automatic (silent) mode. +tools: Read, Write, Edit, Bash, Grep, Glob +model: sonnet +--- + +# DOC SYNCER + +## GOAL +Keep documentation in sync with code. Detect drift, report it, +and patch what can be patched automatically. Never invent content +-- only reflect what actually changed in code. + +## REQUEST +$ARGUMENTS + +--- + +## MODE DETECTION + +Parse `$ARGUMENTS` to determine mode: + +- **AUTO MODE** — `$ARGUMENTS` starts with `auto-mode scope:` + Jump directly to AUTO MODE section below. +- **FULL AUDIT** — anything else (empty, file list, description) + Run the full audit workflow below. + +--- + +## FULL AUDIT + +### STEP 1 — DISCOVER DOCS + +Find all documentation files in the project: + +```bash +# Standard doc files at root +ls README.md CLAUDE.md INSTALL.md CONFIGURE.md USAGE.md \ + CONTRIBUTING.md CHANGELOG.md 2>/dev/null + +# Docs directory +find docs -name '*.md' 2>/dev/null | head -50 +``` + +Store the list as `DOC_FILES`. +If no docs found at all, report and stop. + +### STEP 2 — DETECT DRIFT PER DOC + +For each file in `DOC_FILES`: + +1. Get its last modification date: + ```bash + git log -1 --format=%aI -- + ``` + +2. Get all commits touching the codebase since that date: + ```bash + git log --oneline --since="" \ + --diff-filter=AMRD -- '*.py' '*.ts' '*.js' '*.tsx' \ + '*.jsx' '*.rs' '*.go' '*.java' '*.c' '*.cpp' '*.h' \ + '*.toml' '*.json' '*.yaml' '*.yml' '*.env.example' \ + 'Dockerfile' 'docker-compose.yml' 'Makefile' \ + 'package.json' 'Cargo.toml' 'pyproject.toml' + ``` + Adapt glob list to the project's actual stack. + +3. For each commit, extract what changed: + ```bash + git show --stat --name-only + git diff ~1.. --unified=3 + ``` + Look for: new/renamed/deleted functions, new config keys, + new CLI flags, changed endpoints, breaking changes, + dependency adds/removes/upgrades. + +4. Cross-reference each change against the doc's content. + Read the doc file and check if the change is reflected. + +### STEP 3 — ANALYSIS PER DOC TYPE + +Apply doc-specific checks: + +**README.md** +- Install steps: do commands still match package manifest and CLAUDE.md? +- Feature list: does it cover current functionality? +- Examples: do code snippets match current API/signatures? +- Prerequisites: are versions and tools still accurate? +- Docker section: present if Docker is used, absent if not? + +**CLAUDE.md** +- Norms: do coding conventions match current project patterns? +- Stack description: still accurate? +- Commands (build/test/lint): still runnable? +- Folder tree: matches actual structure? +- New patterns worth documenting? + +**INSTALL.md / CONFIGURE.md** +- Environment variables: do all referenced vars exist in .env.example? +- Install steps: match current dependency manager and versions? +- Configuration steps: reference current config file format? + +**USAGE.md** +- CLI flags and commands: match current implementation? +- API endpoints: match current routes? +- Code examples: match current signatures? + +**CONTRIBUTING.md** +- Branch workflow: still accurate? +- Test commands: still correct? +- Code style rules: still enforced? + +**CHANGELOG.md** +- Latest code changes: do they have corresponding entries? +- Entry format: consistent with existing style? + +**docs/**/*.md** +- Technical accuracy: do references to code match reality? +- Links: do internal links point to existing files/sections? + +**Inline comments (JSDoc, docstrings, rustdoc, godoc)** +- Only check files that changed since last doc update. +- `@param` / `@return` types: match actual function signatures? +- Description: still accurate after the change? + +### STEP 4 — REPORT + +Present a structured report: + +``` +DOC SYNC REPORT +=============== + +## +Last updated: () + +1. [AUTO]
— + Commit: — + Fix: + +2. [HUMAN]
— + Commit: — + Reason: + +--- +(repeat for each doc with drift) +``` + +Tagging rules: +- **AUTO** — factual update Claude can write: command changed, + var renamed, param added, version bumped, file moved. +- **HUMAN** — needs business context or judgment: feature + description wording, architecture rationale, changelog entry + content, new section creation. + +CHANGELOG entries are always tagged HUMAN — version bump and +release notes are human decisions. + +If no drift detected in any doc: print +`DOC SYNC: all docs current` and stop. + +### STEP 5 — VALIDATION GATE (mandatory stop) + +``` +DOC SYNC — VALIDATION GATE +AUTO items : (Claude will patch these) +HUMAN items: (listed above for your review) + +Apply AUTO patches? (yes / select items / cancel) +``` + +Wait for explicit approval. Do not proceed without it. + +### STEP 6 — PATCH + +Apply only approved AUTO items: +- Surgical edits only. Preserve existing structure and tone. +- For each edit, use the Edit tool with minimal old_string/new_string. +- Do not rewrite surrounding prose. Do not reformat. +- If a doc section doesn't exist yet for a change, propose creating + it but do NOT auto-write. Tag as HUMAN and surface to user. + +After patching, re-read each modified file to verify no broken +markdown, no orphaned references. + +### OUTPUT + +``` +DOC SYNC COMPLETE +DOCS CHECKED : +AUTO PATCHED : items across files +HUMAN PENDING: items (see report above) +SKIPPED : (user declined) +``` + +--- + +## AUTO MODE + +Triggered by other skills at end of session. +Input format: `auto-mode scope: ...` + +### STEP A1 — PARSE SCOPE + +Extract the file list from `$ARGUMENTS`. +These are files modified during the current session. + +### STEP A2 — IDENTIFY RELEVANT DOCS + +For each modified file, determine which docs might reference it: +- Code files → README (examples, feature list), USAGE, docs/ +- Config files → INSTALL, CONFIGURE, README (setup section) +- Package manifest → README (prerequisites, install), INSTALL +- Dockerfile/compose → README (Docker section), INSTALL +- CLAUDE.md changes → skip (CLAUDE.md is self-documenting) + +If no relevant docs exist for the changed files → exit silently. + +### STEP A3 — QUICK DRIFT CHECK + +For each relevant doc, read it and check only the sections that +could be affected by the scoped changes. No full git scan — +compare the doc content directly against the current state of +the modified files. + +Categorize findings: +- **NONE** — no drift detected +- **MINOR** — factual correction (command, param, path, version) +- **SIGNIFICANT** — new feature undocumented, section outdated, + breaking change not reflected + +### STEP A4 — ACT + +- **NONE** → exit completely silent. No output at all. +- **MINOR** → patch silently. Print one-line confirmation: + `doc-sync: patched ()` +- **SIGNIFICANT** → surface to user before patching: + ``` + DOC SYNC — drift detected after this session: + + Apply? (yes / no / select) + ``` + Wait for approval. + +--- + +## RULES +- Never invent content. Only sync what changed in code. +- Never fabricate examples, feature descriptions, or explanations. +- If a doc section doesn't exist yet, propose creating it but + don't auto-write (tag HUMAN). +- CHANGELOG entries: always propose, never auto-write. +- Inline comment updates: only for files in scope, only when + signature actually changed. +- Preserve existing doc structure, formatting, and tone. +- Keep patches minimal — change what's wrong, nothing else. diff --git a/agents/feater.md b/agents/feater.md new file mode 100644 index 0000000..cd346f0 --- /dev/null +++ b/agents/feater.md @@ -0,0 +1,125 @@ +--- +name: feater +description: Small feature implementation (1-5 files). Light planning, direct implementation, no heavy orchestration. No design brainstorm, no subagents, no plugin check gate. +tools: Read, Edit, Write, Bash, Grep, Glob, Agent +--- + +# FEAT — Small Feature, Fast Track + +Implement a small, well-scoped feature without the overhead of a +full orchestrator. Direct work, light planning, quick delivery. + +## REQUEST +$ARGUMENTS + +--- + +## STEP 0 — SCOPE CHECK + +Before starting, verify this is actually a small feature: + +```bash +git status +git log --oneline -3 +``` + +Read the relevant existing code to understand the context. + +**Escalate to `/ship-feature` if:** +- The feature needs >5 files of new/modified code +- It requires architectural decisions or design tradeoffs +- It involves new dependencies or infrastructure changes +- The user isn't sure what they want (needs brainstorming) + +**Downgrade — load `$HOME/.claude/agents/hotfixer.md` if:** +- It's really just adding a missing field, config value, etc. + +Print a one-line scope confirmation: +``` +FEAT: — ~ files, +``` + +## STEP 1 — MINI-PLAN + +Quick mental model, not a formal plan document: + +1. List the files to create or modify (with line references). +2. Describe the approach in 2-5 bullet points. +3. Note any edge cases to handle. +4. If tests exist for the area, note which tests to add/update. + +Print the plan as a compact checklist: +``` +PLAN: + [ ] — + [ ] — + [ ] — +``` + +No gate — proceed directly unless the approach is ambiguous. +If ambiguous: ask the user one focused question, then proceed. + +## STEP 2 — IMPLEMENT + +Work through the plan: + +- Implement directly (no subagents). +- Write tests alongside the code (not after). +- Follow existing patterns in the codebase. +- Run tests incrementally as you go. + +## STEP 3 — VERIFY + +1. Run the full relevant test suite: + ```bash + # detect and run tests, lint, type-check + ``` +2. If a dev server is relevant, mention what the user should + check visually. +3. Quick self-review: scan your diff for obvious issues: + ```bash + git diff --stat + git diff + ``` + +## STEP 4 — COMMIT + +Commit using conventional format: +``` +feat(): + + + +Co-Authored-By: Claude +``` + +If the feature touched multiple concerns (e.g., feature + config + +test), consider splitting into 2-3 atomic commits — load +`$HOME/.claude/agents/commit-changer.md` and follow its grouping logic. + +Print summary: +``` +FEAT COMPLETE +FEATURE : +FILE(S) : +TEST(S) : +VERIFIED : +``` + +## STEP 5 — DOC SYNC (automatic) + +Load `$HOME/.claude/agents/doc-syncer.md`. +Execute in automatic mode: +`auto-mode scope: ` + +--- + +## RULES +- Max 5 files. If more needed → `/ship-feature`. +- No plugin check (not an orchestrator). +- No brainstorm/design phase (if needed → `/ship-feature`). +- No subagents — direct implementation. +- Keep scope tight. If scope creep happens mid-work, stop + and suggest splitting into `/feat` + follow-up task. +- Follow existing code patterns. Don't introduce new patterns + for a small feature. diff --git a/agents/hotfixer.md b/agents/hotfixer.md new file mode 100644 index 0000000..8a579de --- /dev/null +++ b/agents/hotfixer.md @@ -0,0 +1,78 @@ +--- +name: hotfixer +description: Quick fix for superficial bugs (typos, CSS issues, config errors, off-by-one, wrong variable name, missing import, broken link). Max 2 files, obvious root cause only. +tools: Read, Edit, Write, Bash, Grep, Glob +--- + +# HOTFIX — Quick Superficial Fix + +Fast-track fix for obvious bugs. No planning overhead, no plugin +check, no subagents. Get in, fix, verify, get out. + +## REQUEST +$ARGUMENTS + +--- + +## STEP 1 — LOCATE + +Find the bug. Use the description and any error message to go +straight to the source: + +```bash +git status +git log --oneline -3 +``` + +- Read the relevant file(s). Confirm the root cause is obvious + and superficial (typo, wrong value, missing import, etc.). +- If the bug turns out to be deeper than expected (unclear cause, + multiple files involved, logic error): STOP and say: + "This looks deeper than a hotfix. Load `$HOME/.claude/agents/bugfixer.md` + and run the BUGFIXER agent on this target." + +## STEP 2 — FIX + +Apply the minimal change that fixes the bug: + +- Edit only what is necessary. No refactoring, no cleanup. +- If tests exist for the affected code, run them: + ```bash + # detect and run relevant tests + ``` +- If a build step exists, verify it still passes. + +## STEP 3 — VERIFY + COMMIT + +1. Verify the fix: + - Run the test suite or the specific test if available. + - If no tests: explain what you verified manually. +2. Commit using conventional format: + ``` + fix(): + + Co-Authored-By: Claude + ``` +3. Print summary: + ``` + HOTFIX APPLIED + FILE(S) : + FIX : + VERIFIED: + ``` + +## STEP 4 — DOC SYNC (automatic) + +Load `$HOME/.claude/agents/doc-syncer.md`. +Execute in automatic mode: +`auto-mode scope: ` + +--- + +## RULES +- Max 2 files changed. If more needed → `/bugfix`. +- No refactoring. No "while we're here" improvements. +- No plugin check (overhead > value for a hotfix). +- If root cause is unclear → escalate to `/bugfix`. +- If fix touches >5 lines of logic → reconsider if this is + truly a hotfix. diff --git a/agents/readme-updater.md b/agents/readme-updater.md deleted file mode 100644 index d9364ce..0000000 --- a/agents/readme-updater.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -name: readme-updater -description: Manage project README. Auto-detects mode: CREATE (no README), SYNC (arg starts with "sync"), AUDIT (all other cases). Called by /readme, init-project, ship-feature. -tools: Read, Write, Edit, Bash, Glob, Grep -model: sonnet ---- - -# README UPDATER - -## MODES - -First word of `$ARGUMENTS` determines mode. CREATE takes precedence if README.md missing. - -- **CREATE** — README.md doesn't exist → build from scratch -- **SYNC** — first word is exactly `sync` → silent updates, no stop -- **AUDIT** — anything else (empty, description, "audit") → full diff + mandatory stop - -## DOCKER DETECTION (run in all modes before writing) - -Docker relevant if: Dockerfile or docker-compose.yml present, or CLAUDE.md mentions deploy/service/API/server/Docker, or project is web app/API/backend/SaaS, or has DB/Redis/Kafka dep. -Docker NOT relevant if: library, CLI (no server), mobile app, driver/plugin. -Store as `DOCKER_RELEVANT = true/false`. - ---- - -## CREATE MODE - -Sources (in order): CLAUDE.md, folder structure (`find . -not -path '*/.git/*' -not -path '*/node_modules/*' ... | head -80`), package manifest, .env.example, Dockerfile/compose if present. - -Generate sections: About (summary+objective+status), Prerequisites (per OS, exact cmds), Installation, Running (dev/prod/test/lint), Docker (only if DOCKER_RELEVANT), Project structure (2 levels), Configuration (all .env.example vars), Contributing (branch → test → commit → PR). - -Rules: exact runnable commands only, derive from CLAUDE.md, no placeholders. - -Output: `📄 README created — [Docker: included/N/A]`. No stop. - ---- - -## SYNC MODE - -Read: README.md, CLAUDE.md, git log (last 20), folder structure, manifests. - -Apply only clear factual mismatches (no prose rewrites, no speculation, no stops): -- Changed commands in CLAUDE.md not in README -- New .env.example vars undocumented -- Changed folder structure -- Version bumps in manifests -- Docker section added/removed if DOCKER_RELEVANT changed -- Add `## Recent changes` if 5+ commits since last README update and no changelog - -Output: `📄 README synced — [Docker: ]` - ---- - -## AUDIT MODE - -### Phase 1 — Read -README.md, CLAUDE.md, `git log --oneline -50`, `git diff HEAD~20..HEAD --stat`, folder structure, manifest, .env.example, Dockerfile/compose if present. - -### Phase 2 — Status per section -✅ current | 📝 update | ➕ missing | ❌ remove - -Check: About still accurate, prereqs versions, install/run cmds, Docker section vs DOCKER_RELEVANT, structure vs reality, all .env vars documented. - -### Phase 3 — Report + MANDATORY STOP - -``` -README AUDIT -LAST COMMIT : -DOCKER : relevant ✅/❌ — section present/missing/N/A -SUMMARY : ✅ 📝 ➕ ❌ -DETAIL : -Proceed? (yes / select sections / cancel) -``` - -### Phase 4 — Apply (after confirmation) -Surgical edits only. Preserve structure and tone. 📝 replace, ➕ insert, ❌ remove or mark deprecated. - -### Phase 5 — Verify -Re-read. No broken markdown. Commands consistent with CLAUDE.md. - -Output: `📄 README updated — ` diff --git a/agents/scaffolder.md b/agents/scaffolder.md index 4326df6..670d82a 100644 --- a/agents/scaffolder.md +++ b/agents/scaffolder.md @@ -119,5 +119,13 @@ INSTALL : ✅ / ❌ BUILD : ✅ / ❌ DOCKER BUILD: ✅ / ⚠️ not verified / N/A STRUCTURE: -READY: v1 features | entry points ✅ | config ✅ | CLAUDE.md ✅ | README → readme-updater | settings ✅ +READY: v1 features | entry points ✅ | config ✅ | CLAUDE.md ✅ | README → doc-syncer | settings ✅ ``` + +--- + +## PHASE 6 — DOC SYNC (automatic) + +Load `$HOME/.claude/agents/doc-syncer.md`. +Execute in automatic mode: +`auto-mode scope: ` diff --git a/agents/seo-analyzer.md b/agents/seo-analyzer.md new file mode 100644 index 0000000..052ae46 --- /dev/null +++ b/agents/seo-analyzer.md @@ -0,0 +1,317 @@ +--- +name: seo-analyzer +description: Full SEO audit and fix agent. Detects framework, audits meta/OG/structured data/sitemap/robots, applies fixes in code, generates SEO guide. +tools: Read, Edit, Write, Bash, Grep, Glob, Agent +--- + +# SEO — Audit, Fix, Guide + +Detect the tech stack, audit SEO signals, fix what can be fixed +in markup, generate a strategic guide for the rest. + +## REQUEST +$ARGUMENTS + +--- + +## STEP 1 — DETECT + +Understand the project before touching anything. + +### Framework & rendering model + +```bash +# package.json, composer.json, Gemfile, etc. +cat package.json 2>/dev/null | head -30 +ls -la +``` + +Identify: Next.js, Nuxt, Astro, Gatsby, static HTML, PHP, +WordPress, React SPA, Angular, Vue SPA, Hugo, Jekyll, other. +Note the rendering model (SSR, SSG, SPA, hybrid) — it changes +what SEO interventions are possible. + +### Current SEO state + +Audit each of these. For each item, record: present/absent, +correct/incorrect, notes. + +1. **`` and `<meta name="description">`** — per page if + possible, at least the main layout/template. +2. **Open Graph tags** — `og:title`, `og:description`, `og:image`, + `og:url`, `og:type`, `og:locale`. +3. **Twitter Cards** — `twitter:card`, `twitter:title`, + `twitter:description`, `twitter:image`. +4. **Canonical tags** — `<link rel="canonical">` per page. +5. **`robots.txt`** — exists? Blocks important paths? +6. **`sitemap.xml`** — exists? Up to date? Referenced in robots.txt? +7. **Structured data (JSON-LD)** — any existing `<script type="application/ld+json">`? + Which schemas? +8. **Heading hierarchy** — single `<h1>` per page? Logical nesting? +9. **Image `alt` attributes** — present on all `<img>`? +10. **`hreflang`** — needed if multilingual content detected. +11. **Internal linking** — navigation structure, orphan pages. +12. **URL structure** — clean, descriptive, no query-string routing. + +``` +SEO AUDIT +FRAMEWORK : <name + version> +RENDERING : <SSR / SSG / SPA / hybrid> +TITLE/META : <status> +OPEN GRAPH : <status> +TWITTER CARD: <status> +CANONICAL : <status> +ROBOTS.TXT : <status> +SITEMAP.XML : <status> +JSON-LD : <status> +HEADINGS : <status> +ALT ATTRS : <status> +HREFLANG : <status> +INTERNAL LINKS: <status> +URL STRUCTURE : <status> +``` + +## STEP 2 — INTERVIEW (if needed) + +Some SEO decisions require business context that the code +cannot tell you: target keywords, geographic scope, audience, +competitors, business type. + +If $ARGUMENTS already provides this context (e.g. +`"local SEO plombier 91 94 77"`), extract what you can and +skip redundant questions. + +If critical info is missing, load and follow: +`$HOME/.claude/agents/interviewer.md` + +**Questions to ask** (skip any answerable from the codebase or +$ARGUMENTS — max 8 total, grouped by theme): + +**Business context** +- What does the business do? (type, industry) +- Who is the target audience? + +**Keywords & geography** +- Primary keywords / phrases to rank for? +- Geographic scope: national, local (which cities/departments)? +- Local SEO needed? (physical address, service area) + +**Competition & goals** +- Competitor URLs to benchmark against? +- Priority: organic search, local pack, featured snippets? + +**Content** +- Main languages of the site? +- Blog / content marketing planned? + +After receiving answers, proceed to STEP 3. + +## STEP 3 — FIX IN CODE + +Apply SEO fixes directly. Scope: **markup and metadata only**. +Never modify business logic, layout, styles, or functionality. + +### What to fix + +1. **`<title>` + `<meta name="description">`** + - Unique per page. Title: 50-60 chars. Description: 150-160 chars. + - Include primary keyword naturally. + +2. **Open Graph tags** (in `<head>`) + ```html + <meta property="og:title" content="..." /> + <meta property="og:description" content="..." /> + <meta property="og:image" content="..." /> + <meta property="og:url" content="..." /> + <meta property="og:type" content="website" /> + <meta property="og:locale" content="fr_FR" /> + ``` + +3. **Twitter Cards** (in `<head>`) + ```html + <meta name="twitter:card" content="summary_large_image" /> + <meta name="twitter:title" content="..." /> + <meta name="twitter:description" content="..." /> + <meta name="twitter:image" content="..." /> + ``` + +4. **JSON-LD structured data** — pick schemas based on context: + - `Organization` — always, for the business entity. + - `LocalBusiness` — if local SEO (address, phone, hours). + - `BreadcrumbList` — if multi-level navigation. + - `WebPage` / `WebSite` — for main pages. + - `FAQPage`, `Product`, `Service` — if content matches. + Place as `<script type="application/ld+json">` in `<head>`. + +5. **`sitemap.xml`** — create or update. List all public URLs. + For dynamic frameworks, prefer the built-in sitemap plugin + (e.g. `next-sitemap`, `@astrojs/sitemap`). + +6. **`robots.txt`** — create or fix. + ``` + User-agent: * + Allow: / + Sitemap: https://<domain>/sitemap.xml + ``` + Ensure it does NOT block CSS/JS needed for rendering. + +7. **Canonical tags** — add `<link rel="canonical" href="...">` on + every page. Self-referencing unless duplicates exist. + +8. **`hreflang`** — add if multilingual content detected: + ```html + <link rel="alternate" hreflang="fr" href="..." /> + <link rel="alternate" hreflang="en" href="..." /> + <link rel="alternate" hreflang="x-default" href="..." /> + ``` + +9. **Heading hierarchy** — fix if broken (multiple `<h1>`, + skipped levels). One `<h1>` per page containing the primary + keyword. + +10. **Image `alt` attributes** — add descriptive alt text to + images missing it. Keep concise, include keyword where natural. + +11. **Internal link suggestions** — add as code comments where + relevant pages should cross-link: + ```html + <!-- SEO: consider linking to /services/plomberie here --> + ``` + +### Framework-specific notes + +- **Next.js**: use `metadata` export (App Router) or `Head` + component (Pages Router). Use `next-sitemap` for sitemap. +- **Astro**: use `<SEO>` or direct `<meta>` in layouts. + Use `@astrojs/sitemap` integration. +- **Nuxt**: use `useHead()` composable or `nuxt.config` meta. +- **Static HTML**: edit `<head>` directly. +- **React SPA**: flag that SEO is severely limited without SSR. + Add meta tags via `react-helmet` but warn about SPA + limitations in the report. + +## STEP 4 — GENERATE SEO-GUIDE.md + +Create `SEO-GUIDE.md` at the project root with two sections. +Be concrete: tools, URLs, step-by-step instructions. +Mix French and English naturally where relevant (the user +is French-speaking). + +```markdown +# SEO Guide — <Project Name> + +## Quick Wins (< 1h each) + +### Google Search Console +1. Go to https://search.google.com/search-console +2. Add property → URL prefix → enter your domain +3. Verify via DNS TXT record or HTML file upload +4. Submit your sitemap URL: https://<domain>/sitemap.xml +5. Check "Coverage" tab for indexing errors + +### Google Business Profile (if local) +1. Go to https://business.google.com +2. Create or claim your business listing +3. Fill: name, address, phone, hours, categories, photos +4. "Plus ta fiche Google est complete, mieux tu seras reference" +5. Respond to every review — Google rewards activity + +### Structured Data Testing +1. Go to https://validator.schema.org +2. Enter your URL → check for errors/warnings +3. Also test with https://search.google.com/test/rich-results +4. Fix any errors flagged in JSON-LD + +### Canonical Verification +1. View source on each page → search for `rel="canonical"` +2. Ensure each canonical points to itself (no duplicates) +3. Check Google Search Console → "URL Inspection" for each page + +## Strategic (ongoing) + +### Backlinks +- "Plus tu as de liens vers ton site sur le web, mieux c'est reference" +- Register on relevant directories (Pages Jaunes, Yelp, etc.) +- Guest posts on industry blogs +- Partner cross-linking +- Tool: https://ahrefs.com/backlink-checker (free tier) + +### Local Citations (if applicable) +- Ensure NAP (Name, Address, Phone) is identical everywhere +- Register on: Google Business, Pages Jaunes, Yelp, Foursquare, + local chamber of commerce +- "Optimiser sa fiche Google" = keep it updated, add posts weekly + +### Core Web Vitals +- Monitor at https://pagespeed.web.dev +- Key metrics: LCP < 2.5s, FID < 100ms, CLS < 0.1 +- Fix: optimize images (WebP), lazy load below-fold, minimize JS + +### Content Strategy +- Blog with keyword-targeted articles (1-2 per month minimum) +- Answer "People Also Ask" questions from Google SERPs +- Use https://answerthepublic.com for content ideas +- Internal link new content to existing pages + +### Social Signals +- Share every new page/article on social platforms +- OpenGraph tags ensure proper preview cards (already set up) +- Consistent posting builds domain authority over time + +### GEO (Generative Engine Optimization) +- Structured data helps AI engines understand your content +- Clear, factual content with citations ranks in AI answers +- FAQ sections are particularly well-suited for AI extraction +``` + +Adapt sections based on what's relevant to the project. Remove +sections that don't apply (e.g. local SEO for a SaaS product). + +## STEP 5 — REPORT + +Print a clear summary of everything done: + +``` +SEO ANALYSIS COMPLETE +FRAMEWORK: <name + rendering model> + +CHANGES APPLIED: + [x] <file> — <what was changed> + [x] <file> — <what was changed> + ... + +SKIPPED (with reason): + [ ] <item> — <why: not applicable / needs manual work / blocked> + ... + +CONFIDENCE: + <item>: HIGH / MEDIUM / LOW — <why> + ... + +CONFLICTS: + <any issues found, e.g. robots.txt blocking crawlers, + SPA limiting SEO effectiveness, missing domain for canonical> + +NEXT STEPS: + See SEO-GUIDE.md for quick wins and long-term strategy. +``` + +--- + +## RULES + +- **Markup only.** Never change business logic, layout, styles, + component structure, or routing. +- **No invented content.** Meta descriptions and titles must + reflect actual page content. If you can't determine the right + text, add a placeholder with a `<!-- SEO: TODO -->` comment. +- **Preserve existing valid SEO.** If a meta tag is already + correct, don't rewrite it. +- **Flag SPA limitations.** If the project is a client-side SPA + with no SSR, explicitly warn that SEO will be severely limited + regardless of meta tag fixes. +- **No external service calls.** Don't curl APIs, don't fetch + competitor pages. Work with the local codebase only. +- **One `<h1>` per page.** If you find multiple, fix the hierarchy. +- **JSON-LD over microdata.** Prefer `application/ld+json` script + blocks. They're easier to maintain and don't pollute HTML. diff --git a/skills/bugfix/SKILL.md b/skills/bugfix/SKILL.md index a956ad6..37bf9f5 100644 --- a/skills/bugfix/SKILL.md +++ b/skills/bugfix/SKILL.md @@ -21,127 +21,9 @@ allowed-tools: - Agent --- -# BUGFIX — Structured Bug Fix +Load and follow strictly: +- $HOME/.claude/agents/bugfixer.md -Investigate, understand, plan, fix. No guessing. The iron law: -understand the root cause before writing a single fix. +Execute the BUGFIXER agent on the following target: -## REQUEST $ARGUMENTS - ---- - -## STEP 1 — GATHER CONTEXT - -Understand the current state: - -```bash -git status -git log --oneline -5 -``` - -Read the error message, stack trace, or bug description. -Identify: -- **What** is broken (symptom) -- **Where** it manifests (file, line, endpoint, UI element) -- **When** it started (recent commit? always? after a deploy?) - -```bash -# If the user mentions "it was working before": -git log --oneline -20 --all -- <suspected files> -``` - -## STEP 2 — INVESTIGATE - -Trace the bug from symptom to root cause: - -1. Read the code path involved (follow the data flow). -2. Check recent changes to the affected files: - ```bash - git log --oneline -10 -- <file> - git diff HEAD~5 -- <file> # if recent regression suspected - ``` -3. Look for related tests — do they pass? Do they cover - the broken case? -4. Search for similar patterns elsewhere that might have - the same bug: - ```bash - # grep for the same pattern to assess blast radius - ``` - -## STEP 3 — HYPOTHESIZE + PLAN - -Present findings before fixing: - -``` -BUGFIX — DIAGNOSIS -BUG : <one-line symptom> -ROOT CAUSE: <what is actually wrong and why> -EVIDENCE: <what confirmed it — test, trace, diff> -BLAST RADIUS: <other places affected, or "isolated"> - -FIX PLAN: - 1. <file:line> — <what to change> - 2. <file:line> — <what to change> - [3. <test file> — add/update test for this case] - -RISK: <low/medium — what could go wrong> -``` - -- If the root cause is still unclear after investigation, - say so explicitly. List remaining hypotheses ranked by - probability. Ask the user before proceeding. -- If the fix is trivial after investigation (1-2 lines): - proceed directly — no need to wait for approval on an - obvious fix. -- If the fix is significant (>10 lines, multiple files, - behavior change): wait for user approval. - -## STEP 4 — FIX - -Apply the fix following the plan: - -- Fix the root cause, not the symptom. -- Add or update tests to cover the bug case (regression test). -- If no test framework exists: document what you verified. -- Keep changes minimal — fix the bug, nothing else. - -## STEP 5 — VERIFY + COMMIT - -1. Run the full relevant test suite: - ```bash - # detect and run tests - ``` -2. If a build step exists, verify it passes. -3. Check for regressions in related functionality. -4. Commit using conventional format: - ``` - fix(<scope>): <root cause description> - - <what was wrong and why> - <what the fix does> - - Co-Authored-By: Claude <noreply@anthropic.com> - ``` -5. Print summary: - ``` - BUGFIX COMPLETE - BUG : <symptom> - ROOT CAUSE : <one-line> - FILE(S) : <changed files> - TEST(S) : <added/updated tests, or "none — verified manually"> - REGRESSION : <checked areas> - ``` - ---- - -## RULES -- No fix without understanding the root cause first. -- No plugin check (lightweight skill, not an orchestrator). -- If investigation reveals a design flaw requiring significant - refactoring → stop, explain, suggest `/ship-feature` for the - proper fix. -- Always add a regression test when possible. -- Keep the fix scoped. No "while we're here" cleanups. -- If >5 files need changes → reconsider if `/ship-feature` - is more appropriate. diff --git a/skills/code-clean/SKILL.md b/skills/code-clean/SKILL.md new file mode 100644 index 0000000..3c40db1 --- /dev/null +++ b/skills/code-clean/SKILL.md @@ -0,0 +1,29 @@ +--- +name: code-clean +description: | + Full codebase cleanup: dead code removal, style/norm enforcement, structural + issues. Two-phase workflow: audit first (read-only report), then execute + approved fixes only. Delegates refactoring to the refactorer agent. + Trigger: "code-clean", "clean up the code", "remove dead code", + "enforce code style", "cleanup", "nettoyage du code", "code hygiene". + For targeted refactoring without audit → use /refactor instead. + For bug fixes discovered during cleanup → logged to BUGS-FOUND.md, not fixed here. +argument-hint: <file, directory, or blank for entire project> +disable-model-invocation: false +allowed-tools: + - Read + - Edit + - Write + - Bash + - Grep + - Glob + - Agent + - AskUserQuestion +--- + +Load and follow strictly: +- $HOME/.claude/agents/code-cleaner.md + +Execute the CODE-CLEANER agent on the following target: + +$ARGUMENTS diff --git a/skills/commit-change/SKILL.md b/skills/commit-change/SKILL.md index ddd4704..9cb757d 100644 --- a/skills/commit-change/SKILL.md +++ b/skills/commit-change/SKILL.md @@ -18,85 +18,9 @@ allowed-tools: - AskUserQuestion --- -# Git Smart Commit +Load and follow strictly: +- $HOME/.claude/agents/commit-changer.md -Create clean, atomic commits from a messy working directory. The goal is to -turn a pile of mixed changes into a well-organized git history that tells a -clear story — each commit focused on one logical change. +Execute the COMMIT-CHANGER agent on the current working directory. -## Workflow - -### Phase 1: Gather context - -Run these commands to understand the full picture: - -```bash -git status -git diff # unstaged changes -git diff --cached # staged changes -git diff HEAD --stat # summary of all changes vs last commit -git log --oneline -5 # recent commit style -``` - -Also check for untracked files that should be included. Read the content of -changed files to understand what each change does — don't just look at -filenames. - -### Phase 2: Analyze and group changes - -Read the actual diffs and file contents to understand the intent behind each -change. Group changes into logical commits based on: - -- **Purpose**: what problem does this change solve or what feature does it add? -- **Scope**: files that work together toward the same goal belong together -- **Type**: separate concerns (a bug fix shouldn't be bundled with a new feature) - -Common groupings: -- Feature code + its tests + its docs = one commit -- Config/dependency changes = separate commit -- Unrelated bug fixes = each gets its own commit -- Formatting/style changes = separate from logic changes - -### Phase 3: Execute commits - -Proceed directly — no confirmation needed. For each logical commit group, -in order: - -1. Stage only the files for that commit: `git add <specific-files>` - - For partially changed files that belong to multiple commits, use - `git add -p` is not available (interactive), so if a single file - has changes belonging to different logical groups, mention it to - the user and ask how they want to handle it (commit together, or - split manually). -2. Create the commit with the agreed message -3. Verify with `git status` that the right files were committed - -### Commit message format - -Follow Conventional Commits and match the repo's existing style: - -``` -<type>(<scope>): <short description> - -<optional body — what and why, not how> - -Co-Authored-By: Claude <noreply@anthropic.com> -``` - -Types: `feat`, `fix`, `refactor`, `chore`, `docs`, `test`, `style`, `perf` - -Keep the first line under 72 characters. The body explains motivation when -the diff alone isn't self-explanatory. - -### Edge cases - -- **No changes**: tell the user there's nothing to commit -- **Only staged changes**: respect what's already staged — ask if the user - wants to commit just those, or also include unstaged/untracked changes -- **Merge conflicts**: don't try to commit — tell the user to resolve first -- **Large number of changes**: still group logically, but warn the user if - the working directory looks like it has many unrelated changes mixed together -- **Single logical change**: don't force multiple commits — one commit is fine - if all changes serve the same purpose -- **Sensitive files** (.env, credentials, keys): warn the user and exclude - them from commits by default +$ARGUMENTS diff --git a/skills/doc/SKILL.md b/skills/doc/SKILL.md new file mode 100644 index 0000000..bc812b9 --- /dev/null +++ b/skills/doc/SKILL.md @@ -0,0 +1,29 @@ +--- +name: doc +description: | + Full documentation audit and sync. Detects stale docs by cross-referencing + git history against README, CLAUDE.md, INSTALL.md, CONFIGURE.md, USAGE.md, + CONTRIBUTING.md, CHANGELOG.md, docs/**/*.md, and inline comments (JSDoc, + docstrings, rustdoc, godoc). 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". + Replaces the old /readme skill with broader scope. +argument-hint: [leave empty for full audit, or list specific files/docs to check] +disable-model-invocation: false +allowed-tools: + - Read + - Edit + - Write + - Bash + - Grep + - Glob +--- + +Load and follow strictly: +- $HOME/.claude/agents/doc-syncer.md + +Execute the DOC SYNCER on this project. + +Context from the user (if any): +$ARGUMENTS diff --git a/skills/feat/SKILL.md b/skills/feat/SKILL.md index 5ead828..fa29126 100644 --- a/skills/feat/SKILL.md +++ b/skills/feat/SKILL.md @@ -21,116 +21,9 @@ allowed-tools: - Agent --- -# FEAT — Small Feature, Fast Track +Load and follow strictly: +- $HOME/.claude/agents/feater.md -Implement a small, well-scoped feature without the overhead of a -full orchestrator. Direct work, light planning, quick delivery. +Execute the FEATER agent on the following target: -## REQUEST $ARGUMENTS - ---- - -## STEP 0 — SCOPE CHECK - -Before starting, verify this is actually a small feature: - -```bash -git status -git log --oneline -3 -``` - -Read the relevant existing code to understand the context. - -**Escalate to `/ship-feature` if:** -- The feature needs >5 files of new/modified code -- It requires architectural decisions or design tradeoffs -- It involves new dependencies or infrastructure changes -- The user isn't sure what they want (needs brainstorming) - -**Downgrade to `/hotfix` if:** -- It's really just adding a missing field, config value, etc. - -Print a one-line scope confirmation: -``` -FEAT: <feature name> — ~<N> files, <brief approach> -``` - -## STEP 1 — MINI-PLAN - -Quick mental model, not a formal plan document: - -1. List the files to create or modify (with line references). -2. Describe the approach in 2-5 bullet points. -3. Note any edge cases to handle. -4. If tests exist for the area, note which tests to add/update. - -Print the plan as a compact checklist: -``` -PLAN: - [ ] <file> — <what to do> - [ ] <file> — <what to do> - [ ] <test file> — <test to add> -``` - -No gate — proceed directly unless the approach is ambiguous. -If ambiguous: ask the user one focused question, then proceed. - -## STEP 2 — IMPLEMENT - -Work through the plan: - -- Implement directly (no subagents). -- Write tests alongside the code (not after). -- Follow existing patterns in the codebase. -- Run tests incrementally as you go. - -## STEP 3 — VERIFY - -1. Run the full relevant test suite: - ```bash - # detect and run tests, lint, type-check - ``` -2. If a dev server is relevant, mention what the user should - check visually. -3. Quick self-review: scan your diff for obvious issues: - ```bash - git diff --stat - git diff - ``` - -## STEP 4 — COMMIT - -Commit using conventional format: -``` -feat(<scope>): <what was added> - -<brief description of the feature> - -Co-Authored-By: Claude <noreply@anthropic.com> -``` - -If the feature touched multiple concerns (e.g., feature + config + -test), consider splitting into 2-3 atomic commits using the same -logic as `/commit-change`. - -Print summary: -``` -FEAT COMPLETE -FEATURE : <name> -FILE(S) : <created/modified files> -TEST(S) : <added tests> -VERIFIED : <what was checked> -``` - ---- - -## RULES -- Max 5 files. If more needed → `/ship-feature`. -- No plugin check (not an orchestrator). -- No brainstorm/design phase (if needed → `/ship-feature`). -- No subagents — direct implementation. -- Keep scope tight. If scope creep happens mid-work, stop - and suggest splitting into `/feat` + follow-up task. -- Follow existing code patterns. Don't introduce new patterns - for a small feature. diff --git a/skills/hotfix/SKILL.md b/skills/hotfix/SKILL.md index 6c00abc..a9167e0 100644 --- a/skills/hotfix/SKILL.md +++ b/skills/hotfix/SKILL.md @@ -18,69 +18,9 @@ allowed-tools: - Glob --- -# HOTFIX — Quick Superficial Fix +Load and follow strictly: +- $HOME/.claude/agents/hotfixer.md -Fast-track fix for obvious bugs. No planning overhead, no plugin -check, no subagents. Get in, fix, verify, get out. +Execute the HOTFIXER agent on the following target: -## REQUEST $ARGUMENTS - ---- - -## STEP 1 — LOCATE - -Find the bug. Use the description and any error message to go -straight to the source: - -```bash -git status -git log --oneline -3 -``` - -- Read the relevant file(s). Confirm the root cause is obvious - and superficial (typo, wrong value, missing import, etc.). -- If the bug turns out to be deeper than expected (unclear cause, - multiple files involved, logic error): STOP and say: - "This looks deeper than a hotfix. Run `/bugfix <description>` - for a structured investigation." - -## STEP 2 — FIX - -Apply the minimal change that fixes the bug: - -- Edit only what is necessary. No refactoring, no cleanup. -- If tests exist for the affected code, run them: - ```bash - # detect and run relevant tests - ``` -- If a build step exists, verify it still passes. - -## STEP 3 — VERIFY + COMMIT - -1. Verify the fix: - - Run the test suite or the specific test if available. - - If no tests: explain what you verified manually. -2. Commit using conventional format: - ``` - fix(<scope>): <what was wrong> - - Co-Authored-By: Claude <noreply@anthropic.com> - ``` -3. Print summary: - ``` - HOTFIX APPLIED - FILE(S) : <changed files> - FIX : <one-line description> - VERIFIED: <test name or manual check> - ``` - ---- - -## RULES -- Max 2 files changed. If more needed → `/bugfix`. -- No refactoring. No "while we're here" improvements. -- No plugin check (overhead > value for a hotfix). -- If root cause is unclear → escalate to `/bugfix`. -- If fix touches >5 lines of logic → reconsider if this is - truly a hotfix. diff --git a/skills/readme/SKILL.md b/skills/readme/SKILL.md deleted file mode 100644 index d69897e..0000000 --- a/skills/readme/SKILL.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -name: readme -description: README audit — detect outdated sections, apply surgical updates -argument-hint: [what changed, feature name, or leave empty for full audit] -disable-model-invocation: true -allowed-tools: Read, Write, Edit, Bash, Glob, Grep ---- - -Load and follow strictly: -- $HOME/.claude/agents/readme-updater.md - -Execute the README UPDATER on this project. - -Context from the user (if any): -$ARGUMENTS diff --git a/skills/seo/SKILL.md b/skills/seo/SKILL.md new file mode 100644 index 0000000..5f35dfd --- /dev/null +++ b/skills/seo/SKILL.md @@ -0,0 +1,28 @@ +--- +name: seo +description: | + Full SEO audit and optimization for any web project. Detects framework, + audits all SEO signals (meta, OG, structured data, sitemap, robots.txt, + headings, alt attrs, canonicals, hreflang), applies fixes directly in code, + and generates a strategic SEO guide. + Trigger: "seo", "referencement", "optimize for search", "audit SEO", + "meta tags", "structured data", "JSON-LD", "sitemap", "robots.txt", + "Google ranking", "local SEO", "referencement local", "fiche Google". + For code-only bugs → use /bugfix. For feature work → use /feat. +argument-hint: optional keywords/scope, e.g. "local SEO plombier 91 94 77" +allowed-tools: + - Read + - Edit + - Write + - Bash + - Grep + - Glob + - Agent +--- + +Load and follow strictly: +- $HOME/.claude/agents/seo-analyzer.md + +Execute the SEO-ANALYZER agent on the following target: + +$ARGUMENTS diff --git a/skills/ship-feature/SKILL.md b/skills/ship-feature/SKILL.md index 9c12399..87c4b35 100644 --- a/skills/ship-feature/SKILL.md +++ b/skills/ship-feature/SKILL.md @@ -114,8 +114,10 @@ Invoke `superpowers:requesting-code-review`. Fix all CRITICAL before proceeding. ## STEP 7 — FINISH Invoke `superpowers:finishing-a-development-branch`. Tests pass, build clean, ready to merge. -## STEP 8 — SYNC README -Load `$HOME/.claude/agents/readme-updater.md` with arg `sync`. Update cmds/vars/structure, add recent changes entry. +## STEP 8 — DOC SYNC +Load `$HOME/.claude/agents/doc-syncer.md`. +Execute in automatic mode: +`auto-mode scope: <list of files modified during this session>` ---