--- title: "Medisolv Skill Creator" type: "Skill" slug: "skill-creator" icon: "auto_awesome" category: "Platform" tags: [ "Meta", "Skill", "SKILL.md", "Markdown", "Developer Tools", "Platform", "Augment Code", ] installs: "0" author: "Medisolv Platform Team" authorInitial: "M" lastUpdated: "2026-04-09" popularity: "5.0/5" reviewCount: "New" platformTags: ["v1.0", "Internal"] installLabel: "SKILL.md" securityBadges: - label: "Data Handling" status: "No PHI - generates docs only" - label: "Compliance" status: "Internal Developer Use" --- # Medisolv Skill Creator Gives any AI agent the complete knowledge needed to author, validate, and publish a production-ready Medisolv Skill from scratch. Install this skill so your agent knows the exact SKILL.md structure, YAML frontmatter fields, required markdown sections, and portal publishing requirements -- without you having to explain them every time. Use this skill whenever someone asks to create a new skill, turn a workflow into a reusable skill, verify an existing skill against conventions, or onboard a new engineer to the skill authoring process. ## When to Use Use this skill when you need to: - Create a brand-new Skill that teaches an AI agent how to perform a specific Medisolv workflow - Convert an ad-hoc process, checklist, or tribal knowledge into a reusable, installable Skill on the Discovery Portal - Scaffold the `skills//SKILL.md` directory structure and populate it with correct frontmatter and body sections - Verify that an existing `SKILL.md` follows Medisolv conventions (frontmatter fields, required sections, naming rules) - Onboard a new engineer who needs to understand the full Skill authoring recipe without reading every commit - Decide whether the user's request actually needs a Skill, or would be better served by an MCP, Subagent, or CLI ## Installation ``` auggie skill add https://aidiscoveryportal.azurewebsites.net/api/skills/skill-creator ``` ## Tool Definition ```json { "name": "skill_creator", "description": "You are a Medisolv platform engineer who specialises in authoring Skills for the Medisolv AI Discovery Portal. When asked to create or scaffold a Skill, always follow the Medisolv conventions documented in this skill. Produce the SKILL.md with correct frontmatter and all required markdown sections -- no steps skipped.", "capabilities": [ "scaffold skills// directory and SKILL.md", "generate YAML frontmatter with all required portal fields", "write required markdown sections: When to Use, Installation, Tool Definition", "write recommended sections: Workflow, Best Practices, Common Mistakes, Example Prompts", "verify an existing SKILL.md against Medisolv conventions and the portal loader", "decide whether a request needs a Skill, MCP, Subagent, or CLI" ], "constraints": [ "Always decide whether the request needs a Skill, an MCP, a Subagent, or a CLI before authoring anything", "Always choose a slug that is lowercase and hyphen-separated and matches the folder name exactly", "Always include every required frontmatter field so the portal loader renders the card correctly", "Always quote string values in YAML frontmatter that contain special characters or dates", "Always include the three required body sections: When to Use, Installation, Tool Definition", "Always write a Tool Definition JSON block with name, description, capabilities, and constraints", "Never include PHI, credentials, or environment-specific secrets in the SKILL.md", "Always pick a category from the approved list to ensure the catalog filter UX works correctly", "Always use the auggie skill add URL pattern for the Installation section" ] } ``` ## Workflow Follow this lifecycle for every new Skill: 1. **Capture intent** -- clarify what the skill should teach an AI to do, who the audience is, and what the expected input/output looks like 2. **Choose the resource shape** -- confirm a Skill is the right type (see decision table below) 3. **Pick a slug** -- choose a lowercase, hyphen-separated identifier that becomes both the folder name and URL path 4. **Write the SKILL.md** -- frontmatter first, then the required body sections, then recommended sections 5. **Register in the portal** -- place the file at `skills//SKILL.md`; the portal auto-discovers it 6. **Verify** -- confirm the skill appears at `/catalog` and `/skills/` and all sections render correctly 7. **Iterate** -- refine the instructions based on real usage, tighten the Tool Definition constraints, add examples --- ## First Decision: Does the User Need a Skill, MCP, Subagent, or CLI? Before authoring anything, classify the request: | If the user needs... | Build... | Why | | -------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------ | | Reusable step-by-step instructions for an AI agent | **Skill** | Skills extend the AI's knowledge without changing its persona or tool access | | A reusable persona with a scoped system prompt and fixed tool access | **Subagent** | Subagents are pre-configured agents with a defined role and tool set | | Runtime access to live APIs or clinical data | **MCP** | MCPs expose callable tools to the AI at runtime via the Model Context Protocol | | A terminal command engineers can install and run directly | **CLI** | CLIs work standalone for humans, scripts, and agents | > **Rule of thumb:** if the output is "teach the AI how to do X in any context", you are building a Skill. If the output is "run this agent and it will do X in a specific domain", you need a Subagent. If it involves live API calls, you need an MCP. If it is a shell command, you need a CLI. --- ## What Is a Medisolv Skill? A Skill is a **Markdown file** stored at `skills//SKILL.md` that teaches an AI agent how to perform a specific task or workflow. It has three defining properties: 1. **Domain-specific instructions** -- the markdown body tells the AI what to do, what to watch for, and how to respond in a particular situation 2. **No persona or tool changes** -- unlike a Subagent, a Skill does not change the AI's identity or restrict its tool access; it only adds knowledge 3. **Publishable on the portal** -- engineers discover and install it from the catalog just like an MCP or Subagent > **Analogy:** Think of a Skill like a recipe card slipped into your AI's cookbook. On its own, the AI is a capable generalist. Add a Skill and it becomes a specialist in that domain -- without changing who it is. --- ## File Location and Auto-Discovery ```text skills/ / SKILL.md <-- the only required file ``` The portal's filesystem loader (`app/lib/loader.ts`) reads every `skills//SKILL.md` at runtime. No code changes are needed -- creating the file is the only required step. The skill immediately appears at: - `/catalog` -- the skills listing page with icon, title, description, and category chip - `/skills/` -- detail page with When to Use, Installation, and Tool Definition sections - `/api/skills/` -- API endpoint that serves the raw markdown --- ## SKILL.md Frontmatter Reference All fields are required unless marked optional. The portal loader (`parseSkillDetail` in `app/lib/loader.ts`) reads these fields from the YAML frontmatter block. ````yaml --- title: "My New Skill" # Display name shown in the portal UI type: "Skill" # Resource type -- always "Skill" for skills slug: "my-new-skill" # URL-safe ID -- must match the folder name exactly icon: "auto_awesome" # Material Symbols icon name (see fonts.google.com/icons) category: "Revenue Cycle" # Category shown in the catalog filter chips tags: ["Tag1", "Tag2", "Tag3"] # Free-form tags for search and filtering installs: "0" # Initial install count -- always start at "0" author: "Your Team Name" # Team or person responsible for this skill authorInitial: "Y" # Single capital letter for the avatar fallback lastUpdated: "2026-04-09" # ISO date string -- must be quoted popularity: "5.0/5" # Rating string -- use "5.0/5" for new skills reviewCount: "New" # Review label -- use "New" or "0 Reviews" initially platformTags: ["v1.0", "Internal"] # Version and audience tags shown on the detail page installLabel: "SKILL.md" # Label shown above the installation code block (optional) securityBadges: # Security compliance badges (optional, array) - label: "Data Handling" ### Approved `category` values Use one of these exactly to ensure the `/catalog` filter chip works correctly: - `Coding` - `Quality` - `Clinical Safety` - `Revenue Cycle` - `Summarization` - `Identity & Access` - `Developer Tools` - `Platform` ### `icon` values Use any icon name from [Material Symbols](https://fonts.google.com/icons). Common choices: | Icon | Use case | | --- | --- | | `auto_awesome` | General-purpose, platform | | `menu_book` | Documentation, knowledge | | `manage_accounts` | Identity, access, users | | `terminal` | CLI, developer tools | | `hub` | Integration, connectivity | | `commit` | Git, version control | | `smart_toy` | AI, agents | | `science` | Clinical, research | | `payments` | Revenue cycle, billing | --- ## Markdown Body Structure The portal loader parses specific `## Heading` sections from the markdown body. These are the sections the detail page renders, and every Skill should include them. ### Required sections These sections are parsed by `parseSkillDetail()` and rendered on the `/skills/` detail page: 1. **Opening paragraph** -- the very first paragraph (before any heading) becomes the `description` shown on catalog cards. Write one clear sentence explaining what this skill does and the value it delivers. 2. **`## When to Use`** -- starts with an optional introductory sentence, then a bullet list of concrete triggers. The loader splits this into `whenToUseIntro` (first paragraph) and `whenToUse` (bullet items). 3. **`## Installation`** -- contains a fenced code block with the install command. The loader extracts the first code block as the `installation` string. Use the pattern: `auggie skill add https://aidiscoveryportal.azurewebsites.net/api/skills/` 4. **`## Tool Definition`** -- contains a fenced JSON code block defining the tool schema. The loader extracts the first code block as the `toolDefinition` string. Include `name`, `description`, `capabilities`, and `constraints`. ### Recommended sections These are not parsed by the loader but provide essential guidance in the raw markdown that AI agents read: - **`## Workflow`** -- numbered lifecycle steps (capture intent, choose type, scaffold, verify, iterate) - **`## First Decision`** -- decision table for resource type classification - **`## What Is a Medisolv [Resource]?`** -- definition and analogy for the resource type - **`## File Location and Auto-Discovery`** -- path and URL structure - **`## Frontmatter Reference`** -- field-by-field documentation with types and examples - **`## Complete SKILL.md Example`** -- a full, copy-pasteable example - **`## Naming Convention`** -- slug rules, folder naming, file naming - **`## Checklist Before Committing`** -- validation steps as checkboxes - **`## Common Mistakes`** -- table of pitfalls and fixes - **`## Example Prompts`** -- realistic user prompts showing how to invoke the skill ### Writing best practices - Open the skill with a strong, declarative statement of what it enables -- not a vague introduction - Use imperative voice for instructions: "Create...", "Verify...", "Include..." - Explain the **why** behind requirements, not just the **what** -- AI agents follow rules better when they understand the reasoning - Keep instructions concrete and actionable; avoid abstract principles without examples - Include a complete worked example so the AI can pattern-match rather than invent from scratch - Target 250-400 lines total -- long enough to be thorough, short enough that the AI loads it efficiently --- ## Complete SKILL.md Example Below is a full, copy-pasteable SKILL.md that follows all Medisolv conventions. Use this as a starting template and replace the placeholder content with the actual skill domain. ```yaml --- title: "Clinical Documentation Reviewer" type: "Skill" slug: "clinical-doc-reviewer" icon: "science" category: "Clinical Safety" tags: ["Clinical", "Documentation", "Review", "Quality", "Compliance"] installs: "0" author: "Medisolv Clinical Team" authorInitial: "C" lastUpdated: "2026-04-09" popularity: "5.0/5" reviewCount: "New" platformTags: ["v1.0", "Internal"] installLabel: "SKILL.md" securityBadges: - label: "Data Handling" status: "No PHI - review guidance only" - label: "Compliance" status: "Internal Clinical Use" --- ```` After the frontmatter closing `---`, write the markdown body: ```markdown # Clinical Documentation Reviewer Teaches an AI agent how to review clinical documentation for completeness, accuracy, and compliance with CMS and Joint Commission standards. ## When to Use Use this skill when you need to: - Review clinical notes for documentation completeness before claim submission - Identify missing physician queries that could improve coding accuracy - Verify that diagnoses have adequate clinical evidence in the medical record - Flag documentation gaps that may affect quality measure performance ## Installation auggie skill add https://aidiscoveryportal.azurewebsites.net/api/skills/clinical-doc-reviewer ## Tool Definition { "name": "clinical_doc_reviewer", "description": "Review clinical documentation for completeness and compliance.", "capabilities": [ "review clinical notes for documentation completeness", "flag documentation gaps affecting quality measures" ], "constraints": [ "Always reference specific CMS or Joint Commission standards", "Never fabricate clinical details" ] } ## Workflow 1. Receive documentation for review 2. Assess completeness against required elements 3. Evaluate clinical evidence supporting diagnoses 4. Flag gaps with specific standard references 5. Recommend actions (physician queries, documentation additions) ## Common Mistakes | Mistake | Fix | | ----------------------------------------- | ----------------------------------- | | Reviewing without specifying standards | State the standard set at the start | | Generic feedback like "needs improvement" | Cite the specific missing element | ## Example Prompts > "Review this discharge summary against CMS documentation requirements." > "What physician queries should we generate based on this operative note?" ``` --- ## Naming Convention | Rule | Example | | -------------------------------------------------------- | --------------------------------------- | | Slug is lowercase, hyphen-separated | `clinical-doc-reviewer` | | Folder name **must** exactly match `slug` | `skills/clinical-doc-reviewer/` | | `title` is the display name (title case, spaces allowed) | `"Clinical Documentation Reviewer"` | | File is always named `SKILL.md` | `skills/clinical-doc-reviewer/SKILL.md` | --- ## Checklist Before Committing - [ ] Confirmed a Skill is the right resource type (not an MCP, Subagent, or CLI) - [ ] Slug is lowercase and hyphen-separated and matches the folder name exactly - [ ] `title`, `type`, `slug`, `icon`, `category`, `tags`, `author`, and `authorInitial` are all present in frontmatter - [ ] `type` is set to `"Skill"` (not `"MCP Server"` or `"Subagent"`) - [ ] `lastUpdated` is a quoted ISO date string (e.g., `"2026-04-09"`) - [ ] `category` is from the approved list so the catalog filter chip works - [ ] `icon` is a valid Material Symbols icon name - [ ] Opening paragraph (before any heading) is a clear one-sentence description - [ ] `## When to Use` section has an intro sentence and a bullet list of concrete triggers - [ ] `## Installation` section has a fenced code block with `auggie skill add ` - [ ] `## Tool Definition` section has a valid JSON code block with `name`, `description`, `capabilities`, and `constraints` - [ ] No PHI, credentials, or environment-specific secrets anywhere in the file - [ ] Skill appears at `/catalog` and `/skills/` after the file is created --- ## Common Mistakes | Mistake | Fix | | ---------------------------------------------- | -------------------------------------------------------------------------------------------------- | | Folder name does not match `slug` | Rename the folder or correct the `slug` field -- they must match exactly | | Missing `type: "Skill"` in frontmatter | Add it -- the loader defaults to "Skill" but being explicit avoids confusion | | Unquoted date in `lastUpdated` | Wrap in quotes: `lastUpdated: "2026-04-09"` -- bare dates cause YAML parse issues | | No opening paragraph before the first heading | Add a one-sentence description as the very first paragraph -- the loader uses it for catalog cards | | Missing `## Installation` code block | Add a fenced code block with the `auggie skill add` command -- the detail page renders it | | Missing `## Tool Definition` JSON block | Add a fenced JSON block with `name`, `description`, `capabilities`, `constraints` | | Using an unapproved `category` value | Pick from the approved list so the catalog filter chip renders correctly | | Conflating a Skill with a Subagent | Skills teach the AI new knowledge; Subagents give it a fixed persona and tool set | | Conflating a Skill with an MCP | Skills are static instructions; MCPs are runtime tools that call live APIs | | Vague Tool Definition with no constraints | Add specific `constraints` that tell the AI what it must always or never do | | Writing abstract instructions with no examples | Include a `## Example Prompts` section and a worked example or template | | Including PHI or credentials | Move secrets to environment variables or MCPs; keep the SKILL.md clean | --- ## Example Prompts > "Create a new Skill that teaches an AI how to review Medisolv MIPS submissions for documentation completeness. Include the full SKILL.md with frontmatter and all required sections." > "I have a checklist I use every day for auditing CDI queries. Turn it into a proper Skill with the right frontmatter and publish it to the Discovery Portal." > "Audit the `skills/citc/SKILL.md` file and tell me if it follows Medisolv Skill conventions, then suggest improvements." > "I need a skill for our revenue cycle team that helps AI agents analyze claim denial patterns. Scaffold the directory and generate the SKILL.md." > "What's the difference between a Skill and a Subagent? Help me decide which one I need for a clinical coding review workflow."