Skip to content

heymegabyte/agent-skills / 09-brand-and-content-system

brand-and-content-system

Verified

Extract real brands (Wayback for rebuilds). Copy system, headline/CTA rules, trust surfaces, legal pages, SEO+structured data, anti-AI-slop, microcopy, DESIGN.md, W3C DTCG tokens, pSEO 5 types, GEO/AI search.

FileKindSize
SKILL.mdskill md12.2 KB
ai-search-geo.mdmarkdown4.0 KB
build-breaking-rules.mdmarkdown21.0 KB
documentation-and-codebase-hygiene.mdmarkdown3.1 KB
email-templates.mdmarkdown6.0 KB
grammar-audit.mdmarkdown3.7 KB
per-route-metadata.mdmarkdown6.8 KB
seo-and-keywords.mdmarkdown6.3 KB
social-automation.mdmarkdown5.8 KB

documentation-and-codebase-hygiene.md

View on GitHub
---
name: "Documentation and Codebase Hygiene"
version: "1.1.0"
updated: "2026-04-23"
description: "Keep codebase in sync: README (install.doctor template, shields.io badges), CLAUDE.md, MEMORY.md, JSDoc/TypeDoc, stale code removal. Stale docs = bugs. Runs continuously."
---

# Documentation and Codebase Hygiene

Stale docs are bugs. Code, comments, markdown, and configs stay in sync at all times.

## README.md (install.doctor Template)

```markdown
<div align="center">
  <img src=".config/assets/logo.png" width="148" height="148" />
  <h1>Project Name</h1>
  <p><em>One-line description</em></p>
</div>

<!-- Badges (for-the-badge style) -->
[![Build](https://img.shields.io/github/actions/workflow/status/ORG/REPO/deploy.yml?style=for-the-badge)]()
[![Website](https://img.shields.io/website?url=https%3A%2F%2FDOMAIN&style=for-the-badge)]()
[![Cloudflare](https://img.shields.io/badge/Cloudflare-Workers-F38020?style=for-the-badge&logo=cloudflare)]()

<!-- Dividers between sections -->
<img src="https://gitlab.com/megabyte-labs/assets/-/raw/master/png/aqua-divider.png" width="100%" />

## Overview | ## Features | ## Quick Start | ## Tech Stack | ## Documentation | ## License
```

## CLAUDE.md Standards

- **Required sections:** What This Is, Tech Stack, Project Structure, Key Patterns, Commands, Current State
- Keep <200 lines
- Update after every session

## Code Comments

### When

- WHY (not what)
- Complex algorithms
- Workarounds with issue links
- API contracts
- Security decisions

### Never

- Restating code
- TODO without issue link
- Commented-out code (git has history)

```typescript
// GOOD: Clerk webhook sends display_name, but our DB schema uses name
user.name = clerkUser.display_name;

// GOOD: Rate limit: 10 req/60s per IP (CF KV-based). See: https://...
```

## JSDoc

Every exported function — `@param`, `@returns`, `@example`, `@see` (with URL). Descriptions <2 sentences.

## Stale Code Removal

### Remove

- Commented-out code
- Unused imports
- Dead functions
- TODO >30 days without issue
- `console.log` debug
- Old applied migrations

### Keep

- User-written code
- Documented workarounds with links
- Active feature flags

**Rule:** Never remove user code without asking. Use `npx knip` for unused exports.

## Sync Protocol

- **Every session** — README matches reality, CLAUDE.md current, remove deleted file refs
- **Feature completion** — update README features, CLAUDE.md patterns, relevant skills
- **Refactor** — update all docs, rename refs, grep for old names, update project structure

## Naming Conventions

- **Files** — kebab-case
- **Functions** — camelCase
- **Types** — PascalCase
- **Constants** — SCREAMING_SNAKE
- **DB columns** — snake_case

## Quality Checks

```bash
grep -rn "TODO\|FIXME" src/ --include="*.ts" | head -20
grep -rn "console\.log" src/ --include="*.ts" | grep -v "// keep"
npx knip --reporter compact
```

## Ownership

- **Owns:** README template, CLAUDE.md standards, code comment quality, JSDoc, stale code removal, cross-project sync, AI-readable formatting
- **Never owns:** Content writing (→09, 22), implementation (→06), testing (→07), deployment (→08)
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall