| name | should-be-project-context |
| disable-model-invocation | true |
| description | Internal project-context placement and consistency reference used by context refactoring and verification workflows. |
should-be-project-context
A skill for analyzing project context files and maintaining consistency while updating and organizing them.
Principles
- AGENTS.md is the SSOT (Single Source of Truth)
- README.md is the "entry point for humans": The first file seen on GitHub
- AGENTS.md is the "guide for AI agents": Detailed information needed for development work
- Unified format: Consistent structure following templates
- Follow the target project's language convention: context files (AGENTS.md, README.md, gotchas.md, rules) must match the language already established by the target project's existing documentation. Do not force English when the target project's convention is a different language
File Roles
README.md
Target audience: Humans (GitHub visitors, new contributors)
Placement rule:
- Root directory: Required
- Monorepo packages: Each publishable package should have its own README.md (displayed on npm)
- Other subdirectories: Not needed (use AGENTS.md instead)
What to include:
- Project name + one-line description
- Overview (2-3 sentences, project purpose)
- Installation steps (minimal)
- Command list (all slash commands, only commonly used npm scripts)
- Related repositories/links (if any)
- License
What NOT to include:
- Detailed directory structure → Refer to AGENTS.md
- Architecture details → Refer to AGENTS.md
- Environment variable details → Refer to AGENTS.md or .env.example
- API specifications → Refer to AGENTS.md
- Development notes → Refer to AGENTS.md
AGENTS.md (Root)
Target audience: AI agents (Claude Code, etc.), developers
What to include:
- Project overview (2-3 sentences)
- Directory/package structure (one-line descriptions only)
- Basic command list (commonly used ones)
- Important instructions/constraints
- Skills list
- Command last updated date
What NOT to include:
- Detailed usage of each package → Refer to subdirectory AGENTS.md
- Environment variable details → Refer to subdirectory AGENTS.md
- Specific code examples → Refer to subdirectory AGENTS.md
- API specifications → Refer to subdirectory AGENTS.md
- Installation steps (documented in README.md)
- License information (documented in README.md)
- References to rules (.claude/rules/ is auto-loaded, no need to reference)
AGENTS.md (Subdirectory)
Target audience: AI agents (Claude Code, etc.), developers
What to include:
- Package/project-specific detailed information
- Development commands (all)
- Environment variables list and descriptions
- Specific command examples
- Detailed directory structure
- API specifications/exports list
- Important notes and considerations
- Command last updated date
What NOT to include:
- Duplicate information already in root
CLAUDE.md
Role: Symbolic link to AGENTS.md
Setup: ln -sf AGENTS.md CLAUDE.md (same directory)
CLAUDE.md is NOT a separate file — it MUST be a symlink pointing to AGENTS.md. If a CLAUDE.md exists as a regular file, replace it with a symlink.
Execution Rules
No User Confirmation
NEVER ask the user for confirmation. Once this skill is invoked, make all decisions autonomously and execute to completion.
Questions like "Is this okay?" or "Should I proceed?" are strictly prohibited. When in doubt, use AGENTS.md as SSOT and act immediately.
Subagent-Driven Execution
Launch a subagent for each target file and process them in parallel.
Each subagent independently reads, analyzes, and updates its assigned file.
Task Management
Create a TODO for each target file path before launching subagents. Mark each as completed when done.
Example:
- [ ] Update .claude/rules/ai-generated/gotchas.md
- [ ] Update AGENTS.md
- [ ] Update README.md
Processing Targets
- gotchas.md - Classify and organize insights learned during sessions
- AGENTS.md - Refactor project structure and architecture information
- README.md - Consistency check + update command list
Consistency Check
- Verify project overview matches AGENTS.md
- If inconsistencies exist, auto-correct README.md using AGENTS.md as SSOT
Reference Files
- @${CLAUDE_PLUGIN_ROOT}/skills/should-be-project-context/classification-criteria.md - Classification criteria (colocation principle, hierarchy design)
- @${CLAUDE_PLUGIN_ROOT}/skills/should-be-project-context/readme-template.md - Unified format for README.md
- @${CLAUDE_PLUGIN_ROOT}/skills/should-be-project-context/agents-template.md - Unified format for AGENTS.md
