Skip to main content
brownfield-onboarding This skill helps users get started with existing (brownfield) projects by scanning the codebase, documenting structure and purpose, analyzing architecture and technical stack, identifying design flaws, suggesting improvements for testing and CI/CD pipelines, and generating AI agent constitution files (AGENTS.md) with project-specific context, coding principles, and UI/UX guidelines.
跳到安装 Skills Marketplace 发现并探索由社区构建的 Agent Skills
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/cyberelf/agent_skills --skill brownfield-onboarding命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
下载 Zip 下载中... 同仓库更多 Skills Stress-test and refine an OpenSpec change through a structured grilling session. Use when the user wants Codex to interrogate, complete, or improve an existing or planned OpenSpec change, maintain a visible problem panorama and progress map, resolve unclear requirements and design decisions one question at a time, and write confirmed decisions back into proposal.md, design.md, specs, and tasks.md.
Agent-first graph-backed knowledge wiki builder with a self-contained CLI. Use for Graphwiki init/build/ingest/update, source indexing, semantic entity and relationship extraction, generated wiki pages, graph JSON/HTML explorer, evidence line ranges, query/explain question answering, synthesis pages, HTML reports, adding confirmed entity types, applying patches, cleanup, validation, tasks, and SQLite cache generation.
insight-knowledge-harvest Build and expand an insight-ready raw-material layer by discovering page-level sources, deduplicating them with an internal pre-crawl link index, capturing raw Markdown, verifying metadata in place, and keeping ingest/register state aligned. Use for additive source harvesting, raw webpage capture, source registry maintenance, source/ingest tracking, source/raw downloads, and in-place verification rather than final synthesis.
name brownfield-onboarding description This skill helps users get started with existing (brownfield) projects by scanning the codebase, documenting structure and purpose, analyzing architecture and technical stack, identifying design flaws, suggesting improvements for testing and CI/CD pipelines, and generating AI agent constitution files (AGENTS.md) with project-specific context, coding principles, and UI/UX guidelines. metadata {"author":"cyberelf","version":"1.0"}
Brownfield Project Onboarding
Overview
This skill provides a systematic approach to understand and document existing projects. It helps developers quickly get up to speed with unfamiliar codebases by generating comprehensive documentation about the project's structure, architecture, design decisions, identifying areas for improvement, and creating AI agent constitution files (AGENTS.md) that encode project-specific knowledge, coding principles, and UI/UX guidelines for effective AI-assisted development.
When to Use This Skill
Invoke this skill when:
Starting work on an unfamiliar or inherited codebase
Joining a new team or project
Conducting a technical audit of an existing system
User requests "help me understand this project"
Need to document an undocumented or poorly documented project
Preparing for a major refactoring or modernization effort
Setting up AI agent constitution files for better AI-assisted development
Establishing coding principles and standards for a team
Creating comprehensive context for AI agents working on the project
How This Skill Works
Upon invocation, this skill:
Analyzes the project to determine its documentation state
Selects the appropriate workflow based on project maturity
Executes the workflow to generate comprehensive documentation
Creates or enhances AGENTS.md files for AI agent context
Provides actionable recommendations for improvements
Workflow Selection This skill uses different workflows based on the project's current state:
Project State Detection The AI agent automatically analyzes the project to determine its documentation maturity level.
Search for AGENTS.md files using file_search
Search for constitution/guideline files (.cursorrules, CONTRIBUTING.md, etc.)
Read and analyze README for depth and quality
Apply classification rules with intelligent judgment
MATURE : AGENTS.md existsESTABLISHED : Constitution files + substantial README (>100 lines)PARTIAL : Basic README (>50 lines) onlyVANILLA : Minimal/no documentation (default)
Has AGENTS.md → MATURE
Has constitution files + README >100 lines with depth → ESTABLISHED
Has README >50 lines of meaningful content → PARTIAL
Otherwise → VANILLA (default)
The agent uses its intelligence to assess quality, not just quantity. A 60-line README with architecture details is better than a 150-line changelog.
Workflow Files Based on the agent's assessment, one of these workflows is executed:
Core Workflow Phases All workflows execute these five phases (adapted to project state):
Phase 1: Project Discovery
Scan codebase structure
Identify technologies and frameworks
Discover features and entry points
Output : .onboard/overview.md
Phase 2: Architecture Analysis
Document technical stack
Identify architectural patterns
Map data flow
Output : .onboard/architecture.md
Phase 3: Design Assessment
Evaluate code quality
Identify technical debt
Propose improvements
Output : .onboard/design_suggestions.md
Phase 4: Quality & Automation Review
Assess testing coverage
Evaluate CI/CD maturity
Recommend improvements
Output : .onboard/guardrail_suggestions.md
Phase 5: Agent Constitution Generation
Detect/read existing constitutions
Generate or enhance AGENTS.md files
Create project-specific guidelines
Outputs : AGENTS.md files + .onboard/agent_constitution.md
Execution Instructions
Step 1: Detect Project State Analyze the project to determine its documentation maturity:
Search for AGENTS.md : Use file_search with pattern **/AGENTS.md
If found → State is MATURE
Search for constitution files : Use file_search to look for:
.cursorrulesCONTRIBUTING.md.github/CONSTITUTION.mdLinter configs (.eslintrc, .prettierrc, etc.)
Style guides
Analyze README : Use read_file to check README.md
Count lines of meaningful content (exclude headers, badges, empty lines)
Assess depth: Does it explain architecture, setup, contribution guidelines?
Classify based on findings :
Has AGENTS.md → MATURE
Has constitution files + substantial README (>100 lines) → ESTABLISHED
Has basic README (>50 lines) but no constitution → PARTIAL
Minimal/no README (<50 lines) → VANILLA (default)
Step 2: Load Appropriate Workflow Based on your assessment, read and execute the corresponding workflow:
Step 3: Execute Workflow Follow the instructions in the selected workflow file:
Each workflow provides detailed, phase-by-phase instructions
Each workflow adapts phases to the project's current state
Each workflow includes specific tool usage recommendations
Step 4: Validate Outputs Ensure all expected files are generated:
Step 5: Provide Summary Give user a comprehensive completion summary based on workflow type.
AGENTS.md Templates This skill includes template files for generating AGENTS.md:
Available Templates
Template Adaptation Templates are adapted based on:
Actual project structure and patterns
Discovered design tokens and conventions
Existing constitution file content
Tech stack and framework conventions
Key Principles
1. Non-Destructive Enhancement
Never overwrite existing documentation
Enhance and complement, don't replace
Preserve existing constitution files
Mark all additions clearly
2. Context-Aware Generation
Generate content based on actual code analysis
Use project-specific examples
Adapt to detected patterns
Match existing documentation style
3. Workflow Adaptation
Different approaches for different project maturities
Respect existing work and conventions
Focus effort where value is highest
Minimize disruption to established projects
4. AI Agent Optimization
Create machine-readable guidelines
Include validation checklists
Provide quick reference formats
Synthesize across multiple docs
Common Tools Used Across all workflows, these tools are commonly used:
Discovery Tools
list_dir - Explore directory structurefile_search - Find specific files by pattern (e.g., **/AGENTS.md, **/.cursorrules)read_file - Read documentation and config files (README, CONTRIBUTING, etc.)
Analysis Tools
semantic_search - Find features and conceptsgrep_search - Pattern-based code searchlist_code_usages - Understand code relationships
Validation Tools
get_errors - Identify existing issuesCode analysis for patterns and anti-patterns
Output Directory Structure After execution, the workspace contains:
.onboard/
├── overview.md # Project structure and features
├── architecture.md # Technical stack and architecture
├── design_suggestions.md # Improvement recommendations
├── guardrail_suggestions.md # Testing and CI/CD recommendations
└── agent_constitution.md # Constitution generation summary
AGENTS.md # Root project constitution
[frontend]/AGENTS.md # Frontend guidelines (if applicable)
[backend]/AGENTS.md # Backend guidelines (if applicable)
Notes & Best Practices
Comprehensive Analysis : Take time to thoroughly explore before documentingBe Specific : Include file paths and concrete examplesPrioritize : Rank suggestions by impact and effortActionable : Provide implementable recommendationsContext-Aware : Tailor to project size, domain, and maturityPositive Framing : Start with strengths before improvementsRealistic Estimates : Provide effort estimates for planningAgent-Friendly : Enable AI agents to validate their workRespect Existing Constitutions : Enhance rather than replaceNon-Destructive : Always preserve existing content when mergingContext-Rich Constitutions : Make AGENTS.md comprehensive with project-specific details
Common Pitfalls to Avoid
❌ Generating superficial documentation without deep analysis
❌ Making technology recommendations without understanding constraints
❌ Suggesting major rewrites instead of incremental improvements
❌ Ignoring existing documentation or architectural decisions
❌ Providing generic advice that doesn't apply to the specific project
❌ Overwhelming with too many suggestions without prioritization
❌ Missing critical security or performance issues
❌ Overwriting existing constitution files without preserving original content
❌ Creating generic AGENTS.md templates without project-specific context
❌ Skipping UI/UX principles analysis for frontend projects
Extension Points This skill can be extended to include:
Security Audit : Dedicated security vulnerability assessmentPerformance Profiling : Performance bottleneck identificationAccessibility Review : WCAG compliance checking for web appsAPI Documentation : Automated API documentation generationDatabase Analysis : Schema design review and optimization suggestionsUI/UX Deep Dive : Integration with ui-ux-pro-max skill for comprehensive UI/UX principlesDependency Audit : Automated dependency security and license checkingConstitution Compliance : Automated checking of code against AGENTS.md guidelines
Related Skills
ui-ux-pro-max : Can be invoked for comprehensive UI/UX analysis to enhance frontend AGENTS.md filesopenspec-constitution-guard : Can validate code changes against generated AGENTS.md constitutionsissue-fixer : Uses project context from AGENTS.md files to fix issues more effectivelyretrospect : References AGENTS.md for project-specific context during retrospective analysis
Reference Documentation
Workflow References
Template References
Quick Start
User invokes : "Help me understand this project" or "Run brownfield onboarding"Detect project state : Analyze project to determine maturity level (MATURE/ESTABLISHED/PARTIAL/VANILLA)Load workflow : Read the appropriate workflow file from references/Execute phases : Follow workflow instructions for all 5 phasesGenerate outputs : Create all documentation and AGENTS.md filesProvide summary : Give user comprehensive results and next steps The workflow files contain all detailed instructions - this main SKILL.md serves as the orchestration guide.
