/skill-creator-plus

SKILL.md Review Checklist

Checklist for reviewing and improving SKILL.md files.

Quick Check (5 items)

- [ ] SKILL.md is under 150 lines? (GitHub guideline: "2 pages or less")
- [ ] Frontmatter has name + description?
- [ ] Self-authored skills have confirmed license + `metadata.author`?
- [ ] Description clearly states WHEN to use (trigger conditions)?
- [ ] Detailed content moved to references/ (Progressive Disclosure)?
- [ ] Self-contained? Knowledge is bundled, not just linked to workspace files that break when copied elsewhere?
- [ ] No README.md or auxiliary docs in skill folder?
- [ ] The skill fits one primary archetype, or the split is intentional?
- [ ] Non-obvious gotchas are captured where they affect correctness?
- [ ] Success can be verified by scripts, assertions, artifacts, or explicit checks?

Size & Structure

Line Count Target

Source: GitHub Docs - Adding repository custom instructions

"Instructions must be no longer than 2 pages."

Progressive Disclosure

→ See skill-structure.md > Progressive Disclosure for the 3-level loading system.

Pattern: Keep SKILL.md lean, move details to references.

❌ Bad: 400-line SKILL.md with all details inline
✅ Good: 120-line SKILL.md + references/detailed-guide.md

Content Quality

Skill Archetype Fit

Before reviewing wording, identify the primary kind of skill:

• Library / API reference
• Product verification
• Data fetching / analysis
• Business process automation
• Code scaffolding / templates
• Code quality / review
• CI/CD / deployment
• Runbook / debugging
• Infrastructure operations

If it claims several at once, split it or move secondary behavior into references. A skill can depend on another skill, but its own responsibility should stay crisp.

Frontmatter

---
name: skill-name # Required
description: "..." # Required - include trigger conditions
license: CC BY-NC-SA 4.0 # Required for self-authored skills
metadata: # Required for self-authored skills
  author: yamapan (https://github.com/aktsmm)
---

Description must answer:

• What does this skill do?
• When should it be triggered?

Body Structure

What NOT to Include

→ See skill-structure.md > What NOT to Include for the complete list.

Gotchas and Verification

High-signal skill content is usually specific failure avoidance, not obvious process narration.

Check for:

• common field-name mismatches, API quirks, stale state, or misleading success responses
• verification steps that inspect real state, not just command exit codes
• scripts or assertions for fragile workflows such as UI flows, deployments, data pulls, or interactive CLIs
• setup state such as config.json when a missing channel, environment, or destination should trigger a user question
• bundled Office assets, especially .pptx, are inspected inside the ZIP package (docProps/custom.xml, docProps/core.xml, slides, notes), not only by visible slide text; remove sensitivity labels, personal emails, author names, tenant IDs, and local paths before public or reusable skill packaging

References Organization

When to Create references/

Naming Convention

references/
├── {topic}.md           # General pattern
├── {variant-name}.md    # For variants (aws.md, gcp.md)
├── examples/            # Example files
└── schemas/             # Schema definitions

Common Issues

Issue 1: SKILL.md Too Long

Symptoms: > 300 lines, scrolling required to find key info

Fix:

1. Identify sections > 50 lines
2. Create references/{section-name}.md
3. Replace with summary + link: → See [references/{name}.md](references/{name}.md)

Issue 2: Vague Description

Symptoms: Description says what skill does, not when to use it

Bad:

description: "Processes PDF files"

Good:

description: "Extract text, rotate pages, and fill forms in PDF files. Use when working with .pdf documents for text extraction, page manipulation, or form automation."

Issue 3: Duplicate Content

Symptoms: Same information in SKILL.md and references/

Fix: Information should live in ONE place only. Keep procedural instructions in SKILL.md, move detailed reference material to references/.

Issue 4: Missing Trigger Conditions

Symptoms: Skill doesn't activate when expected

Fix: Add specific triggers to description:

• File patterns (.pdf, .agent.md)
• Task keywords ("extract text", "rotate page")
• Context conditions ("when working with...")

Issue 5: Obvious Guidance Without Gotchas

Symptoms: The skill says what any capable agent would already do, but omits the edge cases that caused past failures.

Fix: Replace generic advice with specific gotchas, verification checks, or reusable scripts.

Good examples:

• "A UI success banner can appear before backend processing finishes; verify the persisted state."
• "Two systems expose similar request identifiers; document the canonical join key."
• "Append-only history tables need an explicit rule for choosing the active row."

Issue 6: Not Self-Contained (Hidden Dependencies)

Symptoms: Skill works in source repo but breaks when copied / synced elsewhere. Hard reference to a sibling skill, workspace file outside the skill folder, env-specific path (<local-path>\...), customer name, tenant ID, or ~/.copilot/skills/... link.

Allowed:

• Loose reference by skill name as a string (registry / denylist patterns). Loss of the named skill should degrade gracefully, not crash.
• Links to files inside the skill folder (./scripts/, ./references/, ./assets/).

Not allowed:

• ../other-skill/... links
• Absolute paths (D:\..., /Users/...)
• Customer / tenant / personal identifiers without abstraction (use <placeholder>)
• "See instruction X in the workspace" without bundling the content here

Fix: Bundle the knowledge into references/ or scripts/. Abstract env-specific values to placeholders or arguments. Keep registry-style references as strings, but ensure the skill itself runs without them.

Review Template

## SKILL.md Review: {skill-name}

### Metrics

- [ ] Line count: \_\_\_ (target: < 150)
- [ ] Frontmatter valid: Yes/No
- [ ] Description has triggers: Yes/No
- [ ] Primary archetype: **\_\_**

### Structure

- [ ] Progressive disclosure applied
- [ ] No auxiliary docs (README, CHANGELOG)
- [ ] References properly linked

### Content

- [ ] Single responsibility (SRP)
- [ ] No duplicate information
- [ ] Examples minimal but sufficient
- [ ] Gotchas are specific and actionable
- [ ] Verification path is explicit
- [ ] Baseline validation record is complete; helper/package commands ran only when relevant

### Action Items

1. ...
2. ...