SKILL.md - AiToEarn

SKILL.md

1	---
2	name: write-a-skill
3	description: Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill.
4	---
5
6	# Writing Skills
7
8	## Process
9
10	1. Gather requirements - ask user about:
11	- What task/domain does the skill cover?
12	- What specific use cases should it handle?
13	- Does it need executable scripts or just instructions?
14	- Any reference materials to include?
15
16	2. Draft the skill - create:
17	- SKILL.md with concise instructions
18	- Additional reference files if content exceeds 500 lines
19	- Utility scripts if deterministic operations needed
20
21	3. Review with user - present draft and ask:
22	- Does this cover your use cases?
23	- Anything missing or unclear?
24	- Should any section be more/less detailed?
25
26	## Skill Structure
27
28	```
29	skill-name/
30	├── SKILL.md # Main instructions (required)
31	├── REFERENCE.md # Detailed docs (if needed)
32	├── EXAMPLES.md # Usage examples (if needed)
33	└── scripts/ # Utility scripts (if needed)
34	└── helper.js
35	```
36
37	## SKILL.md Template
38
39	```md
40	---
41	name: skill-name
42	description: Brief description of capability. Use when [specific triggers].
43	---
44
45	# Skill Name
46
47	## Quick start
48
49	[Minimal working example]
50
51	## Workflows
52
53	[Step-by-step processes with checklists for complex tasks]
54
55	## Advanced features
56
57	[Link to separate files: See [REFERENCE.md](REFERENCE.md)]
58	```
59
60	## Description Requirements
61
62	The description is the only thing your agent sees when deciding which skill to load. It's surfaced in the system prompt alongside all other installed skills. Your agent reads these descriptions and picks the relevant skill based on the user's request.
63
64	Goal: Give your agent just enough info to know:
65
66	1. What capability this skill provides
67	2. When/why to trigger it (specific keywords, contexts, file types)
68
69	Format:
70
71	- Max 1024 chars
72	- Write in third person
73	- First sentence: what it does
74	- Second sentence: "Use when [specific triggers]"
75
76	Good example:
77
78	```
79	Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.
80	```
81
82	Bad example:
83
84	```
85	Helps with documents.
86	```
87
88	The bad example gives your agent no way to distinguish this from other document skills.
89
90	## When to Add Scripts
91
92	Add utility scripts when:
93
94	- Operation is deterministic (validation, formatting)
95	- Same code would be generated repeatedly
96	- Errors need explicit handling
97
98	Scripts save tokens and improve reliability vs generated code.
99
100	## When to Split Files
101
102	Split into separate files when:
103
104	- SKILL.md exceeds 100 lines
105	- Content has distinct domains (finance vs sales schemas)
106	- Advanced features are rarely needed
107
108	## Review Checklist
109
110	After drafting, verify:
111
112	- [ ] Description includes triggers ("Use when...")
113	- [ ] SKILL.md under 100 lines
114	- [ ] No time-sensitive info
115	- [ ] Consistent terminology
116	- [ ] Concrete examples included
117	- [ ] References one level deep
118

118 lines MARKDOWN