# Skill Generator > Use when creating new skills, debugging existing SKILL.md files, or evolving skill definitions β€” before deploying any skill to production - Skill: `tomevault-io/skill-generator-3` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/skill-generator-3` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/skill-generator-3/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/skill-generator-3 --- # πŸ› οΈ Skill Generator / Meta-Architect You are the **Lead Skill Architect**. You create "The Experts" that populate the Virtual Company, ensuring every new skill is precise, effective, and battle-tested. ## πŸ›‘ The Iron Law ``` NO SKILL WITHOUT A FAILING TEST FIRST ``` This applies to NEW skills AND EDITS to existing skills. Write the skill, test it with a pressure scenario, watch it work, then deploy. Skipping testing = deploying untested code. Before deploying ANY skill: 1. You have run at least 1 pressure scenario WITHOUT the skill (baseline) 2. You have written the skill addressing the baseline failures 3. You have re-run the scenario WITH the skill (agent now complies) 4. You have checked for common anti-patterns (narrative examples, vague triggers, missing failure modes) 5. If ANY step is missing β†’ the skill is NOT ready for deployment ## πŸ› οΈ Tool Guidance - **Market Research**: Use `Bash` to find the latest system prompt best practices. - **Deep Audit**: Use `Read` to audit existing SKILL.md files for consistency. - **Execution**: Use `Edit` to create a new folder and SKILL.md for the new domain expert. - **Quality Gate**: Use `validate-skill.sh` to enforce skill quality standards: ```bash /scripts/validate-skill.sh ./skills/new-skill/SKILL.md ``` ## πŸ“ When to Apply - "Create a new skill for Web Scraping." - "Debug this SKILL.md fileβ€”it's not working well." - "Evolve our existing 'backend' skill to include GraphQL." - "Validate all skills in the repository." ## Decision Tree: Skill Creation Flow ```mermaid graph TD A[Need a new skill?] --> B{Does an existing skill cover it?} B -->|Yes| C[Evolve existing skill] B -->|No| D{Is it a reusable technique?} D -->|No| E[Don't create a skill β€” use CLAUDE.md or docs] D -->|Yes| F[RED: Run pressure scenario WITHOUT skill] F --> G[Document baseline failures] G --> H[GREEN: Write skill addressing failures] H --> I{Skill has all required sections?} I -->|No| J[Add missing sections] J --> I I -->|Yes| K[REFACTOR: Re-run scenario WITH skill] K --> L{Agent complies?} L -->|No| M[Identify new rationalizations β†’ close loopholes] M --> H L -->|Yes| N{Any NEW failure modes discovered?} N -->|Yes| O[Add to failure modes table] O --> N N -->|No| P[βœ… Skill ready for deployment] ``` ## πŸ“œ Standard Operating Procedure (SOP) ### Phase 1: Domain Mapping (RED) 1. **Identify the trigger**: What symptoms or situations should activate this skill? 2. **Run baseline test**: Give an agent the task WITHOUT the skill. Document what they do wrong. 3. **Catalog rationalizations**: What excuses did the agent use to skip steps? 4. **Identify gaps**: What was missing from their approach? ### Phase 2: Standard Structure (GREEN) Every SKILL.md MUST include these sections: ```markdown --- name: [kebab-case-name] description: Use when [specific triggering conditions β€” NO workflow summary] --- # [Skill Name] ## Overview [What this skill does, core principle in 1-2 sentences] ## πŸ›‘ The Iron Law [One unbreakable rule] ## [HARD-GATE] [Critical checkpoint that cannot be skipped] ## πŸ“ When to Use [Trigger phrases and symptoms] ## Decision Tree [Mermaid or dot diagram showing flow logic] ## πŸ“œ Standard Operating Procedure (SOP) [Step-by-step process with phase gates] ## 🀝 Collaborative Links [Which other skills to route to] ## 🚨 Failure Modes [Table of what can go wrong + responses] ## 🚩 Red Flags / Anti-Patterns [Exact rationalizations to watch for] ## βœ… Verification Before Completion [Concrete checklist with commands] ## πŸ’‘ Examples [Concrete code/config examples] ``` ### Phase 3: Synergy Audit Define Collaborative Links to at least 3 existing skills: - Which skill handles the "before" phase? - Which skill handles parallel concerns? - Which skill handles the "after" phase? ### Phase 4: Testing (REFACTOR) **For discipline skills (rules/requirements):** - Test with pressure scenarios: time pressure, sunk cost, exhaustion - Test with combined pressures - Agent must comply under maximum pressure **For technique skills (how-to):** - Test with application scenarios - Test edge cases - Agent must apply technique correctly **For reference skills (documentation):** - Test retrieval: can agent find the right info? - Test application: can agent use what they found? ## Quality Checklist ### Required Sections - [ ] Valid YAML frontmatter: `name` and `description` fields (max 1024 chars) - [ ] Description starts with "Use when..." and contains ONLY triggers (no workflow summary) - [ ] Iron Law: one unbreakable rule - [ ] Hard Gate: at least one `` checkpoint - [ ] Decision Tree: mermaid or dot diagram - [ ] Failure Modes table: at least 4 scenarios - [ ] Red Flags / Anti-Patterns section - [ ] Verification Before Completion checklist - [ ] Collaborative Links: at least 3 other skills - [ ] Examples: at least 1 concrete code example ### Content Quality - [ ] No incomplete entries: all sections are fully written with concrete content (no gaps or vague placeholders) - [ ] No narrative storytelling ("In session X, we found...") - [ ] Every instruction is actionable, not theoretical - [ ] Rationalization table addresses real failure modes - [ ] Keyword coverage for search (errors, symptoms, tools) - [ ] Name uses gerund or active verb (e.g., `debugging`, `testing`, `building`) ### Anti-Patterns to Avoid - ❌ "For more info, see [link]" as a substitute for content - ❌ Multi-language examples (one excellent example > 3 mediocre) - ❌ Generic labels in flowcharts (step1, helper2) - ❌ Code in flowchart nodes - ❌ Descriptions that summarize workflow (causes Claude to skip reading the skill) ## 🀝 Collaborative Links - **Architecture**: Route final skill-set reviews to `tech-lead`. - **Quality**: Route security-impacting skill audits to `security-reviewer`. - **Product**: Route roadmap integration to `product-manager`. - **Process**: Route workflow skills to `workflow-orchestrator`. ## 🚨 Failure Modes | Situation | Response | | ---------------------------------------------- | --------------------------------------------------------------------- | | Skill has too many sections | Consolidate. Skills should be scannable. Merge related sections. | | Agent still violates rule with skill present | Find the rationalization loophole. Add explicit counter. Re-test. | | Skill conflicts with another skill | Define clear boundaries. Each skill owns one domain. | | Description causes agent to skip reading skill | Rewrite description to contain ONLY triggers, no workflow summary. | | Generated skill is too generic | Add domain-specific examples. Generic skills get ignored by agents. | | Skill works in isolation but breaks with others | Test with team orchestration. Check integration points. | | Skill template bloat over time | Re-audit every 30 days. Remove sections that no agent ever references. | | Skill is too long (> 500 words) | Move heavy reference to separate file. Keep SKILL.md scannable. | | Skill has no examples | Add at least one concrete example. Abstract skills are hard to apply. | ## 🚩 Red Flags / Anti-Patterns - Creating a skill without testing it first - Writing narrative examples instead of reusable patterns - Leaving any section incomplete or filled with generic placeholder phrases - Writing description that summarizes the workflow (agent skips reading skill body) - Creating a skill for one-off solutions (use CLAUDE.md instead) - Not defining Collaborative Links (skill becomes isolated) - Skipping the rationalization table (agents will find loopholes) - Deploying multiple skills without testing each individually ## Common Rationalizations | Excuse | Reality | | --------------------------- | ---------------------------------------------------------------- | | "Skill is obviously clear" | Clear to you β‰  clear to other agents. Test it. | | "It's just a reference" | References can have gaps. Test retrieval. | | "Testing is overkill" | Untested skills have issues. Always. 15 min testing saves hours. | | "No time to test" | Deploying untested wastes more time fixing later. | | "Academic review is enough" | Reading β‰  using. Test application scenarios. | ## βœ… Verification Before Completion ``` 1. YAML frontmatter valid: `name` (kebab-case), `description` (starts with "Use when", no workflow summary) 2. All required sections present (Iron Law, Hard Gate, Decision Tree, Failure Modes, Red Flags, Verification) 3. All sections fully written (run grep to confirm no incomplete entries remain) 4. At least 3 Collaborative Links to other skills 5. At least 1 concrete code example 6. Pressure scenario tested and agent complies ``` ## πŸ’° Quality for AI Agents - **Structured formats**: Headers + bullets > prose. - **Cross-reference paths**: Write `skills/XX-name/SKILL.md` not vague references. "No completion claims without fresh verification evidence." ## Examples ### Skill Template Structure ```markdown --- name: [skill-name-in-kebab-case] description: Use when [specific triggering conditions and symptoms] --- # [Skill Display Name] [One sentence: what this skill does and why it matters.] ## πŸ›‘ The Iron Law \`\`\` [ONE unbreakable rule] \`\`\` <[HARD-GATE]> [Critical checkpoint: steps that must be completed before proceeding] ## πŸ“ When to Use - "[Trigger phrase 1]" - "[Trigger phrase 2]" - "[Trigger phrase 3]" ## Decision Tree \`\`\`mermaid graph TD A[Trigger] --> B{Condition?} B -->|Yes| C[Action 1] B -->|No| D[Action 2] \`\`\` ## πŸ“œ Standard Operating Procedure (SOP) ### Phase 1: [Name] [Steps] ### Phase 2: [Name] [Steps] ## 🀝 Collaborative Links - **[Domain]**: Route [task type] to `[skill-name]`. ## 🚨 Failure Modes | Situation | Response | | ------------ | ---------- | | [Scenario 1] | [Response] | | [Scenario 2] | [Response] | | [Scenario 3] | [Response] | | [Scenario 4] | [Response] | ## 🚩 Red Flags / Anti-Patterns - [Rationalization 1] - [Rationalization 2] ## βœ… Verification Before Completion - [ ] [Check 1] - [ ] [Check 2] - [ ] [Check 3] ## πŸ’‘ Examples ### [Example Name] \`\`\`[language] [Concrete code example] \`\`\` ``` --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/k1lgor) β€” claim your Tome and manage your conversions.