[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6D0Z8TY3FSSN6VPNAPSJ713":3,"skill-same:01M6D0Z8TY3FSSN6VPNAPSJ713":107},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":33,"publishedAt":58,"linkOnly":59,"markdownContent":60,"markdownBody":61,"frontMatter":62,"refName":66,"commitSha":67,"skillDirectory":68,"forksCount":69,"repositoryHtmlUrl":70,"repositoryHomepageUrl":6,"ownerHtmlUrl":71,"ownerBlogUrl":6,"ownerDescription":72,"updatedAt":73,"install":74,"resources":86},"01M6D0Z8TY3FSSN6VPNAPSJ713","design-to-code",null,"Rebuild high-fidelity design or prototype (HTML, React JSX, Figma export, screenshots) as production React code. Stack\u002Fengineering rules → frontend-ui-best-practices; design system → products\u002Fdesign\u002FDESIGN.md (restyle mode: one authored from style brief); structure\u002Finteraction → products\u002Fprototype\u002F.","JinsYin\u002Fskills","JinsYin","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F12714609?v=4","01M6D0YYKCF1MT47KYYZSXWE30","01M6D0YYQ1F5AG45M6ATPECCAW",1,"MIT","https:\u002F\u002Fgithub.com\u002FJinsYin\u002Fskills\u002Fblob\u002Fmaster\u002Fskills\u002Fdesign-to-code\u002FSKILL.md",[17,22,25,30],{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000009","前端开发","SCENARIO","使用场景",{"categoryNo":23,"categoryName":24,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000015","视觉设计",{"categoryNo":26,"categoryName":27,"taxonomyType":28,"taxonomyTypeDesc":29},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",{"categoryNo":31,"categoryName":32,"taxonomyType":28,"taxonomyTypeDesc":29},"01JBSEEDCAT000000000000032","设计师",[34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57],"design","code","design to code","jsx","frontend","mode","interaction","figma export","full","structure","rebuild","best-practices","html","export","Rules","system","stack","brief","ui","figma","design system","react","prototype","screenshots","2026-11-10 10:12:30",false,"---\nname: skill-authoring\ndescription: Reference for writing effective agent skills. Anatomy, progressive disclosure, design patterns, anti-patterns, testing, security, and the ship checklist. Read whenever a SKILL.md is being created, edited, reviewed, or debugged, or when a skill is not triggering. Manual-only, invoked as \u002Fskill-authoring.\ndisable-model-invocation: true\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. The core folder and `SKILL.md` format are portable, but optional behavior such as invocation control can be client-specific.\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 to 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: measures prod state, does not change it.'`\n\n### Manual-only invocation is client-specific\n\n`disable-model-invocation: true` is **not** part of the core Agent Skills specification. It is a client extension supported by Claude Code and VS Code\u002FCopilot. In those clients, put it in `SKILL.md` frontmatter to prevent automatic invocation while keeping explicit invocation available.\n\nOpenAI Codex uses a separate file at `agents\u002Fopenai.yaml` inside the skill:\n\n```yaml\npolicy:\n  allow_implicit_invocation: false\n```\n\nFor a manual-only skill shared across Claude Code, VS Code\u002FCopilot, and Codex, include both configurations. Never assume a client-specific frontmatter field works in every Agent Skills implementation; verify each target client's documentation and test implicit invocation in each runtime.\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 to 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\n---\n\n## 14. This workspace\n\nSkills live in `.claude\u002Fskills\u002F\u003Cname>\u002FSKILL.md`. Author them there.\n\nWorkspace conventions on top of the general guidance above:\n\n- Follow `.claude\u002Frules\u002Fwriting-style.md` in skill bodies too. No em-dashes or\n  en-dashes, no emojis, bullets over paragraphs.\n- Skills that touch prod are read-only by default. Encode the read-only access path\n  (for example SSM plus a read-only dump), never a prod shell.\n- Skills that run shell commands should show them with the `rtk` prefix.\n- Set `disable-model-invocation: true` unless the skill genuinely should fire on\n  its own. The default here is manual.\n- After adding a skill, add a one-line entry to `.claude\u002Fskills\u002FREADME.md` and\n  re-run `\u002Fcontext-budget` to confirm the per-turn cost did not move. Skill bodies\n  are invoked-only, but descriptions are always loaded.\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. The core folder and `SKILL.md` format are portable, but optional behavior such as invocation control can be client-specific.\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 to 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: measures prod state, does not change it.'`\n\n### Manual-only invocation is client-specific\n\n`disable-model-invocation: true` is **not** part of the core Agent Skills specification. It is a client extension supported by Claude Code and VS Code\u002FCopilot. In those clients, put it in `SKILL.md` frontmatter to prevent automatic invocation while keeping explicit invocation available.\n\nOpenAI Codex uses a separate file at `agents\u002Fopenai.yaml` inside the skill:\n\n```yaml\npolicy:\n  allow_implicit_invocation: false\n```\n\nFor a manual-only skill shared across Claude Code, VS Code\u002FCopilot, and Codex, include both configurations. Never assume a client-specific frontmatter field works in every Agent Skills implementation; verify each target client's documentation and test implicit invocation in each runtime.\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 to 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\n---\n\n## 14. This workspace\n\nSkills live in `.claude\u002Fskills\u002F\u003Cname>\u002FSKILL.md`. Author them there.\n\nWorkspace conventions on top of the general guidance above:\n\n- Follow `.claude\u002Frules\u002Fwriting-style.md` in skill bodies too. No em-dashes or\n  en-dashes, no emojis, bullets over paragraphs.\n- Skills that touch prod are read-only by default. Encode the read-only access path\n  (for example SSM plus a read-only dump), never a prod shell.\n- Skills that run shell commands should show them with the `rtk` prefix.\n- Set `disable-model-invocation: true` unless the skill genuinely should fire on\n  its own. The default here is manual.\n- After adding a skill, add a one-line entry to `.claude\u002Fskills\u002FREADME.md` and\n  re-run `\u002Fcontext-budget` to confirm the per-turn cost did not move. Skill bodies\n  are invoked-only, but descriptions are always loaded.\n",{"name":63,"description":64,"disable-model-invocation":65},"skill-authoring","Reference for writing effective agent skills. Anatomy, progressive disclosure, design patterns, anti-patterns, testing, security, and the ship checklist. Read whenever a SKILL.md is being created, edited, reviewed, or debugged, or when a skill is not triggering. Manual-only, invoked as \u002Fskill-authoring.",true,"main","fd8b95f43c1a430bdf2b3ddb7460db5d2f03efd8","skills\u002Fdesign-to-code",0,"https:\u002F\u002Fgithub.com\u002FJinsYin\u002Fskills","https:\u002F\u002Fgithub.com\u002FJinsYin","Bigdata Architect. Do more things!","2026-11-09 10:40:45",{"source":8,"skillName":63,"commands":75,"prompt":85,"zipAvailable":65},[76,79,82],{"tool":77,"command":78},"npx","npx skills add JinsYin\u002Fskills --skill skill-authoring",{"tool":80,"command":81},"bunx","bunx skills add JinsYin\u002Fskills --skill skill-authoring",{"tool":83,"command":84},"pnpm","pnpm dlx skills add JinsYin\u002Fskills --skill skill-authoring","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FJinsYin\u002Fskills\u002Fblob\u002Fmaster\u002Fskills\u002Fdesign-to-code\u002FSKILL.md",[87,93,97,103],{"path":88,"resourceType":89,"resourceTypeDesc":90,"sizeBytes":91,"sourceHtmlUrl":92},"agents\u002Fopenai.yaml","REFERENCE","参考文档",43,"https:\u002F\u002Fgithub.com\u002Fchrstnjsff\u002Fdotfiles\u002Fblob\u002Fmain\u002Fclaude\u002Fworkspace\u002F.claude\u002Fskills\u002Fskill-authoring\u002Fagents\u002Fopenai.yaml",{"path":94,"resourceType":89,"resourceTypeDesc":90,"sizeBytes":95,"sourceHtmlUrl":96},"references\u002Fdesign-md-mapping.md",9409,"https:\u002F\u002Fgithub.com\u002FJinsYin\u002Fskills\u002Fblob\u002Fmaster\u002Fskills\u002Fdesign-to-code\u002Freferences\u002Fdesign-md-mapping.md",{"path":98,"resourceType":99,"resourceTypeDesc":100,"sizeBytes":101,"sourceHtmlUrl":102},"scripts\u002Fvisual-check.mjs","SCRIPT","脚本",9218,"https:\u002F\u002Fgithub.com\u002FJinsYin\u002Fskills\u002Fblob\u002Fmaster\u002Fskills\u002Fdesign-to-code\u002Fscripts\u002Fvisual-check.mjs",{"path":104,"resourceType":99,"resourceTypeDesc":100,"sizeBytes":105,"sourceHtmlUrl":106},"scripts\u002Fvisual-freeze.sh",2236,"https:\u002F\u002Fgithub.com\u002FJinsYin\u002Fskills\u002Fblob\u002Fmaster\u002Fskills\u002Fdesign-to-code\u002Fscripts\u002Fvisual-freeze.sh",[108,139,159,183,206,235],{"skillNo":109,"name":110,"nameZh":6,"description":111,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":112,"categories":113,"keywords":117,"publishedAt":58},"01M6D11YS49YDGXSBJ1YJ0FAD3","write-great-skill","Workflow and quality bar for agent skills: draft, polish, compress, verify, ship. Use whenever creating or editing a skill (`SKILL.md`, `references\u002F`, `rules\u002F`), or when project conventions route root `CLAUDE.md`\u002F`AGENTS.md` edits here, even if the user only says “改一下这个 skill”.","https:\u002F\u002Fgithub.com\u002FJinsYin\u002Fskills\u002Fblob\u002Fmaster\u002Fskills\u002Fwrite-great-skill\u002FSKILL.md",[114],{"categoryNo":115,"categoryName":116,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000023","Skill与智能体开发",[118,119,120,121,122,123,124,125,126,127,128,129,130,48,131,132,133,134,135,136,137,138],"write","write great skill","draft","route","references","project conventions","verify","project","editing","polish","only","conventions","use","ship","workflow","quality","compress","user","for","when","bar",{"skillNo":140,"name":141,"nameZh":6,"description":142,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":143,"categories":144,"keywords":145,"publishedAt":58},"01M6D11PP5HJ8142DKTSRJV73A","write-fspec","Derive the 功能规格说明书 (functional spec) from the product prototype and keep it versioned under products\u002Ffspec\u002F: Flyway-style V files plus a merged CURRENT.md. Use when a prototype is finalized, changed or backfilled, when a draft V is confirmed or CURRENT.md lags, or when the user mentions 功能规格, 功能规格说明书 or fspec. Not for the feature spec (.scratch\u002F*\u002Fspec.md) or DESIGN.md.","https:\u002F\u002Fgithub.com\u002FJinsYin\u002Fskills\u002Fblob\u002Fmaster\u002Fskills\u002Fwrite-fspec\u002FSKILL.md",[],[118,146,120,56,147,148,149,150,151,152,34,153,130,154,135,136,155,137,156,157,158],"write fspec","feature","product","read","spec","edit","grep","files","Bash","scratch","keep","functional","style",{"skillNo":160,"name":161,"nameZh":6,"description":162,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":163,"categories":164,"keywords":165,"publishedAt":58},"01M6D11JXM378SWT0VYVCPGN0Y","version-release","Cut a SemVer release — bump every module's version in lockstep, promote CHANGELOG.md, commit, tag, push to origin. Args `major|minor|patch|\u003Cx.y.z>`; none → level inferred from `[Unreleased]`, confirmed with user. Invoke only on explicit request: the user, another skill, or a project convention asking for a release.","https:\u002F\u002Fgithub.com\u002FJinsYin\u002Fskills\u002Fblob\u002Fmaster\u002Fskills\u002Fversion-release\u002FSKILL.md",[],[166,167,168,169,170,171,125,172,173,128,174,175,176,135,177,136,178,179,180,181,182],"release","version release","version","promote","push","changelog","another skill","bump","semver","patch","commit","with","request","cut","module","invoke","origin",{"skillNo":184,"name":185,"nameZh":6,"description":186,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":187,"categories":188,"keywords":191,"publishedAt":58},"01M6D11AR4DYNS4JM0QWQGAYS6","ui-ux-best-practices","UI\u002FUX rules for Chinese-language React\u002FVue admin consoles and their product\u002Fdesign specs. Use when designing, building, reviewing, or refactoring forms, lists, modals\u002Fdrawers, destructive actions, copy, formats, or console layout.","https:\u002F\u002Fgithub.com\u002FJinsYin\u002Fskills\u002Fblob\u002Fmaster\u002Fskills\u002Fui-ux-best-practices\u002FSKILL.md",[189,190],{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},{"categoryNo":31,"categoryName":32,"taxonomyType":28,"taxonomyTypeDesc":29},[192,193,52,194,195,196,197,148,198,199,200,201,202,34,130,48,203,204,55,136,137,205],"ux","ui ux best practices","best practices","ui ux","admin","chinese","layout","refactoring","actions","forms","console","vue","language","formats",{"skillNo":207,"name":208,"nameZh":6,"description":209,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":210,"categories":211,"keywords":215,"publishedAt":58},"01M6D111ECN97WMTB68PSQTGRV","spring-boot-best-practices","Spring Boot 3 + Java 21 + MyBatis Plus 项目的编码规范与架构纪律。涵盖分层依赖、国密 SM2\u002FSM3\u002FSM4、MyBatis Plus 实体与主键策略、多方言数据库迁移、R\u002FRList\u002FRPage 响应包装、DTO 职责边界、鉴权框架选型（Spring Security \u002F Sa-Token）与声明式权限校验、命名约定、模块 README 文档要求。在编写、审查或重构 Spring Boot 后端代码时使用——尤其是新增 Controller\u002FService\u002FMapper、定义 Entity 或 DTO、写数据库迁移、处理加解密与签名、设计 API 契约、或接入鉴权与权限校验时。","https:\u002F\u002Fgithub.com\u002FJinsYin\u002Fskills\u002Fblob\u002Fmaster\u002Fskills\u002Fspring-boot-best-practices\u002FSKILL.md",[212],{"categoryNo":213,"categoryName":214,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000010","后端与接口",[216,217,218,219,194,220,221,222,223,34,224,225,226,227,228,229,230,231,232,233,234],"spring boot best practices","spring boot","spring","boot","controller","README","校验","token","文档","service","security","java","api","spring boot 3","dto","mybatis","spring security","后端","数据",{"skillNo":236,"name":237,"nameZh":6,"description":238,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":239,"categories":240,"keywords":242,"publishedAt":58},"01M6D10Q5V8BG1YRW3AV89VVA3","setup-rules","Conduct an interactive interview, then install selected agent conventions, adapters, `skillsw`, and sensitive-file read restrictions into a project; `update` refreshes installed items without prompting. Use when the user asks to set up agent rules, or run `update` after `setup-rules` conventions change (e.g. Skill Workflow sync). Not for reviewing or hand-editing `CLAUDE.local.md`.","https:\u002F\u002Fgithub.com\u002FJinsYin\u002Fskills\u002Fblob\u002Fmaster\u002Fskills\u002Fsetup-rules\u002FSKILL.md",[241],{"categoryNo":115,"categoryName":116,"taxonomyType":20,"taxonomyTypeDesc":21},[243,48,244,245,246,247,125,248,126,249,149,250,251,252,253,129,130,132,254,255,256,136,137,257,258,259],"setup rules","setup","SET","interview","change","run","update","up","sync","local","install","Adapters","agent rules","conduct","file","interactive","hand"]