SklyDocs
Skills

Best Practices

Write effective AI skills that sell. Provide concise instructions, progressive disclosure, workflows, testing strategies, and highlight common mistakes to avoid.

Core Principles

Be concise

Every token takes up context. Only include what the AI doesn't already know.

Be explicit

Don't be vague; clearly state the tone, format, and constraints.

Match detail to risk

Allow high freedom for flexible tasks and low freedom for critical operations.

Conciseness in Practice

AI agents share their context window with the system prompt, conversation history, other skills, and the user's request. Each token in your skill has a cost.

Assume the AI is already knowledgeable. Before adding information, ask yourself:

  • Does the AI actually need this explanation?
  • Can I assume it already knows this?
  • Does this paragraph justify its token cost?

For example, don't explain what a PDF is; just show how to process one.

Matching Detail Level to Task Risk

When multiple approaches are valid and decisions depend on context, provide general direction and let the AI choose:

## Code Review Process
1. Analyze the code structure
2. Check for potential bugs or edge cases
3. Suggest improvements for readability

Structuring Your Skill

Writing Effective Descriptions

Your skill's description field influences discoverability — it's how agents decide whether to activate your skill. Make it count.

Include both what the skill does and when to use it:

description: Writes SEO-optimized blog posts with keyword research
and meta descriptions. Use when creating content for websites or
when the user asks for blog posts, articles, or web content.

Write descriptions in third person — "Processes Excel files" not "I can help you process Excel files." Use specific keywords that match how users describe their tasks.

Naming Your Skills

Use clear, descriptive names that convey what the skill does:

NameVerdict
seo-blog-writerImmediately clear
code-reviewObvious purpose
data-analysisStraightforward
helperToo vague
utilsToo vague
toolsToo vague

Maintain consistent naming across your skill collection.

Using Workflows

For complex tasks, break operations into clear, sequential steps with a checklist the AI can track:

## Research Synthesis Workflow

Progress:
- [ ] Step 1: Read all source documents
- [ ] Step 2: Identify key themes
- [ ] Step 3: Cross-reference claims
- [ ] Step 4: Create structured summary
- [ ] Step 5: Verify citations

Clear steps help prevent the AI from skipping critical phases.

Add Feedback Loops

For quality-critical tasks, build validation into your workflow:

## Content Review Process
1. Draft content following the guidelines
2. Review against the checklist
3. If issues found, note them, revise, and review again
4. Only proceed when all requirements are met

The "validate → fix → repeat" pattern significantly improves output quality.

Templates and Examples

When you need consistent output format, provide a template:

## Report Structure

Use this template:

# [Analysis Title]

## Executive Summary
[One-paragraph overview of key findings]

## Key Findings
- Finding 1 with supporting data
- Finding 2 with supporting data

## Recommendations
1. Specific actionable recommendation
2. Specific actionable recommendation

Including Scripts

Pre-made utility scripts offer advantages over asking the AI to generate code:

More reliable

Pre-tested code is more dependable than dynamically generated code.

Save tokens

No code generation required; the AI just runs the script.

Ensure consistency

Same behavior every time, across all uses.

Make clear whether the AI should execute the script or read it as reference:

## Utility Scripts

**Extract form fields** (execute):
python scripts/analyze_form.py input.pdf

**Understand the algorithm** (read as reference):
See scripts/analyze_form.py for the extraction logic

Scripts should handle errors gracefully; include helpful error messages, manage missing files, and document dependencies clearly.

Testing Your Skills

Test with at least one AI tool

Test with the AI tools you plan to target. Try different inputs, including edge cases.

Test across multiple AI tools

Different AI tools may interpret instructions differently. If you list Claude and ChatGPT as supported, test with both.

Iterate based on real usage

Use your skill in real workflows, note where the AI struggles, refine your instructions, and test again.

Content Guidelines

Common Mistakes to Avoid

MistakeWhy it's a problem
Too vague"Be creative" gives the AI no direction
Too verboseExplaining what the AI already knows wastes context tokens
Too longSKILL.md over 500 lines should be split into separate files
Not testedAlways test before publishing
Weak descriptionVague descriptions like "Helps with PDFs" hurt discoverability
Wrong categoryMakes your skill hard to find on Skly
No descriptionBuyers won't purchase what they don't understand
Deeply nested refsKeep file references one level deep from SKILL.md

Checklist Before Publishing

  • Description is specific and includes key trigger terms
  • SKILL.md is under 500 lines
  • Detailed content is split into separate reference files if needed
  • Consistent terminology throughout
  • Examples are concrete, not abstract
  • Workflows have clear, numbered steps
  • Tested with at least one AI tool
  • Tested with real-world usage scenarios
  • No time-sensitive information
  • File references are one level deep

Community Resources

For more recommendations and examples from the community, visit agentskills.io — the open standard behind the skill format used on Skly.

Previous

Skill Format Reference

Next

Claude

On this page