SKILL.md Creator Checklist: Everything to Check Before Publishing

Use this checklist before submitting a skill to Agensi. Every item here contributes to passing the security scan, getting approved in quality review, and generating sales once published.

Quick Answer: Before publishing, verify your SKILL.md has valid YAML frontmatter with a descriptive trigger-based description, clear step-by-step instructions, no hardcoded secrets, a clean zip structure, and at least one supporting file (reference doc, script, or example). Skills that pass all checklist items get approved faster and sell more.

Frontmatter checklist

Your YAML frontmatter is the first thing the agent reads. It determines when your skill activates and how it appears on the marketplace.

Name is clear and descriptive. Use a slug-style name like code-reviewer or pytest-generator, not my-skill-v2 or untitled. This appears in the marketplace listing and in the agent's skill list.

Description is trigger-based. The description tells the agent when to load the skill. Write it as "Use when the user asks to..." followed by the specific actions that should activate the skill. Include 3 to 5 trigger phrases. For detailed guidance, read How to Write a SKILL.md Description That Triggers.

No extra frontmatter fields that break parsing. Stick to name and description as the core fields. Additional fields like context, globs, and tags are optional and agent-specific. If you include them, make sure the YAML is valid by testing with a YAML parser.

Instructions checklist

The markdown body is where the real value lives. This is what the agent reads and follows.

Instructions are specific and actionable. "Review code for bugs" is too vague. "Review code for: 1) null pointer errors, 2) unchecked array access, 3) missing error handling on async operations, 4) hardcoded credentials" is actionable. The more specific your instructions, the more consistently the agent follows them.

Output format is defined. Tell the agent exactly how to structure its output. "Group findings by file. For each finding, include severity (critical/warning/suggestion), the line reference, a one-sentence description, and a recommended fix." Without output format instructions, the agent produces inconsistent results.

The skill works across agents. Test your skill in at least two agents (Claude Code and one other). If you use agent-specific features like Claude Code's context: fork, note that in the description so buyers know.

No hardcoded secrets or credentials. Search your SKILL.md for anything that looks like an API key, token, or password. If your skill needs credentials, instruct the user to provide them through environment variables.

Instructions are self-contained. A buyer should be able to install the skill and use it immediately without reading external documentation. If context is needed, include it in a reference file inside the skill folder.

Supporting files checklist

Skills with supporting materials sell for significantly more and get better reviews.

At least one reference file or example. Even a simple references/patterns.md that lists common patterns the skill checks for adds value. A examples/ folder with sample inputs and expected outputs helps buyers understand what they're getting.

Scripts are safe and readable. If you include helper scripts, make sure they only operate within the project directory, don't require elevated permissions, are well-commented so buyers can audit them, and don't install packages or modify system configs.

README.md in the skill folder. A short README explaining what the skill does, how to use it, and any configuration options. This isn't required by the security scan but it significantly improves buyer confidence.

Zip structure checklist

The zip file you upload must follow a specific structure.

Single top-level folder. The zip should contain one folder (named after your skill) with SKILL.md at the root of that folder. Not SKILL.md at the zip root, and not nested two levels deep.

correct:
  code-reviewer/
  ├── SKILL.md
  ├── references/
  │   └── patterns.md
  └── scripts/
      └── helper.sh

wrong:
  SKILL.md (no containing folder)

wrong:
  code-reviewer/
  └── code-reviewer/
      └── SKILL.md (double-nested)

No symlinks or unexpected binary files. The zip should only contain text files (markdown, scripts, configs). Binary files like compiled executables will be flagged by the security scan.

No hidden files from your OS. Make sure .DS_Store (macOS) and Thumbs.db (Windows) aren't included. Use zip -r code-reviewer.zip code-reviewer/ -x "*.DS_Store" to exclude them.

Pre-submission testing

Install and test in at least one agent. Unzip the skill to your agent's skills directory and verify it activates when you ask the agent to do the task the skill covers. Check that the output matches the format you specified in the instructions.

Ask someone else to test it. Have a developer who didn't build the skill install it and try it on their project. If they're confused by the instructions or the output isn't useful, refine before publishing.

For a creator workflow, read Create a SKILL.md from Scratch.

---

Ready to publish? Submit your skill on Agensi.