Agent Skill creation workflow. Use when creating new reusable AI agent skills,
scaffolding skill directories, or converting existing guides into the
portable Agent Skills standard format.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Agent Skill creation workflow. Use when creating new reusable AI agent skills,
scaffolding skill directories, or converting existing guides into the
portable Agent Skills standard format.
Agent Skills are capability modules that give AI agents new abilities. Unlike workflows (which guide how to approach tasks), skills define what an agent can do. Skills are portable across 25+ agent products including Claude Code, Cursor, and VS Code.
When to Use
Use this skill when you need to:
Create a new reusable AI agent capability
Scaffold a skill directory structure
Convert an existing guide or workflow into the Agent Skills format
Build a capability module for AI agents
About Skills
Skills are modular, self-contained packages that extend AI capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks - they transform a general-purpose agent into a specialized one equipped with procedural knowledge that no model can fully possess.
What Skills Provide:
Specialized workflows - Multi-step procedures for specific domains
Tool integrations - Instructions for working with specific file formats or APIs
Domain expertise - Company-specific knowledge, schemas, business logic
Bundled resources - Scripts, references, and assets for complex and repetitive tasks
Process
Step 1: Define the Skill
Before creating the skill, understand it through concrete examples. Ask questions like:
"What functionality should this skill support?"
"Can you give examples of how this skill would be used?"
"What would a user say that should trigger this skill?"
Then clarify its purpose:
What capability does this skill provide?
Example: "Process PDF files", "Generate API documentation", "Manage database migrations"
When should it activate? (Critical for the description field)
What user requests should trigger this skill?
What keywords or contexts indicate this skill is needed?
The description is the primary triggering mechanism - include all "when to use" information there, not in the body (the body is only loaded after triggering)
What resources does it need?
Scripts for deterministic operations that are repeatedly rewritten?
Reference documentation for domain knowledge?
Templates or assets for output generation?
What's the scope?
Keep skills focused on one capability
Split large skills into multiple smaller ones
Step 2: Scaffold the Skill
Run the Samuel CLI command:
samuel skill create <skill-name>
Name Requirements:
Lowercase alphanumeric and hyphens only
No consecutive hyphens (--)
Cannot start or end with hyphen
Maximum 64 characters
This creates:
.claude/skills/<skill-name>/
├── SKILL.md # Pre-filled template
├── scripts/ # For executable code
├── references/ # For additional docs
└── assets/ # For templates, data
Step 3: Write SKILL.md
Edit the generated SKILL.md with:
Required Frontmatter
---name:skill-namedescription:|
What this skill does and when to use it.
Include specific triggers and keywords.
license:MITmetadata:author:your-nameversion:"1.0"---
Description Best Practices:
Describe both what and when
Include keywords that trigger activation
Be specific, not vague ("Process PDF files" not "Helps with documents")
Maximum 1024 characters
Body Content
Write clear instructions that tell the AI agent how to use this skill:
Purpose: What capability this provides
When to Use: Scenarios that trigger this skill
Instructions: Step-by-step procedure
Examples: Input/output pairs
Notes: Warnings, edge cases, best practices
Keep under 500 lines - use reference files for detailed content.
Run validation to check against Agent Skills spec:
samuel skill validate <skill-name>
Validation Checks:
SKILL.md exists with valid YAML frontmatter
Name matches directory name
Name format is correct
Description is present
No fields exceed length limits
Fix any errors before proceeding.
Step 6: Test
Test the skill with real tasks:
Load the skill in your AI agent
Try scenarios from "When to Use"
Verify instructions are followed correctly
Check that examples produce expected output
Test edge cases
Step 7: Document
If the skill is significant, record in .claude/memory/:
# .claude/memory/YYYY-MM-DD-skill-name.md## Skill Created: <skill-name>**Purpose**: Brief description
**Key Decisions**:
- Why this approach
- Alternatives considered
**Testing Notes**:
- What worked
- What needed adjustment
Best Practices
Concise is Key
The context window is a public good. Skills share it with everything else: system prompt, conversation history, other skills' metadata, and the actual user request. Default assumption: the AI is already very smart. Only add context it doesn't already have. Challenge each piece of information: "Does this paragraph justify its token cost?"
Good (50 tokens):
## Extract PDF Text
Use pdfplumber:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
**Bad** (150 tokens):
```markdown
## Extract PDF Text
PDF files are a common format... [unnecessary explanation]
Set Appropriate Degrees of Freedom
Match the level of specificity to the task's fragility and variability. Think of the AI as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).
Freedom Level
When to Use
Implementation
Example
High
Multiple valid approaches
Text-based instructions
Code review process
Medium
Preferred pattern exists
Pseudocode or scripts with parameters
Report generation
Low
Fragile/critical operations
Specific scripts, few parameters
Database migrations
Use Progressive Disclosure
Metadata (~100 tokens): Always loaded
SKILL.md body (<5000 tokens): Loaded on activation
References/Scripts: Loaded on-demand
Keep SKILL.md lean; move details to reference files.
What NOT to Include
A skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation like README.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md, or CHANGELOG.md. The skill should only contain information needed for an AI agent to do the job at hand.
Bundled Resource Guidelines
Scripts (scripts/): Include when the same code is being rewritten repeatedly or deterministic reliability is needed. Scripts may be executed without loading into context, saving tokens.
References (references/): For documentation the AI should reference while working. Keeps SKILL.md lean; loaded only when determined needed. If files are large (>10k words), include grep search patterns in SKILL.md. Avoid duplication - information should live in either SKILL.md or references, not both.
Assets (assets/): Files not intended to be loaded into context, but used in the output (templates, images, boilerplate code, fonts).
Provide Examples
Examples teach better than explanations:
### Example: User Request**Input**: "Help me merge these PDFs"
**Output**:
```python
# Code that handles the request
---
## Checklist
Before finalizing your skill:
- [ ] Name follows conventions (lowercase, hyphens, max 64 chars)
- [ ] Description is specific and under 1024 chars
- [ ] SKILL.md body is under 500 lines
- [ ] Instructions are clear and step-by-step
- [ ] Examples show input/output pairs
- [ ] Validation passes (`samuel skill validate`)
- [ ] Tested with real scenarios
- [ ] Scripts handle errors gracefully (if applicable)
---
## Related
- **Agent Skills Specification**: https://agentskills.io/specification
- **Example Skills**: https://github.com/anthropics/skills
- **Skills README**: `.claude/skills/README.md`
