AgentSkillsCN

write-claude-md

使用 GitHub 发布新版本，合理标注版本号、撰写发布说明，并可选添加构建产物。涵盖语义化版本控制、变更日志生成，以及 GitHub CLI 的使用。

SKILL.md
--- frontmatter
name: write-claude-md
description: >
  Create an effective CLAUDE.md file that provides project-specific
  instructions to AI coding assistants. Covers structure, common
  sections, do/don't patterns, and integration with MCP servers
  and agent definitions.
license: MIT
allowed-tools: Read Write Edit Bash Grep Glob
metadata:
  author: Philipp Thoss
  version: "1.0"
  domain: general
  complexity: basic
  language: multi
  tags: claude-md, ai-assistant, project-config, documentation

Write CLAUDE.md

Create a CLAUDE.md file that gives AI assistants effective project-specific context.

When to Use

  • •Starting a new project where AI assistants will be used
  • •Improving AI assistant behavior on an existing project
  • •Documenting project conventions, workflows, and constraints
  • •Integrating MCP servers or agent definitions into a project

Inputs

  • •Required: Project type and technology stack
  • •Required: Key conventions and constraints
  • •Optional: MCP server configurations
  • •Optional: Author and contributor information
  • •Optional: Security and confidentiality requirements

Procedure

Step 1: Create Basic CLAUDE.md

Place CLAUDE.md in the project root:

markdown
# Project Name

Brief description of what this project is and its purpose.

## Quick Start

Essential commands for working on this project:

```bash
# Install dependencies
npm install  # or renv::restore() for R

# Run tests
npm test     # or devtools::test() for R

# Build
npm run build  # or devtools::check() for R

Architecture

Key architectural decisions and patterns used in this project.

Conventions

  • •Always use descriptive variable names
  • •Follow [language-specific style guide]
  • •Write tests for all new functionality
code
### Step 2: Add Technology-Specific Sections

**For R packages**:

```markdown
## Development Workflow

```r
devtools::load_all()    # Load for development
devtools::document()    # Regenerate docs
devtools::test()        # Run tests
devtools::check()       # Full package check

Package Structure

  • •R/ - Source code (one function per file)
  • •tests/testthat/ - Tests mirror R/ structure
  • •vignettes/ - Long-form documentation
  • •man/ - Generated by roxygen2 (do not edit manually)

Critical Files (Do Not Delete)

  • •.Rprofile - Session configuration
  • •.Renviron - Environment variables (git-ignored)
  • •renv.lock - Locked dependencies
code
**For Node.js/TypeScript**:

```markdown
## Stack

- Next.js 15 with App Router
- TypeScript strict mode
- Tailwind CSS for styling
- Vercel for deployment

## Conventions

- Use `@/` import alias for src/ directory
- Server Components by default, `"use client"` only when needed
- API routes in `src/app/api/`

Step 3: Add MCP Server Information

markdown
## Available MCP Servers

### r-mcptools (R Integration)
- **Purpose**: Connect to R/RStudio sessions
- **Status**: Configured
- **Configuration**: `claude mcp add r-mcptools stdio "Rscript.exe" -- -e "mcptools::mcp_server()"`

### hf-mcp-server (Hugging Face)
- **Purpose**: AI/ML model and dataset access
- **Status**: Configured
- **Configuration**: `claude mcp add hf-mcp-server -e HF_TOKEN=token -- mcp-remote https://huggingface.co/mcp`

Step 4: Add Author Information

markdown
## Author Information

### Standard Package Authorship
- **Name**: Author Name
- **Email**: author@example.com
- **ORCID**: 0000-0000-0000-0000
- **GitHub**: username

Step 5: Add Security Guidelines

markdown
## Security & Confidentiality

- Never commit `.Renviron`, `.env`, or files containing tokens
- Use placeholder values in documentation: `YOUR_TOKEN_HERE`
- Environment variables for all secrets
- Git-ignored: `.Renviron`, `.env`, `credentials.json`

Step 6: Reference Skills and Guides

markdown
## Development Best Practices References
@development-guides/skills/r-packages/write-testthat-tests/SKILL.md
@development-guides/skills/r-packages/submit-to-cran/SKILL.md

Step 7: Add Quality and Status Information

markdown
## Quality Status

- R CMD check: 0 errors, 0 warnings, 1 note
- Test coverage: 85%
- Tests: 200+ passing
- Vignettes: 3 (rated 9/10)

Validation

  • • CLAUDE.md is in project root
  • • Quick start commands are accurate and work
  • • Architecture section reflects actual project structure
  • • No sensitive information (tokens, passwords, private paths)
  • • MCP server configurations are current
  • • Referenced files and paths exist

Common Pitfalls

  • •Stale information: Update CLAUDE.md when project structure changes
  • •Too much detail: Keep it concise. Link to detailed guides rather than duplicating content.
  • •Sensitive data: Never include actual tokens or credentials. Use placeholders.
  • •Conflicting instructions: Ensure CLAUDE.md doesn't contradict other config files
  • •Missing from .Rbuildignore: For R packages, add ^CLAUDE\\.md$ to .Rbuildignore

Examples

Pattern observed across successful projects:

  1. •putior (829 lines): Comprehensive CLAUDE.md with quality metrics, 20 accomplishments, MCP integration details, and development workflow
  2. •Simple project (20 lines): Just quick start commands and key conventions

Scale the CLAUDE.md to match project complexity.

Related Skills

  • •create-r-package - CLAUDE.md as part of package setup
  • •configure-mcp-server - MCP configuration referenced in CLAUDE.md
  • •security-audit-codebase - verify no secrets in CLAUDE.md