Skip to content

Commit a50c01a

Browse files
devbyraydevbyray
committed
docs(skills): add README and migration guide for Agent Skills
- Add comprehensive README with skill overview and structure - Add MIGRATION.md explaining migration rationale and benefits - Document token usage reduction (~70% baseline savings) - Include validation instructions and contribution guidelines
1 parent 3b43df9 commit a50c01a

2 files changed

Lines changed: 329 additions & 0 deletions

File tree

‎.github/skills/MIGRATION.md‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
# Migration Guide: Custom Instructions to Agent Skills
2+
3+
This document explains the migration from custom instructions to Agent Skills and the rationale behind each decision.
4+
5+
## Why Migrate?
6+
7+
Agent Skills offer several advantages over static custom instructions:
8+
9+
| Feature | Custom Instructions | Agent Skills |
10+
|---------|---------------------|--------------|
11+
| Loading | Always loaded (high token usage) | Loaded dynamically when needed |
12+
| Discovery | Manual file references | Rich metadata for automatic discovery |
13+
| Organization | Single file only | Main file + scripts + references |
14+
| Execution | Instructions only | Can include executable scripts |
15+
| Versioning | File-level only | Metadata versioning support |
16+
17+
## Migration Decision Matrix
18+
19+
### ✅ Migrated to Agent Skills
20+
21+
**Criteria**: Language/framework-specific, task-specific workflows, executable patterns
22+
23+
| Instruction File | Migrated To | Reason |
24+
|-----------------|-------------|---------|
25+
| javascript-typescript.instructions.md | javascript-typescript-standards | Language-specific style guide |
26+
| vue.instructions.md | vue-development | Framework-specific patterns |
27+
| nuxt.instructions.md | nuxt-development | Framework-specific workflows |
28+
| css.instructions.md | css-standards | Language-specific guidelines |
29+
| tailwind.instructions.md | tailwind-css | Framework-specific configuration |
30+
| html.instructions.md | html-standards | Language-specific markup patterns |
31+
| csharp.instructions.md | csharp-standards | Language-specific conventions |
32+
| dotnet.instructions.md | dotnet-development | Framework-specific architecture |
33+
| markdown.instructions.md | markdown-standards | Format-specific workflows |
34+
| testing.instructions.md | testing-tdd | Specific task workflow (TDD) |
35+
| commit.instructions.md | commit-conventions | Specific task workflow (commits) |
36+
37+
### 🔄 Remain as Custom Instructions
38+
39+
**Criteria**: Universal principles, always-applicable security/accessibility, cross-cutting concerns
40+
41+
| Instruction File | Reason to Keep |
42+
|-----------------|----------------|
43+
| best-practices.instructions.md | Universal architecture patterns (SOLID, DRY, KISS) apply to ALL code |
44+
| security.instructions.md | Security must ALWAYS be considered (OWASP Top 10) |
45+
| accessibility.instructions.md | Accessibility principles apply universally to all UI work |
46+
| ui-guidelines.instructions.md | General design principles that transcend specific frameworks |
47+
| config.instructions.md | Project-wide configuration standards |
48+
| project-file-structure.instructions.md | Repository-wide structural conventions |
49+
50+
## Migration Benefits by Skill
51+
52+
### JavaScript/TypeScript Standards
53+
**Before**: 42 lines always loaded
54+
**After**: ~100 tokens for metadata, full skill loaded only when working with JS/TS files
55+
**Benefit**: 80% reduction in constant context usage
56+
57+
### Vue Development
58+
**Before**: 67 lines always loaded
59+
**After**: Loaded only when working with .vue files
60+
**Benefit**: Zero overhead when working on backend or documentation
61+
62+
### Testing TDD
63+
**Before**: 30 lines always loaded
64+
**After**: Loaded only when writing/running tests
65+
**Benefit**: Can include test runner scripts in `scripts/` directory
66+
67+
### Commit Conventions
68+
**Before**: 65 lines always loaded
69+
**After**: Loaded when making commits, includes validation script
70+
**Benefit**: Executable `validate-commit.sh` script available
71+
72+
## Skill Enhancements
73+
74+
Each migrated skill includes enhancements beyond the original instructions:
75+
76+
### 1. Rich Metadata
77+
```yaml
78+
metadata:
79+
author: devbyray
80+
version: "1.0"
81+
framework: "vue3"
82+
depends-on: "vue-development"
83+
```
84+
85+
### 2. Better Discovery
86+
```yaml
87+
description: Coding standards for Vue.js 3 development with Composition API.
88+
Use when working with .vue files, Vue components, composables,
89+
or when the user asks about Vue.js patterns...
90+
```
91+
92+
### 3. Executable Scripts
93+
```
94+
commit-conventions/
95+
├── SKILL.md
96+
└── scripts/
97+
└── validate-commit.sh # Git hook for validation
98+
```
99+
100+
### 4. Expanded Examples
101+
Each skill includes more comprehensive examples and common patterns.
102+
103+
### 5. When to Apply Section
104+
Clear guidance on when the skill should be activated.
105+
106+
## Token Usage Analysis
107+
108+
### Before Migration (All Custom Instructions)
109+
110+
```
111+
Total always-loaded instructions: ~800 lines
112+
Approximate tokens: ~16,000 tokens
113+
```
114+
115+
### After Migration (Skills + Remaining Instructions)
116+
117+
```
118+
Always loaded (Custom Instructions): ~200 lines (~4,000 tokens)
119+
Skills metadata (all 11 skills): ~100 tokens each = ~1,100 tokens
120+
Total baseline: ~5,100 tokens
121+
122+
Active skill when working: +2,000-5,000 tokens (only when relevant)
123+
```
124+
125+
**Net Savings**: ~70% reduction in baseline context usage, with skills loaded only when needed.
126+
127+
## Implementation Notes
128+
129+
### Skill Format Compliance
130+
131+
All migrated skills follow the [Agent Skills specification](https://agentskills.io/specification):
132+
133+
- ✅ Valid YAML frontmatter with `name` and `description`
134+
- ✅ Skill name matches directory name
135+
- ✅ Description includes keywords and use cases
136+
- ✅ Main file kept under 500 lines
137+
- ✅ Optional scripts and references in subdirectories
138+
139+
### Naming Conventions
140+
141+
Skill names follow the spec requirements:
142+
- Lowercase only
143+
- Hyphens for separation (no underscores)
144+
- No leading/trailing hyphens
145+
- No consecutive hyphens
146+
- 1-64 characters
147+
148+
### Dependencies
149+
150+
Some skills depend on others:
151+
- `nuxt-development` depends on `vue-development`
152+
- `dotnet-development` depends on `csharp-standards`
153+
154+
This is documented in the `metadata.depends-on` field.
155+
156+
## Future Enhancements
157+
158+
### Potential Additions
159+
160+
1. **Scripts Directory**
161+
- Linting scripts for each language
162+
- Test runners
163+
- Code formatters
164+
- Validation utilities
165+
166+
2. **References Directory**
167+
- Detailed API references
168+
- Framework-specific deep dives
169+
- Common patterns library
170+
- Troubleshooting guides
171+
172+
3. **Additional Skills**
173+
- `react-development`
174+
- `angular-development`
175+
- `python-standards`
176+
- `docker-workflows`
177+
- `ci-cd-patterns`
178+
179+
## Validation
180+
181+
To ensure skills are valid:
182+
183+
```bash
184+
# Validate all skills
185+
for skill in .github/skills/*/; do
186+
skills-ref validate "$skill"
187+
done
188+
```
189+
190+
## Rollback Plan
191+
192+
If issues arise, revert by:
193+
194+
1. Re-activating original `.instructions.md` files
195+
2. Removing `@import` or skill activation
196+
3. Keeping skills directory for future use
197+
198+
## Conclusion
199+
200+
The migration to Agent Skills provides:
201+
- ✅ Significant reduction in baseline token usage
202+
- ✅ Better organization and discoverability
203+
- ✅ Ability to include executable scripts
204+
- ✅ Progressive disclosure for complex documentation
205+
- ✅ Independent versioning per skill
206+
- ✅ Standards-compliant format
207+
208+
Universal principles (security, accessibility, SOLID) remain as custom instructions to ensure they're always considered.

‎.github/skills/README.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# Agent Skills
2+
3+
This directory contains Agent Skills following the [Agent Skills specification](https://agentskills.io/specification).
4+
5+
## What are Agent Skills?
6+
7+
Agent Skills are modular, discoverable instructions that AI agents can load dynamically based on the task at hand. Unlike static custom instructions that are always loaded, skills are activated only when relevant, reducing context overhead and improving performance.
8+
9+
## Skills in this Repository
10+
11+
### Language & Framework Standards
12+
13+
| Skill | Description | When Used |
14+
|-------|-------------|-----------|
15+
| [javascript-typescript-standards](./javascript-typescript-standards/) | JavaScript/TypeScript coding standards | Working with .js, .ts, .jsx, .tsx files |
16+
| [csharp-standards](./csharp-standards/) | C# coding conventions | Working with .cs files |
17+
| [css-standards](./css-standards/) | CSS/SCSS/SASS best practices | Working with stylesheets |
18+
| [html-standards](./html-standards/) | HTML semantic markup & accessibility | Working with HTML templates |
19+
| [markdown-standards](./markdown-standards/) | Markdown documentation standards | Writing .md files |
20+
21+
### Framework-Specific Skills
22+
23+
| Skill | Description | When Used |
24+
|-------|-------------|-----------|
25+
| [vue-development](./vue-development/) | Vue.js 3 Composition API standards | Working with .vue components |
26+
| [nuxt-development](./nuxt-development/) | Nuxt.js 3 development patterns | Building Nuxt applications |
27+
| [dotnet-development](./dotnet-development/) | .NET project structure & patterns | .NET/ASP.NET Core projects |
28+
| [tailwind-css](./tailwind-css/) | Tailwind CSS v4+ usage | Using Tailwind utility classes |
29+
30+
### Workflow Skills
31+
32+
| Skill | Description | When Used |
33+
|-------|-------------|-----------|
34+
| [testing-tdd](./testing-tdd/) | Test-Driven Development workflow | Writing tests, implementing TDD |
35+
| [commit-conventions](./commit-conventions/) | Conventional Commits standard | Making git commits |
36+
37+
## Skill Structure
38+
39+
Each skill follows the Agent Skills specification:
40+
41+
```
42+
skill-name/
43+
├── SKILL.md # Main skill file with frontmatter and instructions
44+
├── scripts/ # Executable scripts (optional)
45+
│ └── example.sh
46+
└── references/ # Additional reference docs (optional)
47+
└── REFERENCE.md
48+
```
49+
50+
## Using Skills
51+
52+
Skills are automatically discovered by compatible AI agents. The agent will:
53+
54+
1. **Load metadata** (~100 tokens): Reads `name` and `description` from all skills at startup
55+
2. **Activate skill** (<5000 tokens): Loads the full `SKILL.md` when relevant to the task
56+
3. **Load resources** (as needed): Accesses scripts and reference files only when required
57+
58+
This progressive disclosure pattern keeps context usage efficient.
59+
60+
## Migrated from Custom Instructions
61+
62+
The following custom instructions have been converted to Agent Skills for better performance and discoverability:
63+
64+
- ✅ `javascript-typescript.instructions.md` → `javascript-typescript-standards`
65+
- ✅ `vue.instructions.md` → `vue-development`
66+
- ✅ `nuxt.instructions.md` → `nuxt-development`
67+
- ✅ `css.instructions.md` → `css-standards`
68+
- ✅ `tailwind.instructions.md` → `tailwind-css`
69+
- ✅ `html.instructions.md` → `html-standards`
70+
- ✅ `csharp.instructions.md` → `csharp-standards`
71+
- ✅ `dotnet.instructions.md` → `dotnet-development`
72+
- ✅ `markdown.instructions.md` → `markdown-standards`
73+
- ✅ `testing.instructions.md` → `testing-tdd`
74+
- ✅ `commit.instructions.md` → `commit-conventions`
75+
76+
## Remaining as Custom Instructions
77+
78+
These instructions remain as custom instructions because they contain universal architecture patterns that should always be active:
79+
80+
- `best-practices.instructions.md` - SOLID, DRY, KISS principles
81+
- `security.instructions.md` - OWASP Top 10 security patterns
82+
- `accessibility.instructions.md` - Universal accessibility guidelines
83+
- `ui-guidelines.instructions.md` - General design principles
84+
85+
## Validation
86+
87+
To validate skill format:
88+
89+
```bash
90+
# Install skills-ref (if available)
91+
npm install -g @agentskills/skills-ref
92+
93+
# Validate a skill
94+
skills-ref validate .github/skills/javascript-typescript-standards
95+
```
96+
97+
## Contributing
98+
99+
When creating new skills:
100+
101+
1. Follow the [Agent Skills specification](https://agentskills.io/specification)
102+
2. Include clear `name` and `description` in frontmatter
103+
3. Keep main `SKILL.md` under 500 lines
104+
4. Move detailed docs to `references/` directory
105+
5. Add executable scripts to `scripts/` directory
106+
6. Update this README with the new skill
107+
108+
## Benefits of Agent Skills
109+
110+
- 🚀 **Dynamic Loading**: Skills load only when needed
111+
- 📦 **Progressive Disclosure**: Metadata → Instructions → Resources
112+
- 🔍 **Better Discovery**: Rich descriptions help agents identify relevant skills
113+
- 🛠️ **Executable Scripts**: Skills can include automation tools
114+
- 📚 **Organized References**: Complex docs split into focused files
115+
- 🔄 **Version Control**: Skills can be versioned independently
116+
117+
## Resources
118+
119+
- [Agent Skills Documentation](https://agentskills.io/)
120+
- [Agent Skills Specification](https://agentskills.io/specification)
121+
- [Agent Skills GitHub](https://github.com/agentskills/agentskills)

0 commit comments

Comments
 (0)