folder-specific-claude-and-agents-md
Create folder-scoped CLAUDE.md and AGENTS.md guidance for future agents working in that area.
- License 许可
- MIT
- 最近更新
- 2026-10-22
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- folder-specific-claude-and-agents-md
- risk
- critical
- tags
- [ "agents-md", "claude-md", "documentation" ]
- tools
- [ "claude", "codex" ]
- author
- davidondrej
- source
- community
- license
- MIT
- category
- development
- date_added
- 2026-07-07
- description
- Create folder-scoped CLAUDE.md and AGENTS.md guidance for future agents working in that area.
- source_repo
- davidondrej/skills
- source_type
- community
- license_source
- https://github.com/davidondrej/skills/blob/main/LICENSE
- user-invocable
- true
03 SKILL.md 正文
Folder CLAUDE.md Creation
When to Use
- Use when the user asks for folder-specific agent instructions or local context files.
- Use when a subdirectory needs a CLAUDE.md and AGENTS.md handoff for future agents.
Generate a focused CLAUDE.md inside a target folder, plus an AGENTS.md symlink pointing at it. The file gives any future agent (Claude Code, Codex, etc.) the folder-specific context the global CLAUDE.md doesn't cover.
Background reference: library/claude-code/claude-and-agents-md.md.
Process
Step 1: Confirm the target folder + sanity-check it deserves a file
Ask the user which folder. Use absolute path under ~/Documents/code/workspace/.
Only create a file if the folder has context needed across multiple sessions — active evolving work, specific conventions, ongoing decisions. A folder of static reference files does NOT need one (agents can read on demand). If unsure, ask the user.
Step 2: Read every file in the folder IN FULL
- Use
ls -lafirst to enumerate files and subfolders. - Read every markdown, config, and key source file.
- For large tldraw/Vite subprojects: read
package.json,src/App.tsx, one representative module file, and the folder's ownmodule-details.md-style files. - Do NOT skim. Do NOT skip. The user's later edits depend on you having full context.
Step 3: Draft a bullet list of candidate content
Before writing the file, give the user a bullet list grouped by section — let them react first. Candidate sections (skip any that don't apply):
- Product / Purpose — what this folder/project is, current state, key metrics
- Avatar / Audience — who it's for (if applicable)
- Essential Files — one-line role for each important file, including cross-folder references (use
@path/file.mdimport syntax) - Constraints (MUST NOT) — explicit hard negatives. Highest-ROI content in the file.
- Conventions — the user's lingo, status emojis (✅ 🟡), naming patterns, "usually do" patterns
- Locked Decisions — things agreed + dated, must not re-litigate
- Context — history, authority, credibility that frames the work
- How to work with the user — collaboration style for this specific folder
- Marketing Angles / Positioning — if public-facing
- Top Insights — 3-5 most glaring signals from research (if research exists)
Step 4: Iterate with the user
- Keep answers short. The user will edit directly in the IDE.
- When they edit the file, RE-READ it and flag: contradictions, typos, missing rules, wrong categorization.
- Do not revert their edits unless asked.
Step 5: Write the file
- Path:
<folder>/CLAUDE.md - Start with a one-line header explaining the file's purpose.
- Subdir file marker: if this is a subdirectory file (parent folder already has its own CLAUDE.md), open with
Apply root CLAUDE.md first, then this file. - Use
##section headers matching the sections the user approved. - Bullets over prose. Short bullets.
- Cross-folder references: use
@relative/path/file.mdimport syntax, not prose mentions. - Heavy reference docs: annotate with
**Read when:**triggers (e.g. "Read when: writing offer copy"). Prevents loading every session.
Step 6: Create the AGENTS.md symlink
cd <folder> && ln -s CLAUDE.md AGENTS.md
Verify with ls -la CLAUDE.md AGENTS.md.
Step 7: Commit only when asked
Do NOT stage or push unless the user says to. When they do: git add -A, commit with a Day N: style message, push.
Rules
- Never invent content. Every bullet must trace back to something you read in the folder or something the user said. No generic boilerplate.
- Brevity wins. The user edits aggressively to make things shorter. Start tight.
- Folder-scoped only. Don't duplicate the global
CLAUDE.md(personality, dates, ports, etc.). Only include what's specific to this folder. - No file trees, no directory dumps, no stack details the code already shows. Anything an agent can derive from
lsorgreprots fast and wastes tokens. Pin decisions, rules, and context — not structure. - Constraints vs Conventions. Hard "MUST NOT" rules go in Constraints (explicit negatives). "Usually do X" patterns go in Conventions. Splitting these improves adherence.
- No absolute ALWAYS/NEVER without explicit exceptions. Edge cases make absolute rules get ignored. "Never commit secrets EXCEPT
.env.example" beats "never commit secrets." - Never summarize or auto-shorten the file. Context collapse degrades it. Grow deliberately, prune manually. If the user asks to trim, do it by hand.
- Maintenance loop. When the user corrects the agent on something this file should have prevented, add the rule to the file immediately. Don't wait.
- No emojis unless the user uses them (status markers ✅ 🟡 are the exception — they're already conventions).
- Symlink, not copy.
AGENTS.mdmust be a symlink so edits stay in sync. - Flag gaps honestly. If the user's edits introduce contradictions (e.g. "sell X" in one section and "never sell X" in another), call it out before they ask.
Limitations
- Adapted from
davidondrej/skills; verify local paths, tools, credentials, and agent features before acting. - For commands, remote access, scheduling, browser automation, or file-changing workflows, get explicit user approval and confirm the target environment first.
04 同仓库更多 Skills
testing-best-practices
Laravel test design and review. Use when selecting coverage, naming or structuring tests, choosing assertions or test data, isolating dependencies, testing HTTP or security boundaries, improving suite performance, or reviewing test value. Use framework guidance or search-docs for Pest and PHPUnit syntax.
tailwindcss-development
Always invoke when the user's message includes 'tailwind' in any form. Also invoke for: building responsive grid layouts (multi-column card grids, product grids), flex/grid page structures (dashboards with sidebars, fixed topbars, mobile-toggle navs), styling UI components (cards, tables, navbars, pricing sections, forms, inputs, badges), adding dark mode variants, fixing spacing or typography, and Tailwind v3/v4 work. The core use case: writing or fixing Tailwind utility classes in HTML templates (Blade, JSX, Vue). Skip for backend PHP logic, database queries, API routes, JavaScript with no HTML/CSS component, CSS file audits, build tool configuration, and vanilla CSS.
laravel-best-practices
Apply this skill whenever writing, reviewing, or refactoring Laravel PHP code. This includes creating or modifying controllers, models, migrations, form requests, policies, jobs, scheduled commands, service classes, and Eloquent queries. Triggers for N+1 and query performance issues, caching strategies, authorization and security patterns, validation, error handling, queue and job configuration, route definitions, and architectural decisions. Also use for Laravel code reviews and refactoring existing Laravel code to follow best practices. Covers any task involving Laravel backend PHP code patterns.
infer-conventions
Use this skill to analyze how a Laravel application is actually written and record its conventions as shared rules. Trigger when the user wants to detect, infer, document, or standardize project conventions or coding style, set up or grow `.ai/rules`, resolve mixed or conflicting patterns (e.g. "are we using Form Requests or inline validation?"), or onboard agents and teammates to "how we do things here". Covers: a systematic sweep of ~49 Laravel convention dimensions (validation, models, architecture, testing, frontend, database, console), open-ended house-pattern discovery, conflict reporting, and recording rules scoped to the right paths via the Boost `record-rule` MCP tool. Only run this skill when the user explicitly asks for it; never start a sweep as part of another task. Do not use for one-off code review, enforcing formatting a linter already handles, or editing `.ai/rules` files by hand.
inertia-react-development
Develops Inertia.js v2 React client-side applications. Activates when creating React pages, forms, or navigation; using <Link>, <Form>, useForm, or router; working with deferred props, prefetching, or polling; or when user mentions React with Inertia, React pages, React forms, or React navigation.
deploying-to-cloud
Deploys and manages Laravel applications on Laravel Cloud using the `cloud` CLI. Use when the user wants to deploy an app, ship to Cloud, create or manage applications, environments, databases, caches, object storage, queues, domains, instances, background processes, secrets, compute, scheduled tasks, or Laravel Cloud infrastructure; or check billing, usage, or spend. Triggers on deployment, shipping, Cloud management, environment setup, database provisioning, billing or usage queries, the `cloud` CLI, and Laravel Cloud deployment troubleshooting.