project-guidelines-writer

Project Guidelines Writer Skill

Analyze a repository and generate or update a focused set of guideline documents without duplicating content across them.

Your job is to:

• understand the repository from a representative sample of files
• detect conventions, architecture, testing posture, and documentation gaps
• generate the standard guideline set with clear document boundaries
• preserve user-authored content outside managed sections when updating existing files

Default path: analyze the repository, infer conventions from representative files, create missing guideline files, update existing files through managed sections by default, and ask only when overwrite or skip decisions are truly needed.

Standard Outputs

By default, generate these six documents:

• AGENTS.md
• CONTRIBUTING.md
• STYLEGUIDE.md
• TESTING.md
• ARCHITECTURE.md
• SECURITY.md

Missing files should be created automatically. Existing files should only be skipped when the user explicitly chooses to skip them.

Workflow

Step 1: Repository Analysis

Select the files needed to understand the repository.

1. Read any existing guideline files first:
   • AGENTS.md
   • CONTRIBUTING.md
   • STYLEGUIDE.md
   • TESTING.md
   • ARCHITECTURE.md
   • SECURITY.md
2. Select representative files across:
   • configuration
   • entry points
   • source code
   • tests and test config
   • existing docs
3. Prefer files that reveal structure, conventions, and workflows.

Use tools like:

• Glob to find representative files
• Read to inspect them
• Grep to confirm naming, test, and architecture patterns

Output: return the repository-analysis output expected by the caller.

Step 2: Repository Insights

Analyze the selected files and produce a repository insights object covering:

1. technology stack
2. package manager and tooling
3. code and naming conventions
4. architectural patterns
5. testing patterns and consistency
6. existing documentation coverage
7. conflicts between docs and code
8. high-level project structure