project-docs
Project documentation lifecycle for PHP/Laravel and Node/TypeScript/React projects — bootstrapping essential docs, naming and folder conventions, freshness, and cleanup of AI-generated junk and stale files. Use when starting a new project, setting up docs/ structure, auditing markdown files, cleaning up the docs folder, or deciding which docs to keep, archive, or delete. Triggers on "set up docs", "audit docs", "clean up markdown", "what docs does this project need", "organize docs folder", "find stale docs".
- License 许可
- MIT
- 最近更新
- 2026-09-01
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- project-docs
- license
- MIT
- metadata
- { "author": "agent-skills", "version": "1.0.0" }
- description
- Project documentation lifecycle for PHP/Laravel and Node/TypeScript/React projects — bootstrapping essential docs, naming and folder conventions, freshness, and cleanup of AI-generated junk and stale files. Use when starting a new project, setting up docs/ structure, auditing markdown files, cleaning up the docs folder, or deciding which docs to keep, archive, or delete. Triggers on "set up docs", "audit docs", "clean up markdown", "what docs does this project need", "organize docs folder", "find stale docs".
02 资源文件 29
- 参考文档AGENTS.md93.6 KB
- 参考文档README.md2.0 KB
- 参考文档rules/_sections.md2.1 KB
- 参考文档rules/_template.md608 B
- 参考文档rules/cleanup-ai-junk.md5.1 KB
- 参考文档rules/cleanup-duplicates.md3.7 KB
- 参考文档rules/cleanup-empty-stubs.md3.7 KB
- 参考文档rules/cleanup-orphans.md3.9 KB
- 参考文档rules/essential-changelog.md3.9 KB
- 参考文档rules/essential-contributing.md3.0 KB
- 参考文档rules/essential-license.md3.4 KB
- 参考文档rules/essential-readme.md3.1 KB
- 参考文档rules/essential-security.md3.5 KB
- 参考文档rules/lifecycle-adr-process.md4.4 KB
- 参考文档rules/lifecycle-archive.md4.3 KB
- 参考文档rules/lifecycle-changelog-discipline.md4.0 KB
- 参考文档rules/lifecycle-freshness.md3.5 KB
- 参考文档rules/naming-adr-files.md3.5 KB
- 参考文档rules/naming-anti-patterns.md3.5 KB
- 参考文档rules/naming-docs-files.md3.0 KB
- 参考文档rules/naming-root-files.md3.2 KB
- 参考文档rules/quality-ai-slop.md5.5 KB
- 参考文档rules/quality-code-blocks.md3.8 KB
- 参考文档rules/quality-conciseness.md4.3 KB
- 参考文档rules/quality-headings.md3.8 KB
- 参考文档rules/quality-links.md4.3 KB
- 参考文档rules/structure-docs-folder.md3.3 KB
- 参考文档rules/structure-root-files.md3.3 KB
- 参考文档rules/structure-subfolders.md3.3 KB
03 SKILL.md 正文
Project Documentation
End-to-end documentation lifecycle for PHP/Laravel and Node/TypeScript/React projects. Contains 25 rules across 6 categories covering folder structure, naming conventions, essential files, content quality (including AI-slop detection), cleanup of accumulated junk, and lifecycle. Supports bootstrap mode (set up docs in a new project), audit mode (find what's missing, stale, bloated, or junk), and reference mode (conventions lookup).
Metadata
- Version: 1.0.0
- Scope: PHP / Laravel + Node / TypeScript / React projects
- Rule Count: 25 rules across 6 categories
- License: MIT
How to Use This Skill — Three Modes
Mode 1: Bootstrap (new project / missing docs)
When the user asks "set up docs", "what docs does this project need", or starts a new project — walk through the bootstrap steps:
- Detect project type (Laravel? React? Both?) —
composer.json,package.json,artisanbinary - Inventory existing docs — list every
.mdfile with its location and last-modified date - Identify gaps — compare against the Essential Files checklist; report what's missing
- Propose folder structure —
docs/with sub-folders (architecture/,adr/,guides/,runbooks/,archive/) based on project size - Offer to scaffold templates — README, CHANGELOG, LICENSE, CONTRIBUTING, SECURITY, ADR-0001 — generate with user approval, do not auto-create
- Suggest CI gates — markdown-lint, broken-link checker (lychee), CHANGELOG-on-PR enforcement
Mode 2: Audit (existing project cleanup)
When the user asks "audit docs", "clean up markdown", or "what should I delete" — produce a classified ledger.
For each .md file in the repo:
- KEEP — file is essential and current
- UPDATE — file is essential but stale (e.g., README contradicts current setup)
- ARCHIVE — superseded but historically useful — move to
docs/archive/<year>/ - DELETE — AI-generated plan files, empty stubs, duplicates, orphaned drafts
- MOVE — wrong location or wrong name (e.g.,
MyArchitectureNotes.mdat root →docs/architecture/overview.md)
Output format:
## Documentation Audit Ledger
| File | Last modified | Verdict | Reason | Action |
|------|---------------|---------|--------|--------|
| PLAN.md | 2026-02-14 | DELETE | AI-generated plan, no longer referenced | rm PLAN.md |
| README.md | 2024-08-01 | UPDATE | Setup steps reference removed Vite v3 | Update install section |
| docs/old-architecture.md | 2024-11 | ARCHIVE | Superseded by docs/architecture/overview.md | mv to docs/archive/2024/ |
| MyNotes.md | 2025-09 | DELETE | Personal notes; not project docs | rm MyNotes.md |
## Summary
- KEEP: X files
- UPDATE: Y files (top priority: ...)
- ARCHIVE: Z files
- DELETE: N files
- MOVE: M files
Never auto-delete. Always surface for user approval first.
Mode 3: Reference (conventions lookup)
When the user asks "how should I name this", "where should this go", or references the skill in a code-review context — look up the relevant rule(s) in rules/.
When to Apply
Reference this skill when:
- Starting a new Laravel or Node/React project and need a docs baseline
- Onboarding a project with messy or AI-cluttered markdown files
- Setting up
docs/folder structure - Naming a new doc file
- Deciding whether to delete a
PLAN.md/TODO.md/IMPLEMENTATION-SUMMARY.md - Adding CI checks for markdown quality
- Reviewing a PR that adds or modifies documentation
- Quarterly "docs hygiene" sweep
Step 1: Detect Project Type
Always check the project stack before recommending specifics. Bootstrap and naming guidance differ slightly per stack.
| Signal | Project Type | Notes |
|---|---|---|
composer.json + artisan |
Laravel (PHP) | README should cover composer install, php artisan migrate, .env.example |
package.json (only) |
Node / TypeScript / React | README should cover npm install, .nvmrc, build scripts |
| Both present | Laravel + Inertia + React | README covers both PHP and Node setup paths |
The rules themselves are mostly stack-agnostic — README format, ADR structure, naming conventions apply to any project.
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Structure | CRITICAL | structure- |
| 2 | Naming | CRITICAL | naming- |
| 3 | Essential Files | HIGH | essential- |
| 4 | Quality | HIGH | quality- |
| 5 | Cleanup | HIGH | cleanup- |
| 6 | Lifecycle | MEDIUM | lifecycle- |
Quick Reference
1. Structure (CRITICAL)
structure-root-files— Which files belong at the repo root (README, CHANGELOG, LICENSE, etc.)structure-docs-folder—docs/as the home for everything beyond root filesstructure-subfolders— Recommendeddocs/layout: architecture/, adr/, guides/, runbooks/, archive/
2. Naming (CRITICAL)
naming-root-files—UPPERCASE.mdfor conventional root filesnaming-docs-files—kebab-case.mdfor files underdocs/naming-adr-files— Numbered prefix:0001-record-architecture-decisions.mdnaming-anti-patterns— No dates, noMyNotes.md, notmp/draft/finalmarkers
3. Essential Files (HIGH)
essential-readme— Every project needs a README with purpose, install, usage, licenseessential-changelog— Keep-a-Changelog format; one entry per releaseessential-license—LICENSEfile (orLICENSE.md) at repo rootessential-contributing—CONTRIBUTING.mdwhen accepting external contributorsessential-security—SECURITY.mdwith vulnerability reporting policy
4. Quality (HIGH)
quality-conciseness— Cut bloat; length is a cost, not a virtuequality-ai-slop— Detect AI-generated content patterns (filler, sign-offs, generic praise)quality-headings— One H1, no skipped levels, descriptive heading textquality-code-blocks— Language tags, copy-pasteable commands, no untagged blocksquality-links— Descriptive link text (not "click here"), relative paths, no broken links
5. Cleanup (HIGH)
cleanup-ai-junk— Detect and remove AI-generated plan/summary filescleanup-duplicates— Same content in multiple files; consolidate or delete copiescleanup-orphans—.mdfiles not linked from anywhere; archive or deletecleanup-empty-stubs— Files with TBD / TODO / placeholder content only
6. Lifecycle (MEDIUM)
lifecycle-freshness— "Last verified" dates on architecture docslifecycle-archive— Superseded docs go todocs/archive/<year>/lifecycle-adr-process— ADR creation triggers and lifecycle (proposed → accepted → superseded)lifecycle-changelog-discipline— Add a CHANGELOG entry in the same PR as the change
Essential Patterns
Standard folder layout
.
├── README.md # required
├── CHANGELOG.md # required from first release
├── LICENSE # required
├── CONTRIBUTING.md # if external contributors
├── SECURITY.md # if internet-facing
├── CODE_OF_CONDUCT.md # if open source community
├── .github/
│ └── CODEOWNERS # team ownership
└── docs/
├── architecture/
│ ├── overview.md
│ └── data-model.md
├── adr/
│ ├── 0001-record-architecture-decisions.md
│ ├── 0002-choose-mysql-over-postgres.md
│ └── 0003-adopt-inertia-for-spa.md
├── guides/
│ ├── getting-started.md
│ ├── deployment.md
│ └── local-development.md
├── runbooks/
│ ├── deploy-production.md
│ └── incident-response.md
└── archive/
└── 2024/
└── old-architecture-notes.md
File naming at a glance
✓ README.md, CHANGELOG.md, LICENSE, CONTRIBUTING.md, SECURITY.md
✓ docs/architecture/overview.md
✓ docs/adr/0007-cache-strategy.md
✓ docs/guides/deployment.md
✓ docs/archive/2024/q3-launch-plan.md
✗ Readme.md, Changelog.md (use UPPERCASE for conventional root files)
✗ docs/Architecture/Overview.md (use kebab-case in docs/)
✗ docs/Notes-2025-09-14.md (no dates in filenames)
✗ MyArchitectureThoughts.md (no first-person, no PascalCase)
✗ PLAN.md, TODO.md, TEMP.md (use issue tracker for transient state)
✗ FINAL-deployment-guide-v2.md (no draft/final/v2 markers)
CI: keep markdown honest
# .github/workflows/docs.yml
- name: Lint markdown
uses: DavidAnson/markdownlint-cli2-action@v23
- name: Check links
uses: lycheeverse/lychee-action@v2
with:
args: --no-progress --exclude-mail './**/*.md'
How to Use
Read individual rule files for detailed conventions and examples:
rules/structure-root-files.md
rules/naming-adr-files.md
rules/essential-readme.md
rules/cleanup-ai-junk.md
rules/lifecycle-archive.md
Each rule file contains:
- YAML frontmatter with metadata (title, impact, tags)
- Brief explanation of why it matters
- Incorrect example (anti-pattern)
- Correct example (the convention)
- Detection / enforcement guidance where applicable
References
- Keep a Changelog
- Semantic Versioning
- Architecture Decision Records (ADR)
- Diátaxis — documentation framework
- Choose a License
- Markdownlint
- Lychee — link checker
Full Compiled Document
For the complete guide with all rules expanded: AGENTS.md
04 同仓库更多 Skills
wordpress-pro
Develops custom WordPress themes and plugins, creates and registers Gutenberg blocks and block patterns, configures WooCommerce stores, implements WordPress REST API endpoints, applies security hardening (nonces, sanitization, escaping, capability checks), and optimizes performance through caching and query tuning. Use when building WordPress themes, writing plugins, customizing Gutenberg blocks, extending WooCommerce, working with ACF, using the WordPress REST API, applying hooks and filters, or improving WordPress performance and security.
websocket-engineer
Use when building real-time communication systems with WebSockets or Socket.IO. Invoke for bidirectional messaging, horizontal scaling with Redis, presence tracking, room management.
webapp-testing
Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
web-design-guidelines
UI/UX best practices and accessibility audit. Use when reviewing UI code, checking accessibility, running accessibility audits, auditing forms, or ensuring web interface best practices. Triggers on "audit accessibility", "check WCAG", "review UI", "check accessibility", "audit design", "review UX", or "check best practices".
web-artifacts-builder
Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.
vue-expert
Builds Vue 3 components with Composition API patterns, configures Nuxt 3 SSR/SSG projects, sets up Pinia stores, scaffolds Quasar/Capacitor mobile apps, implements PWA features, and optimises Vite builds. Use when creating Vue 3 applications with Composition API, writing reusable composables, managing state with Pinia, building hybrid mobile apps with Quasar or Capacitor, configuring service workers, or tuning Vite configuration and TypeScript integration.