skill-normalizer
- Repo stars 208
- License Complete terms in LICENSE.txt
- Author updated Live
- Author repo AgentJet
- Domain
- Data
- Compatible agents
-
- Claude Code
- Cursor
- Cline
- Codex
- Windsurf
- Gemini CLI
- +20
- Trust score
- 94 / 100 · audit passed
- Author / version / license
- @modelscope · Complete terms in LICENSE.txt
- Token usage
- Lean
- Setup complexity
- Manual integration
- External API key
- Not required
- Operating systems
- Docker
- Runtime requirements
- Python >=3.14 · Docker
- Permissions
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- External requests
- Install commands
- 26 variants
Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.
Heads up: 未限定 allowed-tools,默认拥有全部工具权限。
---
name: skill-normalizer
description: Convert skills in non-standard formats to the standard Agent Skills `SKILL.md` format. Validates…
category: data
runtime: Python / Docker
---
# skill-normalizer output preview
## PART A: Task fit
- Use case: Convert skills in non-standard formats to the standard Agent Skills `SKILL.md` format. Validates YAML frontmatter (name, description, license, compatibility, metadata, allowed-tools), directory structure (SKILL.md, scripts/, references/, assets/), and best practices. Use when the user asks to normalize, validate, or fix a skill..
- Inputs: target material, constraints, expected output, and acceptance criteria.
- Evidence boundary: follow “Directory structure / SKILL.md format / Frontmatter” and do not present inference as author intent.
## PART B: Execution result
- **01** The card summarizes the use case; runtime output centers on “Convert skills in non-standard formats to the standard Agent Skills `SKILL.md` format. Validates YAML frontmatter (name, description, license, compatibility, metadata, allowed-tools), directory structure (SKILL.md, scripts/, references/, assets/), and best practices. Use when the user asks to normalize, validate, or fix a skill.”.
- **02** When the source has headings, the agent prioritizes “Directory structure / SKILL.md format / Frontmatter” so the result follows the author’s structure.
- **03** Typical output includes task judgment, concrete steps, required commands or file edits, validation, and follow-up options.
- **04** Risk context follows the fingerprint: read files, write/modify files, run shell commands; may access external network resources; usually needs no extra API key.
## Running Rules
- read files, write/modify files, run shell commands; may access external network resources; usually needs no extra API key.
- Validate with a small sample before expanding scope.
- Return the result, validation criteria, and next iteration options. The source does not require a stable slash command. After installation, invoke the skill by name and describe the task.
Name target files or source material, expected output, forbidden changes, and whether network or shell access is allowed. Permission fingerprint: read files, write/modify files, run shell commands.
Start with a small task and check whether the result follows “Directory structure / SKILL.md format / Frontmatter”. Inspect diffs, logs, previews, or tests before expanding scope.
Confirm the final output includes a concrete result, evidence, and next action. If it stays generic, tighten inputs, boundaries, and acceptance criteria.
---
name: skill-normalizer
description: Convert skills in non-standard formats to the standard Agent Skills `SKILL.md` format. Validates…
category: data
source: modelscope/AgentJet
---
# skill-normalizer
## When to use
- Convert skills in non-standard formats to the standard Agent Skills `SKILL.md` format. Validates YAML frontmatter (nam…
- Use it when the task has clear inputs, repeatable steps, and validation criteria.
## What to provide
- Target material, scope, expected result, and forbidden changes.
- Whether network, commands, file writes, or external services are allowed.
## Execution rules
- Organize steps around “Directory structure / SKILL.md format / Frontmatter” and keep inference separate from source facts.
- read files, write/modify files, run shell commands; may access external network resources; usually needs no extra API key.
- Validate with a small sample before expanding the task.
## Output requirements
- Return the deliverable, key evidence, validation method, and next action.
- Mark missing information as unknown; do not invent commands, platforms, or dependencies. The author source anchors workflow facts; repository files anchor sources and commands; Fluxly only adds fit, limitations, and quality judgment.
skill "skill-normalizer" {
input -> user goal + target files + boundaries + acceptance criteria
context -> Directory structure / SKILL.md format / Frontmatter
rules -> SKILL.md triggers / order / output contract
runtime -> Python / Docker | read files, write/modify files, run shell commands | may access external network resources
guardrails -> usually needs no extra API key + small-sample validation + diff/log review
output -> copyable result + checklist + next iteration
} Your task is to make skills in non-standard formats compatible with the Agent Skills ecosystem by converting them to the standard SKILL.md format. This document provides the specification for the SKILL.md format, including required and optional fields, directory structure, and best practices for writing effective skills.
Documentation Index
Fetch the complete documentation index at: https://agentskills.io/llms.txt Use this file to discover all available pages before exploring further.
Specification
The complete format specification for Agent Skills.
Directory structure
A skill is a directory containing, at minimum, a SKILL.md file:
skill-name/
├── SKILL.md # Required: metadata + instructions
├── scripts/ # Optional: executable code
├── references/ # Optional: documentation
├── assets/ # Optional: templates, resources
└── ... # Any additional files or directories
SKILL.md format
The SKILL.md file must contain YAML frontmatter followed by Markdown content.
Frontmatter
| Field | Required | Constraints |
|---|---|---|
name |
Yes | Max 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen. |
description |
Yes | Max 1024 characters. Non-empty. Describes what the skill does and when to use it. |
license |
No | License name or reference to a bundled license file. |
compatibility |
No | Max 500 characters. Indicates environment requirements (intended product, system packages, network access, etc.). |
metadata |
No | Arbitrary key-value mapping for additional metadata. |
allowed-tools |
No | Space-separated string of pre-approved tools the skill may use. (Experimental) |
---
name: skill-name
description: A description of what this skill does and when to use it.
---
Example with optional fields:
---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
metadata:
author: example-org
version: "1.0"
---
name field
The required name field:
- Must be 1-64 characters
- May only contain unicode lowercase alphanumeric characters (
a-z) and hyphens (-) - Must not start or end with a hyphen (
-) - Must not contain consecutive hyphens (
--) - Must match the parent directory name
name: pdf-processing
name: data-analysis
name: code-review
Invalid examples:
name: PDF-Processing # uppercase not allowed
name: -pdf # cannot start with hyphen
name: pdf--processing # consecutive hyphens not allowed
description field
The required description field:
- Must be 1-1024 characters
- Should describe both what the skill does and when to use it
- Should include specific keywords that help agents identify relevant tasks
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
Poor example:
description: Helps with PDFs.
license field
The optional license field:
- Specifies the license applied to the skill
- We recommend keeping it short (either the name of a license or the name of a bundled license file)
license: Proprietary. LICENSE.txt has complete terms
compatibility field
The optional compatibility field:
- Must be 1-500 characters if provided
- Should only be included if your skill has specific environment requirements
- Can indicate intended product, required system packages, network access needs, etc.
compatibility: Designed for Claude Code (or similar products)
compatibility: Requires git, docker, jq, and access to the internet
compatibility: Requires Python 3.14+ and uv
metadata field
The optional metadata field:
- A map from string keys to string values
- Clients can use this to store additional properties not defined by the Agent Skills spec
- We recommend making your key names reasonably unique to avoid accidental conflicts
metadata:
author: example-org
version: "1.0"
allowed-tools field
The optional allowed-tools field:
- A space-separated string of tools that are pre-approved to run
- Experimental. Support for this field may vary between agent implementations
allowed-tools: Bash(git:*) Bash(jq:*) Read
Body content
The Markdown body after the frontmatter contains the skill instructions. There are no format restrictions. Write whatever helps agents perform the task effectively.
Recommended sections:
- Step-by-step instructions
- Examples of inputs and outputs
- Common edge cases
Note that the agent will load this entire file once it's decided to activate a skill. Consider splitting longer SKILL.md content into referenced files.
Optional directories
scripts/
Contains executable code that agents can run. Scripts should:
- Be self-contained or clearly document dependencies
- Include helpful error messages
- Handle edge cases gracefully
Supported languages depend on the agent implementation. Common options include Python, Bash, and JavaScript.
references/
Contains additional documentation that agents can read when needed:
REFERENCE.md- Detailed technical referenceFORMS.md- Form templates or structured data formats- Domain-specific files (
finance.md,legal.md, etc.)
Keep individual reference files focused. Agents load these on demand, so smaller files mean less use of context.
assets/
Contains static resources:
- Templates (document templates, configuration templates)
- Images (diagrams, examples)
- Data files (lookup tables, schemas)
Progressive disclosure
Agents load skills progressively, pulling in more detail only as a task calls for it. Skills should be structured to take advantage of this:
- Metadata (~100 tokens): The
nameanddescriptionfields are loaded at startup for all skills - Instructions (< 5000 tokens recommended): The full
SKILL.mdbody is loaded when the skill is activated - Resources (as needed): Files (e.g. those in
scripts/,references/, orassets/) are loaded only when required
Keep your main SKILL.md under 500 lines. Move detailed reference material to separate files.
File references
When referencing other files in your skill, use relative paths from the skill root:
See [the reference guide](references/REFERENCE.md) for details.
Run the extraction script:
scripts/extract.py
Keep file references one level deep from SKILL.md. Avoid deeply nested reference chains.
Validation
Use the skills-ref reference library to validate your skills:
skills-ref validate ./my-skill
This checks that your SKILL.md frontmatter is valid and follows all naming conventions.
Decide Fit First
SKILL.mdformat. Validates YAML frontmatter (name, descrip…Design Intent
How To Use It
Boundaries And Review