From 52f31e9563f18cd71d624496223652d90e718722 Mon Sep 17 00:00:00 2001 From: Sergio Bernal Date: Sun, 1 Nov 2026 16:09:02 +0100 Subject: [PATCH 1/2] docs(create-agentsmd): prioritize concise reusable agent context --- skills/create-agentsmd/SKILL.md | 125 +++++++++++++------------------- 1 file changed, 49 insertions(+), 76 deletions(-) diff --git a/skills/create-agentsmd/SKILL.md b/skills/create-agentsmd/SKILL.md index bdcfcf7c93..3369b06586 100644 --- a/skills/create-agentsmd/SKILL.md +++ b/skills/create-agentsmd/SKILL.md @@ -2,7 +2,6 @@ name: create-agentsmd description: 'Prompt for generating an AGENTS.md file for a repository' --- - # Create high‑quality AGENTS.md file You are a code agent. Your task is to create a complete, accurate AGENTS.md at the root of this repository that follows the public guidance at https://agents.md/. @@ -15,29 +14,34 @@ AGENTS.md is a Markdown file that serves as a "README for agents" - a dedicated, ## Key Principles -- **Agent-focused**: Contains detailed technical instructions for automated tools +- **Agent-focused** : Make every token count. Prioritize context that helps the agent make better decisions in any session, and link to task-specific details for when they are needed - **Complements README.md**: Doesn't replace human documentation but adds agent-specific context - **Standardized location**: Placed at repository root (or subproject roots for monorepos) - **Open format**: Uses standard Markdown with flexible structure +- **Minimal size**: Keep it as small as possible while preserving essential, actionable instructions. Remove redundancy and link to existing documentation instead of duplicating it - **Ecosystem compatibility**: Works across 20+ different AI coding tools and agents ## File Structure and Content Guidelines -### 1. Required Setup +### 1. File Requirements - Create the file as `AGENTS.md` in the repository root - Use standard Markdown formatting - No required fields - flexible structure based on project needs -### 2. Essential Sections to Include +### 2. Sections to Consider + +Choose sections and detail based on the project. Short command lists and concise rules can stay inline or link to an existing command block. Link longer explanations and procedures to a coherent documentation range or dedicated skill. Group related topics under one reference when they are documented together; separate links only when they help agents find distinct content. #### Project Overview - Brief description of what the project does -- Architecture overview if complex +- Architecture overview - Key technologies and frameworks used -#### Setup Commands +#### Setup + +Keep the full setup guide in human documentation or a dedicated skill, where dependencies, prerequisites, configuration, and troubleshooting can be explained together. AGENTS.md should briefly say when to consult it and link to the relevant range; a simple installation command can stay inline if it is sufficient. - Installation instructions - Environment setup steps @@ -47,20 +51,23 @@ AGENTS.md is a Markdown file that serves as a "README for agents" - a dedicated, #### Development Workflow - How to start development server -- Build commands -- Watch/hot-reload setup +- Watch/hot-reload commands - Package manager specifics (npm, pnpm, yarn, etc.) #### Testing Instructions +Keep a short list of test commands and essential requirements inline, or link to the testing command block. Use a broader reference for explanations of suite selection, fixtures, coverage, or failure diagnosis. + - How to run tests (unit, integration, e2e) - Test file locations and naming conventions - Coverage requirements - Specific test patterns or frameworks used -- How to run subset of tests or focus on specific areas +- How to run a subset of tests or focus on specific areas #### Code Style Guidelines +Use the topics below as links to the relevant blocks in external documentation or a dedicated skill. Simple lint/format commands can stay inline when useful; convention topics should point to their content rather than serve as placeholders for expanding it inside AGENTS.md. + - Language-specific conventions - Linting and formatting rules - File organization patterns @@ -69,6 +76,8 @@ AGENTS.md is a Markdown file that serves as a "README for agents" - a dedicated, #### Build and Deployment +Build commands and output paths can be a few inline entries or one link to the command block. Link deployment procedures when they involve environment configuration, prerequisites, release steps, or recovery guidance; a single deployment command needs no separate guide if it is sufficient. + - Build commands and outputs - Environment configurations - Deployment steps and requirements @@ -87,11 +96,13 @@ AGENTS.md is a Markdown file that serves as a "README for agents" - a dedicated, - How to work with multiple packages - Cross-package dependencies -- Selective building/testing +- Selective build/test commands or a shared reference when the workflow needs explanation - Package-specific commands #### Pull Request Guidelines +Keep brief requirements such as the title format, required checks, and commit convention inline. Link the contribution or review workflow as a block when it needs more explanation; do not create a separate reference just for a title format. + - Title format requirements - Required checks before submission - Review process @@ -99,14 +110,12 @@ AGENTS.md is a Markdown file that serves as a "README for agents" - a dedicated, #### Debugging and Troubleshooting -- Common issues and solutions -- Logging patterns -- Debug configuration -- Performance considerations +- Keep a short, recurring fix inline when useful +- Link longer diagnosis and recovery procedures to the relevant documentation range or dedicated skill, indicating when to consult it ## Example Template -Use this as a starting template and customize based on the specific project: +Use this as a starting template, keeping applicable topics and filling placeholders with concise rules or commands. Use shared references for detail, omit redundant entries, and replace example paths and line ranges with verified ones: ```markdown # AGENTS.md @@ -115,17 +124,14 @@ Use this as a starting template and customize based on the specific project: [Brief description of the project, its purpose, and key technologies] -## Setup Commands +## Setup References -- Install dependencies: `[package manager] install` -- Start development server: `[command]` -- Build for production: `[command]` +- For first-time setup, consult [Setup: dependencies, environment, database, and troubleshooting — README.md, lines 45–90](./README.md#L45-L90). ## Development Workflow -- [Development server startup instructions] -- [Hot reload/watch mode information] -- [Environment variable setup] +- Start development server: `[command]` +- Watch for changes: `[command]` ## Testing Instructions @@ -133,65 +139,35 @@ Use this as a starting template and customize based on the specific project: - Run unit tests: `[command]` - Run integration tests: `[command]` - Test coverage: `[command]` -- [Specific testing patterns or requirements] +- For test selection and specific requirements, consult [Testing guide — README.md, lines 91–120](./README.md#L91-L120). -## Code Style +## Code Style Guidelines -- [Language and framework conventions] -- [Linting rules and commands] -- [Formatting requirements] -- [File organization patterns] +- [Language and framework conventions — CONTRIBUTING.md, lines 45–59](./CONTRIBUTING.md#L45-L59) +- [Linting rules and commands — CONTRIBUTING.md, lines 60–69](./CONTRIBUTING.md#L60-L69) +- [Formatting requirements — CONTRIBUTING.md, lines 70–79](./CONTRIBUTING.md#L70-L79) +- [File organization patterns — CONTRIBUTING.md, lines 80–90](./CONTRIBUTING.md#L80-L90) ## Build and Deployment -- [Build process details] -- [Output directories] -- [Environment-specific builds] -- [Deployment commands] +- Build: `[command]` +- Output: `[directory]` +- For environment-specific builds and deployment steps, consult [Build and deployment guide — README.md, lines 121–160](./README.md#L121-L160). ## Pull Request Guidelines - Title format: [component] Brief description - Required checks: `[lint command]`, `[test command]` -- [Review requirements] +- Commit messages: [brief convention] +- For the full submission and review workflow, consult [Contribution guide — CONTRIBUTING.md, lines 91–130](./CONTRIBUTING.md#L91-L130). ## Additional Notes - [Any project-specific context] -- [Common gotchas or troubleshooting tips] +- For environment troubleshooting, consult [Setup and troubleshooting — README.md, lines 45–90](./README.md#L45-L90). - [Performance considerations] ``` -## Working Example from agents.md - -Here's a real example from the agents.md website: - -```markdown -# Sample AGENTS.md file - -## Dev environment tips - -- Use `pnpm dlx turbo run where ` to jump to a package instead of scanning with `ls`. -- Run `pnpm install --filter ` to add the package to your workspace so Vite, ESLint, and TypeScript can see it. -- Use `pnpm create vite@latest -- --template react-ts` to spin up a new React + Vite package with TypeScript checks ready. -- Check the name field inside each package's package.json to confirm the right name—skip the top-level one. - -## Testing instructions - -- Find the CI plan in the .github/workflows folder. -- Run `pnpm turbo run test --filter ` to run every check defined for that package. -- From the package root you can just call `pnpm test`. The commit should pass all tests before you merge. -- To focus on one step, add the Vitest pattern: `pnpm vitest run -t ""`. -- Fix any test or type errors until the whole suite is green. -- After moving files or changing imports, run `pnpm lint --filter ` to be sure ESLint and TypeScript rules still pass. -- Add or update tests for the code you change, even if nobody asked. - -## PR instructions - -- Title format: [] -- Always run `pnpm lint` and `pnpm test` before committing. -``` - ## Implementation Steps 1. **Analyze the project structure** to understand: @@ -200,31 +176,28 @@ Here's a real example from the agents.md website: - Package managers and build tools - Testing frameworks - Project architecture (monorepo, single package, etc.) - 2. **Identify key workflows** by examining: - package.json scripts - Makefile or other build files - CI/CD configuration files - Documentation files +3. **Choose useful content for each section**: -3. **Create comprehensive sections** covering: - - - All essential setup and development commands - - Testing strategies and commands - - Code style and conventions - - Build and deployment processes - -4. **Include specific, actionable commands** that agents can execute directly - -5. **Test the instructions** by ensuring all commands work as documented - + - Keep short commands, concise rules, and useful topic lists inline where they help + - Link setup and other extended procedures to coherent documentation ranges or dedicated skills + - Group related guidance under a shared reference rather than creating a link for every item +4. **Include specific, actionable commands** where a short list is sufficient, or link to an existing command block +5. **Verify the instructions** by checking retained commands and referenced content, including line ranges 6. **Keep it focused** on what agents need to know, not general project information ## Best Practices +- **Prioritize relevance across sessions**: A good AGENTS.md contains information useful in every session; unused content reduces its effectiveness. Link to task-specific procedures for agents to read when needed instead of detailing workflows a session may never use. +- **Choose detail by usefulness**: Short command lists and rules can stay inline or link to a shared block. Keep extended setup, troubleshooting, and other procedures in documentation or dedicated skills; preserve useful topic lists without requiring a link per item. - **Be specific**: Include exact commands, not vague descriptions - **Use code blocks**: Wrap commands in backticks for clarity +- **Link to relevant ranges**: Point to a coherent block, e.g. `[README.md — lines 45–90](./README.md#L45-L90)`. Related items can share one reference; use separate links when they lead to distinct guidance. Verify ranges and update them when content moves. - **Include context**: Explain why certain steps are needed - **Stay current**: Update as the project evolves - **Test commands**: Ensure all listed commands actually work From 8b61facd3a5afea0fd6d775131d95c5a5097748e Mon Sep 17 00:00:00 2001 From: Sergio Bernal <sergioguillot@gmail.com> Date: Sun, 1 Nov 2026 16:21:39 +0100 Subject: [PATCH 2/2] docs(create-agentsmd): require CONTRIBUTING reference for PR guidance --- skills/create-agentsmd/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/create-agentsmd/SKILL.md b/skills/create-agentsmd/SKILL.md index 3369b06586..32764c14f1 100644 --- a/skills/create-agentsmd/SKILL.md +++ b/skills/create-agentsmd/SKILL.md @@ -101,7 +101,7 @@ Build commands and output paths can be a few inline entries or one link to the c #### Pull Request Guidelines -Keep brief requirements such as the title format, required checks, and commit convention inline. Link the contribution or review workflow as a block when it needs more explanation; do not create a separate reference just for a title format. +Always link to the relevant line range in `CONTRIBUTING.md` for contribution and review requirements. Keep brief requirements such as the title format, required checks, and commit convention inline when useful; do not create a separate reference just for a title format. - Title format requirements - Required checks before submission