[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M78BB38AX0YQQQJQCKRDEVJ5":3,"skill-same:01M78BB38AX0YQQQJQCKRDEVJ5":57},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":28,"ownerHtmlUrl":29,"ownerBlogUrl":30,"ownerDescription":31,"updatedAt":32,"install":33,"resources":46},"01M78BB38AX0YQQQJQCKRDEVJ5","effective-agent-skills",null,"How to write effective agent skills — what to do, what not to do, anatomy, progressive disclosure, design patterns, anti-patterns, testing, security. Read this whenever a skill (Claude Skill, Agent Skill, SKILL.md) is being created, edited, reviewed, or debugged. Use when the user says \"create a skill\", \"new skill\", \"update this skill\", \"improve a skill\", \"why isn't my skill triggering\", or anything else involving authoring or editing SKILL.md files.","Solizardking\u002Fskillhub-main","Solizardking","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F108096810?v=4","01M786KDB10AYV042N0F9BD5B5","Clawd","01M786NYYXSZK1D05WM8JQPC48",0,"MIT","https:\u002F\u002Fgithub.com\u002FSolizardking\u002Fskillhub-main\u002Fblob\u002Fmain\u002Fpublic\u002Fapi\u002Fskills\u002Fskill-authoring\u002Feffective-agent-skills\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: effective-agent-skills\ndescription: How to write effective agent skills — what to do, what not to do, anatomy, progressive disclosure, design patterns, anti-patterns, testing, security. Read this whenever a skill (Claude Skill, Agent Skill, SKILL.md) is being created, edited, reviewed, or debugged. Use when the user says \"create a skill\", \"new skill\", \"update this skill\", \"improve a skill\", \"why isn't my skill triggering\", or anything else involving authoring or editing SKILL.md files.\n---\n\n# Agent Skills: A Complete Guide\n\nA consolidated reference on what agent skills are, why they exist, how they work, and how to write effective ones.\n\n---\n\n## 1. What agent skills are\n\nAn Agent Skill is a folder containing a `SKILL.md` file (YAML frontmatter + markdown instructions), plus optional subfolders for scripts, references, and assets that the agent loads on demand.\n\n```\nmy-skill\u002F\n├── SKILL.md          # Required: metadata + instructions\n├── scripts\u002F          # Optional: executable code (CLIs, validators, helpers)\n├── references\u002F       # Optional: detailed docs loaded only when needed\n└── assets\u002F           # Optional: templates, fonts, static files\n```\n\nSkills are an open standard (agentskills.io), originally created by Anthropic and adopted by OpenAI Codex, Cursor, Gemini CLI, Microsoft Agent Framework, Google ADK, and 40+ other agent products. A skill written once works across all compatible agents.\n\n---\n\n## 2. Why this abstraction exists\n\nBase LLMs are generalists. Real work requires procedural knowledge, organizational context, and repeatable workflows. Every prior alternative had a failure mode:\n\n| Approach | Problem |\n|---|---|\n| Stuff it into the system prompt | Always loaded → context bloat at scale |\n| Re-paste instructions each session | No version control, no consistency |\n| Fine-tuning | Slow, expensive, opaque, vendor-locked |\n| MCP servers alone | Give the agent tools but no workflows for using them |\n\nSkills solve four problems at once:\n\n- **Context efficiency** — instructions load only when relevant\n- **Repeatability** — multi-step procedures become auditable workflows\n- **Composability** — multiple skills combine at runtime per task\n- **Portability** — same files work across vendors and surfaces\n\nMental model: skills are to LLMs what man pages, runbooks, and team handbooks are to engineers — reference material loaded into working memory only when the task demands it.\n\n---\n\n## 3. How they work — progressive disclosure\n\nThe architectural core. Three-stage loading:\n\n**Level 1 — Discovery (~100 tokens per skill, always in context):**\nOnly `name` + `description` from frontmatter are injected into the system prompt at startup. Agent knows the skill exists and when it applies. You can install dozens of skills with negligible overhead.\n\n**Level 2 — Activation (\u003C5,000 tokens, loaded on match):**\nWhen the user's request matches a skill's description, the agent reads the full `SKILL.md` body into context.\n\n**Level 3 — Execution (unbounded, on demand):**\nThe agent reads referenced files (`references\u002Ffoo.md`) or runs scripts (`scripts\u002Fvalidate.py`) only as needed. Scripts can execute without their source being loaded into context at all.\n\nThis is why bundled content has no practical limit. Files don't consume tokens until accessed.\n\n---\n\n## 4. SKILL.md anatomy\n\n```markdown\n---\nname: skill-name\ndescription: What this skill does AND when to use it. Include trigger phrases the user will say.\n---\n\n# Skill Name\n\n## Quick start\n[Minimal working example]\n\n## Workflow\n[Step-by-step procedure with checklists]\n\n## Output format\n[What the user\u002Fagent should expect back]\n\n## Advanced\n[Link to references\u002F for rarely-needed detail]\n```\n\nFrontmatter constraints:\n- `name` is lowercase, hyphens only, 1–64 chars, **exactly matches the parent folder name**\n- Avoid `\u003C` and `>` in frontmatter (they can inject into the system prompt)\n- Invalid YAML silently prevents loading\n- **Never put `: ` (colon + space) inside an unquoted `description`** — strict YAML parsers (e.g. Pi's) reject it as a nested mapping (\"Nested mappings are not allowed in compact mappings\"), even though lenient parsers (Claude Code) accept it. If the text needs a mid-sentence colon, single-quote the whole value and double any inner apostrophes: `description: 'Differentiator: finds gaps in David''s knowledge.'`\n\nOptional standard fields:\n- `disable-model-invocation: true` — stops the agent from auto-loading the skill based on the conversation; it can only be triggered manually (e.g. `\u002Fskill-name`). Now a standard Agent Skills spec field, so it works across spec-compliant clients (Claude Code, Copilot, etc.), not just Claude. Caveat: it prevents auto-invocation, but some clients (Claude Code, open bug) still inject the `description` into context, so it doesn't always save the discovery-level tokens. Use for manual-only utilities you don't want firing automatically.\n\n---\n\n## 5. Two design philosophies\n\nSkills tend to fall into one of two patterns. Both are valid; they solve different problems.\n\n### Pattern A — Capability primitives (tool wrappers)\nThe skill is a thin wrapper over a deterministic CLI or script. Logic lives in code. SKILL.md teaches the agent how to invoke it.\n\n- **Adds**: new capabilities (search, email, browser, API access)\n- **Reliability via**: shell tools, not prompts\n- **Typical length**: 30–80 lines, mostly command examples\n- **Use when**: the bottleneck is \"the agent can't do X\"\n\n### Pattern B — Process primitives (cognitive disciplines)\nThe skill encodes a methodology the agent should follow. Pure prompt engineering — no scripts needed.\n\n- **Adds**: structured workflows (TDD, code review, design alignment, debugging loops)\n- **Reliability via**: explicit procedure, checklists, validation loops\n- **Use when**: the bottleneck is \"the agent's output quality or process is bad\"\n\nA mature setup uses both. Pattern A gives the agent better tools. Pattern B gives it better methods for using them.\n\n---\n\n## 6. How to write effective skills — do this\n\n### Description as routing contract\nThe description is the only thing the agent sees before deciding to load the skill. If your skill doesn't trigger, the description is wrong 95% of the time, not the body.\n\nInclude three elements:\n1. **What** the skill does (one phrase)\n2. **When** to use it (trigger phrases, situations)\n3. **Differentiator** vs related skills (prevents routing conflicts)\n\nPattern: `\"X via Y. Use for [situations]. [Differentiator: no Z required \u002F faster than W \u002F handles edge case V].\"`\n\n**Never summarize the full workflow in the description.** If the description contains a step-by-step summary of *how* the skill works, the agent tends to follow that summary and skip loading the body. Describe *what* and *when*, never *how*. The description answers \"should I open this skill now?\" — not \"what are the steps?\"\n\n### Keep SKILL.md lean\n- Beyond a certain length, you're usually encoding logic that should be in a script or referenced file\n\n### Bash-first, prose-second\nConcrete command examples with inline comments beat prose explanations. The agent pattern-matches on syntax. Show, don't describe.\n\n### Push determinism into code\nAnything fragile, repetitive, or where variation is a bug → script. Use markdown only for tasks requiring judgment.\n\n### Match strictness to task fragility (degrees of freedom)\nScale instruction rigidity to how costly a wrong move is:\n- **Loose natural-language heuristics** when many approaches are valid (e.g. code review).\n- **Pseudocode or templates** when there's a preferred pattern but variation is acceptable (e.g. report format).\n- **Exact scripts and strict step lists** when the workflow is fragile, error-prone, or consistency-critical (e.g. migrations, document patching).\n\n### Build validation loops\nThe single biggest output quality improvement: state a verify → fix → re-verify loop explicitly.\n\n- Document skills: visual QA pass before delivery\n- Code skills: tests pass + zero type errors before completion\n- Data skills: schema validation before output\n\n### State-check before action\nDon't assume setup is done. Instruct the agent to verify state, then branch:\n```\nFirst check if X is configured: [command]\nIf not, walk the user through setup: [steps]\n```\n\n### Just-in-time loading with explicit pointers\nTell the agent exactly when to read each referenced file:\n```\nFor standard cases, follow the steps below.\nFor [specific edge case], read references\u002Fedge-cases.md first.\n```\n\n### Keep references one level deep\nLink referenced files directly from SKILL.md. Never build chains (SKILL.md → advanced.md → details.md → actual.md) — the agent may preview nested files only partially and miss critical instructions. Add a table of contents to any reference file longer than 100 lines.\n\n### Document output formats\nIf your script returns structured data, show the agent what it looks like. Enables reliable downstream parsing.\n\n### Defer to --help for completeness\nList the 80% common operations in SKILL.md. Tell the agent to run `tool --help` for the rest. Keeps SKILL.md small without losing functionality.\n\n### Compose primitives, don't bundle workflows\nOne skill = one capability or one discipline. Resist bundling concerns into \"the X workflow.\" Multiple small skills combine at runtime; one large skill is rigid.\n\n### Cite established principles when applicable\nIf your skill encodes a known engineering methodology (TDD, DDD, red-green-refactor), name the source. Gives the agent a coherent model to align with and gives users a way to verify the design.\n\n### Persistent artifacts for cross-session memory\nSkills can write to repo-level files (CONTEXT.md, ADRs, decision logs) that future agent sessions read. This is how you fight the \"agents have no memory\" problem at the architecture level.\n\n---\n\n## 7. What not to do — anti-patterns\n\n### Don't re-teach what the model already knows\nEvery line in SKILL.md should provide context the model doesn't already have. No Python syntax tutorials. No \"what is git.\" Challenge every paragraph.\n\n### Don't include human-facing docs\nNo README.md, no CHANGELOG.md, no INSTALLATION_GUIDE.md inside the skill folder. Skills are for agents.\n\n### Don't write vague descriptions\n- Bad: \"A helpful skill for documents\"\n- Good: \"Fill PDF form fields, extract form data, flatten completed PDFs. Use when the user mentions PDF forms, fillable forms, or programmatic field population.\"\n\n### Don't bundle library code\nIf you need a parsing library, install via npm\u002Fpip. Don't paste source into the skill.\n\n### Don't write monolithic mega-skills\nIf one skill does design + planning + implementation + testing + deployment, you've built a framework, not a skill. Split it.\n\n### Don't assume the agent will infer\nBe explicit about every step that matters.\n- Bad: \"Then deploy it.\"\n- Good: \"Run `npm run deploy:staging` and wait for HTTP 200 from \u002Fhealthz before reporting success.\"\n\n### Don't write style-only variants\nA skill that just changes tone or formatting belongs in user preferences or a system prompt, not a skill.\n\n### Don't ignore failure modes\nFor every workflow step that can fail, document what failure looks like and what to do. Happy-path-only skills break in production.\n\n### Don't include time-sensitive information\n\"As of Q4 2024...\" rots fast. Fetch live data via script or omit.\n\n### Don't use absolute paths\nAlways relative. Forward slashes regardless of OS. Use runtime placeholders for skill-directory references.\n\n### Don't trust unfamiliar skills\nSkills can execute arbitrary code and steer agent behavior. A malicious skill is a data exfiltration vector. Audit `scripts\u002F` for unexpected network calls, file access outside expected scope, or hidden instructions in references. Watch for typosquatted skill names. Sandbox execution environments.\n\n---\n\n## 8. Authoring workflow\n\n1. **Identify the gap.** Run your agent on real tasks. Where does it consistently fail or need re-prompting? That's a skill candidate.\n2. **Decide the pattern.** Capability primitive (need new tools) or process primitive (need better methodology)?\n3. **Draft the description first.** What + when + differentiator. Read it back: would the agent know when to fire it?\n4. **Write the smallest body that works.** Add only when testing reveals gaps.\n5. **Move detail to references\u002F once SKILL.md grows too long.**\n6. **Test triggering.** Ask the agent something the skill should handle without invoking it explicitly. If it doesn't fire, fix the description.\n7. **Test execution.** Invoke explicitly. If output is wrong, fix the body.\n8. **Adversarial test.** Have another LLM ask: \"What edge cases break this skill?\" Patch the gaps.\n9. **Version control.** Treat skills as code. Tag, branch, review.\n\n---\n\n## 9. Testing and debugging\n\n- **\"Which skill did you use?\"** — ask the agent post-task. Fastest routing debug.\n- **Routing fails → description problem.** Add specific trigger phrases.\n- **Execution fails → body problem.** Add explicit steps, examples, or validation.\n- **Skills snapshot at session start.** Edits during a session require a restart.\n- **Test against the weakest model you'll deploy on.** Stronger models forgive vague skills; weaker models expose them.\n- **Run an eval suite.** A handful of representative prompts that should and shouldn't trigger the skill, with expected outputs.\n\n---\n\n## 10. Composition\n\nSkills compose at runtime — the agent loads multiple skills as needed for a single task. Design for this:\n\n- **One skill = one concern.** Resist bundling.\n- **Define interfaces between skills.** If skill A produces artifacts that skill B consumes, document the shape.\n- **Use a repo-level config substrate.** A shared file (e.g., AGENTS.md, CONTEXT.md, settings.json) that multiple skills read and write coordinates them without explicit handoffs.\n- **Loops over menus.** A coordinated set of skills forming a workflow (align → spec → build → verify → refactor) drives adoption far better than an unrelated catalog of capabilities.\n\n---\n\n## 11. Security checklist\n\nBefore installing any third-party skill:\n\n- Read every file in the folder\n- Audit `scripts\u002F` for outbound network calls, file access outside expected scope, command execution\n- Check references for prompt injection (\"ignore previous instructions...\")\n- Verify the skill name isn't typosquatting a popular one\n- Run in a sandboxed environment first\n- Pin to a specific version\u002Fcommit, not `latest`\n\n---\n\n## 12. Ship checklist\n\nBefore publishing a skill:\n\n- [ ] Frontmatter `name` matches folder name\n- [ ] Description includes what + when + differentiator\n- [ ] Description includes likely user trigger phrases\n- [ ] No human-facing docs inside the skill folder\n- [ ] No time-sensitive information\n- [ ] Relative paths only\n- [ ] State-check before action where applicable\n- [ ] Validation loop documented\n- [ ] Output format documented if relevant\n- [ ] Tested with weak and strong models\n- [ ] Tested for both correct triggering and correct execution\n- [ ] Skill does one thing\n- [ ] Composes cleanly with related skills\n- [ ] Version controlled\n\n---\n\n## 13. First principles, compressed\n\n1. **The description routes; the body executes.** Get both right independently.\n2. **Tokens are scarce; files are cheap.** Push detail out of context until it's needed.\n3. **Determinism comes from code; judgment comes from prompts.** Put each in its right place.\n4. **One skill, one concern.** Composition beats bundling.\n5. **Agents have no memory.** Use persistent artifacts to give them one.\n6. **The model knows a lot.** Don't re-teach. Only add what's missing.\n7. **Validate before completing.** Self-correction loops dominate output quality.\n8. **Skills are code.** Version, test, audit, and review them as such.\n","# Agent Skills: A Complete Guide\n\nA consolidated reference on what agent skills are, why they exist, how they work, and how to write effective ones.\n\n---\n\n## 1. What agent skills are\n\nAn Agent Skill is a folder containing a `SKILL.md` file (YAML frontmatter + markdown instructions), plus optional subfolders for scripts, references, and assets that the agent loads on demand.\n\n```\nmy-skill\u002F\n├── SKILL.md          # Required: metadata + instructions\n├── scripts\u002F          # Optional: executable code (CLIs, validators, helpers)\n├── references\u002F       # Optional: detailed docs loaded only when needed\n└── assets\u002F           # Optional: templates, fonts, static files\n```\n\nSkills are an open standard (agentskills.io), originally created by Anthropic and adopted by OpenAI Codex, Cursor, Gemini CLI, Microsoft Agent Framework, Google ADK, and 40+ other agent products. A skill written once works across all compatible agents.\n\n---\n\n## 2. Why this abstraction exists\n\nBase LLMs are generalists. Real work requires procedural knowledge, organizational context, and repeatable workflows. Every prior alternative had a failure mode:\n\n| Approach | Problem |\n|---|---|\n| Stuff it into the system prompt | Always loaded → context bloat at scale |\n| Re-paste instructions each session | No version control, no consistency |\n| Fine-tuning | Slow, expensive, opaque, vendor-locked |\n| MCP servers alone | Give the agent tools but no workflows for using them |\n\nSkills solve four problems at once:\n\n- **Context efficiency** — instructions load only when relevant\n- **Repeatability** — multi-step procedures become auditable workflows\n- **Composability** — multiple skills combine at runtime per task\n- **Portability** — same files work across vendors and surfaces\n\nMental model: skills are to LLMs what man pages, runbooks, and team handbooks are to engineers — reference material loaded into working memory only when the task demands it.\n\n---\n\n## 3. How they work — progressive disclosure\n\nThe architectural core. Three-stage loading:\n\n**Level 1 — Discovery (~100 tokens per skill, always in context):**\nOnly `name` + `description` from frontmatter are injected into the system prompt at startup. Agent knows the skill exists and when it applies. You can install dozens of skills with negligible overhead.\n\n**Level 2 — Activation (\u003C5,000 tokens, loaded on match):**\nWhen the user's request matches a skill's description, the agent reads the full `SKILL.md` body into context.\n\n**Level 3 — Execution (unbounded, on demand):**\nThe agent reads referenced files (`references\u002Ffoo.md`) or runs scripts (`scripts\u002Fvalidate.py`) only as needed. Scripts can execute without their source being loaded into context at all.\n\nThis is why bundled content has no practical limit. Files don't consume tokens until accessed.\n\n---\n\n## 4. SKILL.md anatomy\n\n```markdown\n---\nname: skill-name\ndescription: What this skill does AND when to use it. Include trigger phrases the user will say.\n---\n\n# Skill Name\n\n## Quick start\n[Minimal working example]\n\n## Workflow\n[Step-by-step procedure with checklists]\n\n## Output format\n[What the user\u002Fagent should expect back]\n\n## Advanced\n[Link to references\u002F for rarely-needed detail]\n```\n\nFrontmatter constraints:\n- `name` is lowercase, hyphens only, 1–64 chars, **exactly matches the parent folder name**\n- Avoid `\u003C` and `>` in frontmatter (they can inject into the system prompt)\n- Invalid YAML silently prevents loading\n- **Never put `: ` (colon + space) inside an unquoted `description`** — strict YAML parsers (e.g. Pi's) reject it as a nested mapping (\"Nested mappings are not allowed in compact mappings\"), even though lenient parsers (Claude Code) accept it. If the text needs a mid-sentence colon, single-quote the whole value and double any inner apostrophes: `description: 'Differentiator: finds gaps in David''s knowledge.'`\n\nOptional standard fields:\n- `disable-model-invocation: true` — stops the agent from auto-loading the skill based on the conversation; it can only be triggered manually (e.g. `\u002Fskill-name`). Now a standard Agent Skills spec field, so it works across spec-compliant clients (Claude Code, Copilot, etc.), not just Claude. Caveat: it prevents auto-invocation, but some clients (Claude Code, open bug) still inject the `description` into context, so it doesn't always save the discovery-level tokens. Use for manual-only utilities you don't want firing automatically.\n\n---\n\n## 5. Two design philosophies\n\nSkills tend to fall into one of two patterns. Both are valid; they solve different problems.\n\n### Pattern A — Capability primitives (tool wrappers)\nThe skill is a thin wrapper over a deterministic CLI or script. Logic lives in code. SKILL.md teaches the agent how to invoke it.\n\n- **Adds**: new capabilities (search, email, browser, API access)\n- **Reliability via**: shell tools, not prompts\n- **Typical length**: 30–80 lines, mostly command examples\n- **Use when**: the bottleneck is \"the agent can't do X\"\n\n### Pattern B — Process primitives (cognitive disciplines)\nThe skill encodes a methodology the agent should follow. Pure prompt engineering — no scripts needed.\n\n- **Adds**: structured workflows (TDD, code review, design alignment, debugging loops)\n- **Reliability via**: explicit procedure, checklists, validation loops\n- **Use when**: the bottleneck is \"the agent's output quality or process is bad\"\n\nA mature setup uses both. Pattern A gives the agent better tools. Pattern B gives it better methods for using them.\n\n---\n\n## 6. How to write effective skills — do this\n\n### Description as routing contract\nThe description is the only thing the agent sees before deciding to load the skill. If your skill doesn't trigger, the description is wrong 95% of the time, not the body.\n\nInclude three elements:\n1. **What** the skill does (one phrase)\n2. **When** to use it (trigger phrases, situations)\n3. **Differentiator** vs related skills (prevents routing conflicts)\n\nPattern: `\"X via Y. Use for [situations]. [Differentiator: no Z required \u002F faster than W \u002F handles edge case V].\"`\n\n**Never summarize the full workflow in the description.** If the description contains a step-by-step summary of *how* the skill works, the agent tends to follow that summary and skip loading the body. Describe *what* and *when*, never *how*. The description answers \"should I open this skill now?\" — not \"what are the steps?\"\n\n### Keep SKILL.md lean\n- Beyond a certain length, you're usually encoding logic that should be in a script or referenced file\n\n### Bash-first, prose-second\nConcrete command examples with inline comments beat prose explanations. The agent pattern-matches on syntax. Show, don't describe.\n\n### Push determinism into code\nAnything fragile, repetitive, or where variation is a bug → script. Use markdown only for tasks requiring judgment.\n\n### Match strictness to task fragility (degrees of freedom)\nScale instruction rigidity to how costly a wrong move is:\n- **Loose natural-language heuristics** when many approaches are valid (e.g. code review).\n- **Pseudocode or templates** when there's a preferred pattern but variation is acceptable (e.g. report format).\n- **Exact scripts and strict step lists** when the workflow is fragile, error-prone, or consistency-critical (e.g. migrations, document patching).\n\n### Build validation loops\nThe single biggest output quality improvement: state a verify → fix → re-verify loop explicitly.\n\n- Document skills: visual QA pass before delivery\n- Code skills: tests pass + zero type errors before completion\n- Data skills: schema validation before output\n\n### State-check before action\nDon't assume setup is done. Instruct the agent to verify state, then branch:\n```\nFirst check if X is configured: [command]\nIf not, walk the user through setup: [steps]\n```\n\n### Just-in-time loading with explicit pointers\nTell the agent exactly when to read each referenced file:\n```\nFor standard cases, follow the steps below.\nFor [specific edge case], read references\u002Fedge-cases.md first.\n```\n\n### Keep references one level deep\nLink referenced files directly from SKILL.md. Never build chains (SKILL.md → advanced.md → details.md → actual.md) — the agent may preview nested files only partially and miss critical instructions. Add a table of contents to any reference file longer than 100 lines.\n\n### Document output formats\nIf your script returns structured data, show the agent what it looks like. Enables reliable downstream parsing.\n\n### Defer to --help for completeness\nList the 80% common operations in SKILL.md. Tell the agent to run `tool --help` for the rest. Keeps SKILL.md small without losing functionality.\n\n### Compose primitives, don't bundle workflows\nOne skill = one capability or one discipline. Resist bundling concerns into \"the X workflow.\" Multiple small skills combine at runtime; one large skill is rigid.\n\n### Cite established principles when applicable\nIf your skill encodes a known engineering methodology (TDD, DDD, red-green-refactor), name the source. Gives the agent a coherent model to align with and gives users a way to verify the design.\n\n### Persistent artifacts for cross-session memory\nSkills can write to repo-level files (CONTEXT.md, ADRs, decision logs) that future agent sessions read. This is how you fight the \"agents have no memory\" problem at the architecture level.\n\n---\n\n## 7. What not to do — anti-patterns\n\n### Don't re-teach what the model already knows\nEvery line in SKILL.md should provide context the model doesn't already have. No Python syntax tutorials. No \"what is git.\" Challenge every paragraph.\n\n### Don't include human-facing docs\nNo README.md, no CHANGELOG.md, no INSTALLATION_GUIDE.md inside the skill folder. Skills are for agents.\n\n### Don't write vague descriptions\n- Bad: \"A helpful skill for documents\"\n- Good: \"Fill PDF form fields, extract form data, flatten completed PDFs. Use when the user mentions PDF forms, fillable forms, or programmatic field population.\"\n\n### Don't bundle library code\nIf you need a parsing library, install via npm\u002Fpip. Don't paste source into the skill.\n\n### Don't write monolithic mega-skills\nIf one skill does design + planning + implementation + testing + deployment, you've built a framework, not a skill. Split it.\n\n### Don't assume the agent will infer\nBe explicit about every step that matters.\n- Bad: \"Then deploy it.\"\n- Good: \"Run `npm run deploy:staging` and wait for HTTP 200 from \u002Fhealthz before reporting success.\"\n\n### Don't write style-only variants\nA skill that just changes tone or formatting belongs in user preferences or a system prompt, not a skill.\n\n### Don't ignore failure modes\nFor every workflow step that can fail, document what failure looks like and what to do. Happy-path-only skills break in production.\n\n### Don't include time-sensitive information\n\"As of Q4 2024...\" rots fast. Fetch live data via script or omit.\n\n### Don't use absolute paths\nAlways relative. Forward slashes regardless of OS. Use runtime placeholders for skill-directory references.\n\n### Don't trust unfamiliar skills\nSkills can execute arbitrary code and steer agent behavior. A malicious skill is a data exfiltration vector. Audit `scripts\u002F` for unexpected network calls, file access outside expected scope, or hidden instructions in references. Watch for typosquatted skill names. Sandbox execution environments.\n\n---\n\n## 8. Authoring workflow\n\n1. **Identify the gap.** Run your agent on real tasks. Where does it consistently fail or need re-prompting? That's a skill candidate.\n2. **Decide the pattern.** Capability primitive (need new tools) or process primitive (need better methodology)?\n3. **Draft the description first.** What + when + differentiator. Read it back: would the agent know when to fire it?\n4. **Write the smallest body that works.** Add only when testing reveals gaps.\n5. **Move detail to references\u002F once SKILL.md grows too long.**\n6. **Test triggering.** Ask the agent something the skill should handle without invoking it explicitly. If it doesn't fire, fix the description.\n7. **Test execution.** Invoke explicitly. If output is wrong, fix the body.\n8. **Adversarial test.** Have another LLM ask: \"What edge cases break this skill?\" Patch the gaps.\n9. **Version control.** Treat skills as code. Tag, branch, review.\n\n---\n\n## 9. Testing and debugging\n\n- **\"Which skill did you use?\"** — ask the agent post-task. Fastest routing debug.\n- **Routing fails → description problem.** Add specific trigger phrases.\n- **Execution fails → body problem.** Add explicit steps, examples, or validation.\n- **Skills snapshot at session start.** Edits during a session require a restart.\n- **Test against the weakest model you'll deploy on.** Stronger models forgive vague skills; weaker models expose them.\n- **Run an eval suite.** A handful of representative prompts that should and shouldn't trigger the skill, with expected outputs.\n\n---\n\n## 10. Composition\n\nSkills compose at runtime — the agent loads multiple skills as needed for a single task. Design for this:\n\n- **One skill = one concern.** Resist bundling.\n- **Define interfaces between skills.** If skill A produces artifacts that skill B consumes, document the shape.\n- **Use a repo-level config substrate.** A shared file (e.g., AGENTS.md, CONTEXT.md, settings.json) that multiple skills read and write coordinates them without explicit handoffs.\n- **Loops over menus.** A coordinated set of skills forming a workflow (align → spec → build → verify → refactor) drives adoption far better than an unrelated catalog of capabilities.\n\n---\n\n## 11. Security checklist\n\nBefore installing any third-party skill:\n\n- Read every file in the folder\n- Audit `scripts\u002F` for outbound network calls, file access outside expected scope, command execution\n- Check references for prompt injection (\"ignore previous instructions...\")\n- Verify the skill name isn't typosquatting a popular one\n- Run in a sandboxed environment first\n- Pin to a specific version\u002Fcommit, not `latest`\n\n---\n\n## 12. Ship checklist\n\nBefore publishing a skill:\n\n- [ ] Frontmatter `name` matches folder name\n- [ ] Description includes what + when + differentiator\n- [ ] Description includes likely user trigger phrases\n- [ ] No human-facing docs inside the skill folder\n- [ ] No time-sensitive information\n- [ ] Relative paths only\n- [ ] State-check before action where applicable\n- [ ] Validation loop documented\n- [ ] Output format documented if relevant\n- [ ] Tested with weak and strong models\n- [ ] Tested for both correct triggering and correct execution\n- [ ] Skill does one thing\n- [ ] Composes cleanly with related skills\n- [ ] Version controlled\n\n---\n\n## 13. First principles, compressed\n\n1. **The description routes; the body executes.** Get both right independently.\n2. **Tokens are scarce; files are cheap.** Push detail out of context until it's needed.\n3. **Determinism comes from code; judgment comes from prompts.** Put each in its right place.\n4. **One skill, one concern.** Composition beats bundling.\n5. **Agents have no memory.** Use persistent artifacts to give them one.\n6. **The model knows a lot.** Don't re-teach. Only add what's missing.\n7. **Validate before completing.** Self-correction loops dominate output quality.\n8. **Skills are code.** Version, test, audit, and review them as such.\n",{"name":5,"description":7},"main","be3de0244dc1a57e323d8160787ebb40fb64930e","public\u002Fapi\u002Fskills\u002Fskill-authoring\u002Feffective-agent-skills","https:\u002F\u002Fgithub.com\u002FSolizardking\u002Fskillhub-main","https:\u002F\u002Fskills.x402.wtf","https:\u002F\u002Fgithub.com\u002FSolizardking","https:\u002F\u002Fmusebook.trade","Got a mile high and never came down","2026-10-08 23:20:13",{"source":8,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add Solizardking\u002Fskillhub-main --skill effective-agent-skills",{"tool":39,"command":40},"bunx","bunx skills add Solizardking\u002Fskillhub-main --skill effective-agent-skills",{"tool":42,"command":43},"pnpm","pnpm dlx skills add Solizardking\u002Fskillhub-main --skill effective-agent-skills","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FSolizardking\u002Fskillhub-main\u002Fblob\u002Fmain\u002Fpublic\u002Fapi\u002Fskills\u002Fskill-authoring\u002Feffective-agent-skills\u002FSKILL.md",true,[47,53],{"path":48,"resourceType":49,"resourceTypeDesc":50,"sizeBytes":51,"sourceHtmlUrl":52},"metadata.json","REFERENCE","参考文档",688,"https:\u002F\u002Fgithub.com\u002FSolizardking\u002Fskillhub-main\u002Fblob\u002Fmain\u002Fpublic\u002Fapi\u002Fskills\u002Fskill-authoring\u002Feffective-agent-skills\u002Fmetadata.json",{"path":54,"resourceType":49,"resourceTypeDesc":50,"sizeBytes":55,"sourceHtmlUrl":56},"verification.json",1391,"https:\u002F\u002Fgithub.com\u002FSolizardking\u002Fskillhub-main\u002Fblob\u002Fmain\u002Fpublic\u002Fapi\u002Fskills\u002Fskill-authoring\u002Feffective-agent-skills\u002Fverification.json",[58,65,72,79,86,94],{"skillNo":59,"name":60,"nameZh":6,"description":61,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":62,"categories":63,"keywords":64,"publishedAt":19},"01M78E0TGCAMNPS207BA3G07S7","zkrouter","Self-hosted OpenAI-compatible LLM router — smart tier-based routing, ZK-stamped routing decisions, mode overrides, free OpenRouter at install via the Birth bot. Save 60-80% on inference costs by routing to the cheapest capable model across 12+ OpenRouter models.","https:\u002F\u002Fgithub.com\u002FSolizardking\u002Fskillhub-main\u002Fblob\u002Fmain\u002Fskills\u002Fzkrouter\u002FSKILL.md",[],[],{"skillNo":66,"name":67,"nameZh":6,"description":68,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":69,"categories":70,"keywords":71,"publishedAt":19},"01M78E0R1Z8BDT6EDTHY17MTNB","zk","For custom ZK Solana programs and privacy-preserving applications to prevent double spending. Guide to integrate rent-free nullifier PDAs for double-spend prevention.","https:\u002F\u002Fgithub.com\u002FSolizardking\u002Fskillhub-main\u002Fblob\u002Fmain\u002Fskills\u002Fzk\u002FSKILL.md",[],[],{"skillNo":73,"name":74,"nameZh":6,"description":75,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":76,"categories":77,"keywords":78,"publishedAt":19},"01M78E0P3ZTZ1YWF8MD5MM23QE","zk-omni-messaging","Zero-knowledge omnichain messaging between Robinhood Chain and Solana using CheshireZkOmniMessenger (msgType 4) with nullifier anti-replay and the zk-omni-relayer service.","https:\u002F\u002Fgithub.com\u002FSolizardking\u002Fskillhub-main\u002Fblob\u002Fmain\u002Fskills\u002Fzk-omni-messaging\u002FSKILL.md",[],[],{"skillNo":80,"name":81,"nameZh":6,"description":82,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":83,"categories":84,"keywords":85,"publishedAt":19},"01M78E0JXZ2PNB1896VXAGDBWD","zerion-wallet-data","Use when the user asks to check a wallet's portfolio, token balances, DeFi positions, PnL, transaction history, or NFTs. Provides interpreted on-chain data across 40+ EVM chains and Solana via x402 pay-per-request or API key — no raw RPC decoding needed.","https:\u002F\u002Fgithub.com\u002FSolizardking\u002Fskillhub-main\u002Fblob\u002Fmain\u002Fskills\u002Fzerion-wallet-data\u002FSKILL.md",[],[],{"skillNo":87,"name":88,"nameZh":6,"description":89,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":90,"sourceHtmlUrl":91,"categories":92,"keywords":93,"publishedAt":19},"01M78E0G14FH9GRRTQYMKD5E59","youtube-clipper","YouTube 视频智能剪辑工具。下载视频和字幕，AI 分析生成精细章节（几分钟级别）， 用户选择片段后自动剪辑、翻译字幕为中英双语、烧录字幕到视频，并生成总结文案。 使用场景：当用户需要剪辑 YouTube 视频、生成短视频片段、制作双语字幕版本时。 关键词：视频剪辑、YouTube、字幕翻译、双语字幕、视频下载、clip video","https:\u002F\u002Fgithub.com\u002FSolizardking\u002Fskillhub-main\u002Fblob\u002Fmain\u002Fskills\u002Fyoutube-clipper\u002FLICENSE","https:\u002F\u002Fgithub.com\u002FSolizardking\u002Fskillhub-main\u002Fblob\u002Fmain\u002Fskills\u002Fyoutube-clipper\u002FSKILL.md",[],[],{"skillNo":95,"name":96,"nameZh":6,"description":97,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":98,"categories":99,"keywords":100,"publishedAt":19},"01M78E0C2ZYA99CFFDNB7ZMK5S","yield-optimization","Multi-chain yield optimization via yield.xyz (StakeKit). Discover 2,988+ yield opportunities across 75+ blockchains, build deposit\u002Fwithdrawal transactions with shell scripts, and sign them with a MoonPay wallet. Use when the user wants to earn yield, find the best lending or staking rate, enter\u002Fexit a position, or check portfolio balances.","https:\u002F\u002Fgithub.com\u002FSolizardking\u002Fskillhub-main\u002Fblob\u002Fmain\u002Fskills\u002Fyield-optimization\u002FSKILL.md",[],[]]