skill-creator · v1.0.0 · 2026-09-03 · sha256 b5454d82a99c1241
skill-creator v1.0.0A
Immutable. This exact content is served forever at /api/v1/blob/b5454d82a99c1241.
---
name: "skill-creator"
description: 'Create, validate, and maintain AgentX skills following the agentskills.io specification. Use when scaffolding a new skill, auditing skill compliance, restructuring for progressive disclosure, or adding scripts/references/assets to an existing skill.'
metadata:
author: "AgentX"
version: "1.0.0"
created: "2025-01-15"
updated: "2025-01-15"
compatibility:
frameworks: ["agentx"]
platforms: ["windows", "linux", "macos"]
---
# Skill Creator
> Create, validate, and maintain skills that follow the [agentskills.io](https://agentskills.io) open specification.
## When to Use
- Creating a new skill from scratch
- Auditing existing skills for spec compliance
- Restructuring a skill for progressive disclosure
- Adding scripts/, references/, or assets/ to an existing skill
## Knowledge vs Execution Principle
Every agent task is either a **knowledge problem** or an **execution problem**:
| Problem Type | Solution | Example |
|---|---|---|
| **Knowledge** (know something) | Skill (Markdown) | Coding standards, triage workflows, deployment conventions |
| **Execution** (do something) | MCP Server | Query a database, create a GitHub issue, send an email |
| **Hybrid** (know how to do well) | Skill that references MCP tools | Skill encodes workflow + judgment; MCP provides API calls |
**Standalone Principle**: Every skill SHOULD produce useful output without MCP connections.
If disconnecting all MCP servers makes the skill non-functional, the knowledge layer is
not properly separated from the execution layer.
When deciding whether to create a skill or an MCP server, ask:
1. Is it stable knowledge (changes weekly/monthly)? -> Skill
2. Does it require a live API call at runtime? -> MCP
3. Both? -> Skill that orchestrates MCP tools as a subordinate layer
## Decision Tree
```
Need to work on a skill?
+- Creating new skill?
| +- Run: scripts/init-skill.ps1
| - Fill in SKILL.md template
+- Auditing existing skill?
| +- Check frontmatter against spec (see Frontmatter Rules)
| +- Check line count (target < 500, ideal < 350)
| - Verify progressive disclosure structure
+- Skill too large (> 500 lines)?
| +- Extract detailed examples -> references/
| +- Extract executable logic -> scripts/
| - Keep SKILL.md as slim router
- Adding capability to existing skill?
+- Executable automation -> scripts/
+- Extended docs/examples -> references/
- Templates, starter code, sample data -> assets/
```
## Quick Start: Create a New Skill
```powershell
# Scaffold a new skill with all directories
./.github/skills/development/skill-creator/scripts/init-skill.ps1 `
-Name "my-new-skill" `
-Category "development" `
-Description "Brief description of the skill" `
-WithScripts -WithReferences
```
This creates:
```
.github/skills/development/my-new-skill/
+-- SKILL.md # Main skill document
+-- scripts/
| -- example.ps1 # Starter script
+-- references/
| -- reference-guide.md # Extended content
-- assets/ # (with -WithAssets)
-- .gitkeep # Templates, starter code, sample data
```
## Core Rules (Frontmatter)
### Required Fields
| Field | Rules | Example |
|-------|-------|---------|
| `name` | lowercase, hyphens, 1-64 chars | `"api-design"` |
| `description` | 1-1024 chars, plain text | `"REST API design patterns"` |
### Recommended Fields
| Field | Purpose | Example |
|-------|---------|---------|
| `metadata.author` | Attribution | `"AgentX"` |
| `metadata.version` | Skill version (SemVer) | `"1.0.0"` |
| `metadata.created` | Creation date | `"2025-01-15"` |
| `metadata.updated` | Last update date | `"2025-01-15"` |
| `compatibility.languages` | Language scope | `["csharp", "python"]` |
| `compatibility.frameworks` | Framework scope | `["dotnet", "flask"]` |
| `compatibility.platforms` | OS scope | `["windows", "linux"]` |
| `prerequisites` | Required tools, MCP servers, env | `["Node.js 24+", "Docker"]` |
| `allowed-tools` | Space-delimited tool names | `"read_file run_in_terminal"` |
| `argument-hint` | Slash-command input hint | `"[target] [options]"` |
| `user-invocable` | Show in slash-command menu | `false` for background knowledge |
| `disable-model-invocation` | Disable automatic activation | `true` for manual-only workflows |
| `context` | Inline or forked execution | `fork` for read-heavy focused reports |
### Frontmatter Template
```yaml
---
name: "skill-name"
description: 'Create, validate, and maintain AgentX skills following the agentskills.io specification. Use when scaffolding a new skill, auditing skill compliance, restructuring for progressive disclosure, or adding scripts/references/assets to an existing skill.'
metadata:
author: "AgentX"
version: "1.0.0"
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
compatibility:
languages: ["lang1", "lang2"]
frameworks: ["framework1"]
platforms: ["windows", "linux", "macos"]
prerequisites: ["tool or runtime required"]
allowed-tools: "tool1 tool2 tool3"
---
```
## Progressive Disclosure Pattern
Skills load in 3 tiers to manage context window tokens:
| Tier | What Loads | Token Budget | When |
|------|-----------|--------------|------|
| **Metadata** | Frontmatter only | ~100 tokens | Always (skill discovery) |
| **Body** | SKILL.md content | < 5,000 tokens | On skill activation |
| **Extended** | references/ files | Variable | On-demand via `read_file` |
### Structure Rules
1. **SKILL.md** (< 500 lines, ideal < 350): Decision tree, quick start, core rules, pattern summaries
2. **references/**: Detailed examples, extended documentation, edge cases
3. **scripts/**: Executable automation (scanners, scaffolders, validators)
4. **assets/**: Reusable templates, starter code, sample data, report templates
### Assets Directory Convention
| Content Type | Example | When to Use |
|-------------|---------|-------------|
| Code templates | `pyspark_transforms.py` | Reusable starter code for the skill domain |
| Report templates | `completion_report_template.md` | Structured output documents |
| Config templates | `pipeline-templates.json` | Pre-built configurations |
| Sample data | `sample-input.csv` | Test/demo data for the skill |
| Prompt templates | `system-prompt.md` | AI prompt patterns for the skill |
## Skill Quality Checklist
The executable quality gate is `scripts/score-skill.ps1`, using the deterministic
[Skill Quality Rubric](../../../../evaluation/rubrics/skill-quality.md). It emits
eight weighted dimensions, blocking findings, a 0-100 score, a tier, and JSON
evidence. Use `-Enforce` for new or changed skills; all-inventory mode reports
existing score debt while always failing universal blockers.
- [ ] Frontmatter has `name` and `description` (required)
- [ ] Frontmatter has `metadata.version` (recommended)
- [ ] SKILL.md is under 500 lines
- [ ] Has a decision tree section
- [ ] Has "When to Use" section with WHEN: trigger phrase
- [ ] Has "Core Rules" section
- [ ] Has "Error Handling" section
- [ ] Has "Anti-Patterns" section
- [ ] Large examples are in references/ (not inline)
- [ ] Executable tools are in scripts/ (not just documented)
- [ ] Reusable templates/starter code in assets/ (not inline)
- [ ] `prerequisites` listed if skill requires external tools
- [ ] Added to Skills.md master index
## Required Sections Standard
Every SKILL.md MUST include these sections:
| Section | Purpose |
|---------|---------|
| Frontmatter | `name`, `description` (50+ chars) |
| When to Use | WHEN: trigger phrase describing file patterns and keywords |
| Decision Tree | Quick routing for sub-decisions |
| Core Rules | 3-5 actionable rules |
| Error Handling | What to do when things go wrong in this skill domain |
| Checklist | Pre-handoff verification items |
**Required for `development/` category**: skills under `.github/skills/development/` MUST also include a `## Rationalization Table` section between `## Prerequisites` (or `## When to Use`) and `## Decision Tree`. The table lists 5-8 common excuses an agent or human uses to skip the skill's discipline, paired with a one-line rebuttal. This is the highest-leverage section against LLM rationalization patterns. Format:
```markdown
## Rationalization Table
| Rationalization | Reality |
|-----------------|---------|
| "{the excuse the agent would make}" | {why the excuse is wrong and what to do instead} |
```
Other categories (architecture, languages, ai-systems, etc.) MAY include a Rationalization Table when the skill encodes a discipline that is commonly skipped under pressure.
**WHEN: Trigger Phrase**: Every skill SHOULD start with a `> WHEN:` blockquote after the title
that describes when to load the skill. This enables better routing by agents.
Example:
```markdown
# API Design
> WHEN: Creating REST endpoints, designing API versioning, adding pagination or rate limiting.
```
## Anti-Patterns
- **Monolith skills**: > 500 lines with no references/ -> split them
- **Missing frontmatter**: No `name` or `description` -> spec violation
- **Code-dump skills**: Walls of example code -> move to references/
- **Undiscoverable skills**: Not listed in Skills.md -> invisible to routing
- **Stale metadata**: `version` never bumped after changes -> unreliable
- **MCP-dependent skills**: Skills that do nothing without an MCP server -> separate knowledge from execution
- **Token-tax skills**: Encoding knowledge via MCP tool schemas (~23K-50K tokens) instead of a skill file (~200-500 tokens)
## Scripts
- `scripts/init-skill.ps1` - Scaffold a new skill with proper structure and frontmatter