# Refine Skill Design > Audit and refactor existing SKILLs to meet spec compliance, repository asset boundaries, tool adaptation requirements, and LLM best practices. - Skill: `nesnilnehc/refine-skill-design` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add nesnilnehc/refine-skill-design` - Raw SKILL.md: https://api.skillmd.com/api/skills/nesnilnehc/refine-skill-design/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - License: MIT - Author: nesnilnehc (https://skillmd.com/u/nesnilnehc) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/nesnilnehc/refine-skill-design --- # Skill: Refine Skill Design ## Purpose As a "meta-skill", this skill **reviews and refactors** AI capability definitions that are still in draft form. It applies an advanced prompt-engineering lens to raise logical robustness, scenario coverage, and instruction adherence, so that every capability meets LLM best practices. --- ## Core Objective **Primary goal**: produce a reviewed and refactored skill document that meets spec compliance, the repository's asset boundaries, and LLM best practices. **Success criteria** (all must be met): 1. ✅ **Structurally compatible**: the skill follows the standard template (YAML, purpose, use cases, behavior, input and output, restrictions, self-check, examples) 2. ✅ **Logic is clear**: the input → behavior → output chain is clear and unambiguous 3. ✅ **Constraints defined**: the restrictions section covers the failure modes common to the domain 4. ✅ **Asset boundaries clear**: the Skill embeds no authoritative definition that belongs to a Spec / Protocol / Rule; where needed it references one instead, or proposes a split 5. ✅ **Execution adaptation explicit**: external tools, MCP tools, the runtime environment, and missing capabilities all have a discovery, mapping, and failure-handling path 6. ✅ **Repository contract compliant**: obeys `AGENTS.md`, the terminology definitions, and the external-link, language, and asset-priority rules 7. ✅ **Examples are thorough**: at least 2 examples, one of them an edge case or a challenging scenario 8. ✅ **Changes recorded**: the diff summary lists every change together with its section, description, and reason 9. ✅ **Version proposed**: a SemVer proposal with its rationale **Acceptance test**: can an AI Agent apply this refined skill consistently across different environments, with no ambiguity? --- ## Scope Boundaries **This skill does**: - Review an existing skill draft for quality and compliance - Refactor the skill's structure and content to meet the spec - Audit the Skill / Spec / Protocol / Rule boundary, to avoid burying a structural contract, an interaction protocol, or a single-point rule inside a Skill - Audit the tool adaptation layer, so that discovery, capability mapping, and missing-tool handling for MCP / CLI / API tools are executable - Audit the repository's local contract, so the optimised Skill obeys `AGENTS.md` and the local terminology definitions - Raise logical clarity and instruction precision - Add the missing sections or strengthen the weak areas - Provide the diff summary and a version proposal **This skill does not do**: - Generate the full skeleton of a new Skill from scratch - Install an external Skill or initialiser at runtime - Decide, in the maintainer's place, the licence and vendoring scope of an externally derived Skill - Generate the project docs/ structure (taken on by the AgentFabric runtime or a human) **Handoff point**: once the SKILL is refined and the diff summary is delivered, hand off to the user for review and a version-control commit. --- ## Use Cases - **New skill onboarding**: an expert review after an agent has drafted a new skill. - **Quality repair**: when a skill behaves inconsistently on a new model, adjust the logic and strengthen the examples. - **Consistency review**: check that a new skill matches the tag system and naming in INDEX.md; make sure `description`, `tags`, and `triggers` are enough to support semantic discovery. - **Upgrade**: turn a plain "formatter" into a full agent capability with an interaction policy and error handling. **Scope**: this skill is for **reviewing and refactoring an existing skill**, not for creating one from scratch. A new Skill is handled separately, through the repository contribution process and the agentskills.io spec; an external skill-creator must not be installed at runtime for that purpose. --- ## Behavior ### Meta-Audit Model 1. **Intent**: is the purpose specific enough? Avoid vague terms such as "assistant" or "utility". 2. **Logic**: do input → behavior → output form a clear chain? 3. **Constraints**: do the restrictions cover the most common failure modes in the domain? 4. **Examples**: do the examples run from simple to complex and include at least one edge case? 5. **Interaction policy** (spec §4.3): does the behavior state the defaults, the choice options, and which items need user confirmation? Defaults first, then choices, then context inference. 6. **Asset boundary**: is the Skill defining the structure of a thing (Spec), a multi-party message sequence (Protocol), or an atomic prohibition (Rule)? If so, keep the execution orchestration and turn the authoritative definition into a reference to an existing asset, or name where the split belongs. 7. **Execution adaptation**: does the Skill depend on MCP / CLI / API / an external service? If it does, does it state how to discover the available tools, build the capability mapping, handle a missing tool, and avoid hard-coding a tool name that does not exist? 8. **Repository contract**: when optimising inside the AI Cortex repository, `AGENTS.md`, `docs/architecture/terminology.md`, and `skills/SOURCES.yaml` must be read and applied; external HTTP/HTTPS links must not be fetched by default, and a Skill must not be installed at runtime. A pinned upstream version can be read only where an externally derived copy is maintained and the context explicitly declares `allow_external_fetch=true`. 9. **Triggers** (optional): for a high-discoverability skill, consider putting "triggers" (3-5 English phrases) up front, for fast invocation matching. ### Optimisation Process 1. **Structure**: apply the standard template (YAML, purpose, use cases, behavior, I/O, restrictions, self-check, examples). 2. **Verbs**: use precise, unambiguous verbs (e.g. "process" → "parse", "convert", "trim"). 3. **Interaction**: for complex logic, add "confirm before continuing" or "choose an option". Keep it in line with the spec's interaction policy (defaults preferred, then choices). 4. **Boundaries**: demote authoritative structural definitions, message sequences, and atomic rules from the Skill body to references; where the asset does not yet exist, list the suggested new Spec / Protocol / Rule in the diff summary, and do not conjure unrelated assets inside this skill. 5. **Adaptation**: add "discover → map → execute → handle absence" steps for the tool dependencies; a tool name is whatever the current runtime actually exposes, and an example tool name serves only as a capability hint. 6. **Local contract**: check external links, raw URLs, language, asset priority, and the local-path-first policy; on a violation, switch to a local reference or a conditional note. 7. **Metadata**: align the tags with INDEX.md; suggest triggers for a high-discoverability skill; suggest a sensible SemVer. 8. **Apply the changes**: unless the user explicitly asks for a dry run or a temporary refined file, write the refined content **straight back to the source `SKILL.md`**, and attach both the diff summary and the version proposal to the output, so it can be reviewed and audited. --- ## Input & Output ### Input - A SKILL Markdown document that needs optimising, or a draft. ### Output - **Optimised skill**: production-grade Markdown that meets the spec. - **Diff summary**: what changed, and why. - **Version proposal**: a SemVer recommendation. ### Output Persistence (document handling) **Rule**: by default, improve and overwrite the original `SKILL.md` in place, together with an auditable diff summary and a version proposal; only when the user explicitly asks for "a refined draft only, leave the source file alone" is a temporary or new refined file written. Every run must pick one of the three strategies below: | Strategy | Path pattern | Behavior | | :--- | :--- | :--- | | **Overwrite in place** (default) | `skills//SKILL.md` | Overwrite the source file directly, keep the frontmatter `version` updated, and carry the change summary in the output, which is what makes it auditable | | **Fixed temp file** (opt-out) | `skills//SKILL.refined.md` | Used when the user asks "do not touch the original, just give me the refinement"; every run overwrites the same temporary file | | **New file per run** (opt-out) | `skills//SKILL.refined.YYYYMMDD.md` | Used when the user asks "keep a separate file for this refinement"; every run creates a new refined file | User override: if the user names a path or a strategy, follow it. Otherwise use **overwrite in place**. --- ## Restrictions ### Hard Boundaries - **Overwrite by default, but it must stay auditable**: the default strategy overwrites the source `SKILL.md` directly, but the frontmatter `version` must be updated in step and the output carries a complete change summary, which is what keeps it auditable. - **Respect an explicit "draft mode" request**: where the user explicitly asks "do not modify the original", "only produce a refined draft" or the like, the source `SKILL.md` must not be overwritten; write only to a temporary or new refined file. - **Do not change the intent**: the optimisation must preserve the skill's core purpose. - **Do not dress a split suggestion up as done**: if only the Skill's reference changed and no Spec / Protocol / Rule was actually created, the output must say "split suggested" and must not claim the asset already exists. - **Do not route around the local contract**: in a repository that forbids external fetching by default, an external URL must not be written in as a source that execution depends on; it serves only as a reference source where conditions allow. - **Write less prose**: prefer lists and tables over long narrative paragraphs. - **Several examples**: do not keep only one "happy path" example; include at least one challenging or extreme case. ### Skill Boundaries (avoid overlap) **Do not do these (other skills handle them)**: - **Create a new skill from scratch**: generating the initial skill structure and content → handled separately through the repository contribution process; an external skill-creator must not be installed ad hoc - **Project documentation**: generate a README → use `generate-standard-readme`; generate AGENTS.md → use `generate-agent-entry` - **Decontextualise text**: strip PII or sensitive information → use `decontextualize-text` **When to stop and hand off**: - The user says "looks good", "approved", "commit this" → the refinement is done; hand off to the user for version control - The user asks "how do I create a new skill?" → hand off to the repository contribution guide and the agentskills.io spec --- ## Self-Check ### Core Success Criteria (all must be met) - [ ] **Structurally compatible**: the skill follows the standard template (YAML, purpose, use cases, behavior, input and output, restrictions, self-check, examples) - [ ] **Logic is clear**: the input → behavior → output chain is clear and unambiguous - [ ] **Constraints defined**: the restrictions section covers the failure modes common to the domain - [ ] **Asset boundaries**: the Skill carries no authoritative definition that belongs to a Spec / Protocol / Rule; any necessary split is stated - [ ] **Execution adaptation**: external tools and MCP tools have a discovery, capability-mapping, and missing-tool handling path - [ ] **Repository contract**: `AGENTS.md`, the terminology definitions, and the external-link and language rules are applied - [ ] **Examples are thorough**: at least 2 examples, one of them an edge case or a challenging scenario - [ ] **Changes recorded**: the diff summary lists every change together with its section, description, and reason - [ ] **Version proposed**: a SemVer proposal is given, with its rationale ### Process Quality Checks - [ ] **Bootstrapping**: can this skill be applied to itself successfully (refine itself)? - [ ] **Clarity**: can an agent with no domain background reproduce the behavior's result? - [ ] **Compliance**: are all the required sections and metadata fields present? - [ ] **Intent preserved**: does the refined skill keep the original skill's core purpose? - [ ] **Precision**: are the verbs concrete and unambiguous (not a vague term such as "process")? - [ ] **Interaction policy** (spec §4.3): does the behavior have default-based or choice-based interaction, where that applies? - [ ] **Triggers** (optional): for a high-discoverability skill, are "triggers" suggested? ### Acceptance Test **Can an AI Agent apply this refined skill consistently across different environments, with no ambiguity?** If no: the skill needs further refinement. Go through the "Behavior" section for clarity and add more specific instructions. If yes: the refinement is done. Give the user the diff summary and the version recommendation. --- ## Examples ### Before > Name: spell-check > This skill checks spelling. > Input: multilingual text. > Output: the corrected text. ### After > Name: polish-text-spelling > Description: context-aware spelling and terminology correction for multilingual documents. > Tags: [writing, quality-control] > Version: 1.1.0 > > --- > > **Skill: Spelling and Terminology** > > **Purpose**: find and fix low-level spelling errors and terminology inconsistencies without changing the author's intent or tone > > **Behavior** > > 1. Detect the language. > 2. If the text is long, build a terminology list. > 3. Tell a "typo" apart from "deliberate style". > > **Restrictions**: do not change proper nouns or specific abbreviations unless they are plainly wrong ### Example 2: Edge case — an ambiguous draft - **Input**: a skill draft whose purpose is "help users process files", with no use cases and no restrictions. - **Expected**: pin down the intent (replace "process" with a concrete verb: parse, convert, merge, and so on); add use cases and restrictions (e.g. do not overwrite the source; do not modify binary files); add at least one edge-case example (e.g. an empty file, a very large file, permission denied).