[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-74192":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":15,"stars7d":16,"stars30d":17,"stars90d":14,"forks30d":14,"starsTrendScore":18,"compositeScore":19,"rankGlobal":9,"rankLanguage":9,"license":9,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":22,"hasPages":20,"topics":23,"createdAt":9,"pushedAt":9,"updatedAt":24,"readmeContent":25,"aiSummary":26,"trendingCount":14,"starSnapshotCount":14,"syncStatus":27,"lastSyncTime":28,"discoverSource":29},74192,"skills-best-practices","mgechev\u002Fskills-best-practices","mgechev","Write professional-grade skills for agents, validate them using LLMs, and maintain a lean context window.",null,"Python",1941,139,13,0,11,18,60,33,19.44,false,"main",true,[],"2026-06-12 02:03:23","# Best Practices for Creating Agent Skills\n\nThis guide explains how to write professional-grade skills for agents, validate them using LLMs, and maintain a lean context window.\n\nThis guide is a concentrated set of best practices for creating agent skills. If you're looking for a comprehensive documentation see [Claude's docs](https:\u002F\u002Fplatform.claude.com\u002Fdocs\u002Fen\u002Fagents-and-tools\u002Fagent-skills\u002Fbest-practices).\n\n**To evaluate if your skills do well and prevent regressions, check out [skillgrade](https:\u002F\u002Fgithub.com\u002Fmgechev\u002Fskillgrade).**\n\n## Structure of a skill\n\nEvery skill must follow this directory structure:\n\nPlaintext\n\n```\nskill-name\u002F\n├── SKILL.md              # Required: Metadata + core instructions (\u003C500 lines)\n├── scripts\u002F              # Executable code (Python\u002FBash) designed as tiny CLIs\n├── references\u002F           # Supplementary context (schemas, cheatsheets) \n└── assets\u002F               # Templates or static files used in output\n```\n\n* **SKILL.md:** Acts as the \"brain.\" Use it for navigation and high-level procedures.  \n* **References:** Link directly from SKILL.md. Keep them **one level deep** only.  \n* **Scripts:** Use for fragile\u002Frepetitive operations where variation is a bug. **Do not bundle library code here**;\n\n## Optimize the frontmatter for discoverability\n\nThe `name` and `description` in the frontmatter of your `SKILL.md` are the only fields that the agent sees before triggering a skill. If they are not optimized for discoverability and specific enough, your skill is invisible.\n\n* **Adhere to Strict Naming:** The name field must be 1-64 characters, contain only lowercase letters, numbers, and hyphens (no consecutive hyphens), and **must exactly match the parent directory name** (e.g., name: `angular-testing` must live in `angular-testing\u002FSKILL.md`).  \n* **Write Trigger-Optimized Descriptions:** (Max 1,024 characters). This is the only metadata the agent sees for routing. Describe the capability in the third person and include \"negative triggers.\"  \n  * **Bad:** \"React skills.\" (Too vague).\n  * **Good:** \"Creates and builds React components using Tailwind CSS. Use when the user wants to update component styles or UI logic. Don't use it for Vue, Svelte, or vanilla CSS projects.\"\n\n## Progressive disclosure and resource management\n\nMaintain a pristine context window by loading information only when needed. **SKILL.md** is the \"brain\" for high-level logic; offload details to subdirectories.\n\n* **Keep SKILL.md Lean:** Limit the main file to **\\\u003C500 lines**. Use it for navigation and primary procedures.  \n* **Use Flat Subdirectories:** Move bulky context to standard folders. Keep files exactly **one level deep** (e.g., `references\u002Fschema.md`, not `references\u002Fdb\u002Fv1\u002Fschema.md`).  \n  * `references\u002F`: API docs, cheatsheets, domain logic.  \n  * `scripts\u002F`: Executable code for deterministic tasks.  \n  * `assets\u002F`: Output templates, JSON schemas, images.  \n* **Just-in-Time (JiT) Loading:** Explicitly instruct the agent when to read a file. It will not see these resources until you direct it to (e.g., *\"See `references\u002Fauth-flow.md` for specific error codes\"*).  \n* **Explicit Pathing:** Always use **relative paths** with forward slashes (`\u002F`), regardless of the OS.\n\nSkills are for agents, not humans. To keep the context window lean and avoid unnecessary token consumption. **Do not create:**\n\n* **Documentation files:** `README.md`, `CHANGELOG.md`, or `INSTALLATION_GUIDE.md`.  \n* **Redundant logic:** If the agent already handles a task reliably without help, delete the instruction.  \n* **Library code:** Skills should reference existing tools or contain tiny, single-purpose scripts. Long-lived library code belongs in standard repo CLI directories.\n\n## Use specific procedural instructions instead of prose\n\nCreate instructions for LLMs instead of humans.\n\n* **Use Step-by-Step Numbering:** Define the workflow as a strict chronological sequence. If there is a decision tree, map it out clearly (e.g., *\"Step 2: If you need source maps run `ng build --source-map`. Otherwise, skip to Step 3.\"*).  \n* **Provide Concrete Templates:** Agents pattern-match exceptionally well. Instead of spending paragraphs describing how a JSON output should look, place a template in the assets\u002F folder and instruct the agent to copy its structure.  \n* **Write in the Third-Person Imperative:** Frame instructions as direct commands to the agent (e.g., *\"Extract the text...\"* rather than *\"I will extract...\"* or *\"You should extract...\"*).\n\nBe specific and consistent in the way you reference concepts in your skill files.\n\n* **Use identical terminology:** Pick a single term to refer to a specific concept.  \n* **Specificity**: Use the most specific terminology that’s native to the domain that you describe. For example, in Angular use the concept “template” instead of “html”, “markup”, or “view”.\n\n## Bundle deterministic scripts for repetitive operations\n\nDon't ask the LLM to write complex parsing logic or boilerplate code from scratch every time it runs a skill.\n\n* **Offload fragile\u002Frepetitive tasks:** If the agent needs to parse a complex dataset or query a specific database, give it a tested Python, Bash, or Node script to run in the scripts\u002F directory.  \n* **Handle edge cases gracefully:** An agent relies on standard output (stdout\u002Fstderr) to know if a script succeeded. Write scripts that return highly descriptive, human-readable error messages so the agent knows exactly how to self-correct without needing user intervention.\n\n# Validation Guide\n\nSince LLMs will be using your skills, the best way I’ve identified to ensure they are useful is in collaboration with LLMs.\n\nIt’s critical to have evals for your skills to make sure the changes you’re making have a positive impact and don’t lead to regression. A popular benchmark for skills is [SkillsBench](https:\u002F\u002Farxiv.org\u002Fabs\u002F2602.12670) which could help with some inspiration.\n\nOnce you draft the initial version of your skills, you can validate your work going through the following steps:\n\n### Discovery Validation\n\nAgents load skills based strictly on the YAML frontmatter. Test how an LLM interprets your description in isolation to prevent false triggers (like firing for a React app when it's meant for Angular).\n\nPaste exactly the text below into a fresh LLM chat:\n\n> I am building an Agent Skill based on the agentskills.io spec. Agents will decide whether to load this skill based entirely on the YAML metadata below.\n>\n> ```\n> name: angular-vite-migrator\n> description: Migrates Angular CLI projects from Webpack to Vite and esbuild. Use when the user wants to update builder configurations, replace webpack plugins with rollup equivalents, or speed up Angular compilation.\n> ```\n>\n> Based strictly on this description:\n> 1. Generate 3 realistic user prompts that you are 100% confident should trigger this skill.\n> 2. Generate 3 user prompts that sound similar but should NOT trigger this skill (e.g., migrating a React app to Vite, or just updating Angular versions).\n> 3. Critique the description: Is it too broad? Suggest an optimized rewrite.\n\nIn addition, prompt agents with assignments that you expect to trigger a skill read and inspect the thought process. Go back and forth with the agent to identify why it picked (or didn’t) particular skills.\n\n### Logic Validation\n\nEnsure your step-by-step instructions are deterministic and don't force the agent to hallucinate missing steps.\n\nFeed the LLM your entire `SKILL.md` and directory structure:\n\n> Here is the full draft of my SKILL.md and the directory tree of its supporting files.\n> \n> ```\n> ├── SKILL.md\n> ├── scripts\u002Fesbuild-optimizer.mjs\n> └── assets\u002Fvite.config.template.ts\n> ```\n> \n> [Paste your SKILL.md contents here]\n> Act as an autonomous agent that has just triggered this skill. Simulate your execution step-by-step based on a request to Migrate my Angular v17 app to Vite.\n>\n> For each step, write out your internal monologue:\n> 1. What exactly are you doing?\n> 2. Which specific file\u002Fscript are you reading or running?\n> 3. Flag any Execution Blockers: Point out the exact line where you are forced to guess or hallucinate because my instructions are ambiguous (e.g., how to map Angular environment files to Vite's import.meta.env).\n\n### Edge Case Testing\n\nForce the LLM to hunt for vulnerabilities, unsupported configurations, and failure states inherent to web tooling.\n\nAsk the LLM to attack your logic:\n\n> Now, switch roles. Act as a ruthless QA tester. Your goal is to break this skill.\n> Ask me 3 to 5 highly specific, challenging questions about edge cases, failure states, or missing fallbacks in the SKILL.md. Focus on:\n>\n> * What if `scripts\u002Fesbuild-optimizer.mjs` fails due to a legacy CommonJS dependency?\n> * What if the user's `angular.json` contains heavily customized Webpack builders (`@angular-builders\u002Fcustom-webpack`) that Vite doesn't support?\n> * Are there implicit assumptions I made about the user's Node environment?\n>\n> Do not fix these issues yet. Just ask me the numbered questions and wait for me to answer them.\n\n### Architecture Refinement\n\nLLMs often try to stuff large config files directly into the main prompt. Use this step to enforce progressive disclosure and shrink the token footprint.\n\nHave the LLM apply your fixes and restructure the skill:\n\n> Based on my answers to your edge-case questions, rewrite the SKILL.md file, strictly enforcing the Progressive Disclosure design pattern:\n>\n> 1. Keep the main `SKILL.md` strictly as a high-level set of steps using third-person imperative commands (e.g., Execute the esbuild script, Read the Vite config template).\n> 2. If there are dense rules, large `vite.config.ts` templates, or complex `angular.json` schemas currently in the file, remove them. Tell me to create a new file in `references\u002F` or `assets\u002F`, and replace the text in `SKILL.md` with a strict command to read that specific file only when needed.\n> 3. Add a dedicated Error Handling section at the bottom incorporating my answers about Webpack fallbacks and CommonJS resolution.\n","该项目提供了一套编写专业级代理技能的最佳实践指南，包括使用大型语言模型（LLMs）进行验证和保持简洁的上下文窗口。核心功能在于指导开发者如何构建结构化、易于发现且高效的技能文件，通过优化元数据如名称和描述来提高技能的可触发性，并采用渐进式披露策略以管理资源。技术特点强调了对`SKILL.md`文件大小的限制（少于500行），以及对目录结构的规范要求，确保代码与参考资料的有效组织。适用于需要创建高质量自动化代理技能的场景，特别是在开发涉及复杂逻辑处理或需频繁更新维护的项目时尤为有用。",2,"2026-06-11 03:49:27","high_star"]