Skill Authoring

````instructions
---
name: skill-authoring
description: 'Create, structure, and maintain AI agent skills with proper folder layout, templates, scripts, and references. Use when creating a new skill, restructuring an existing one, or reviewing skill quality.'
---

# Skill Authoring

> **Agent-agnostic** — this skill works with any AI coding agent. All instructions use standard CLI tools and Markdown files.

## Overview

Skills are structured knowledge packages that teach AI agents domain-specific
workflows. Each skill lives in `.github/skills/<skill-name>/` and contains a
core `SKILL.md` plus optional scripts, references, and agent configs.

A well-authored skill transforms a generic AI agent into a domain expert
for a specific workflow.

## Follow This Workflow

### 1. Determine skill scope

Before creating a skill, answer these questions:

| Question | Purpose |
| --- | --- |
| What workflow does this skill teach? | Defines the core SKILL.md content |
| What decisions does the agent need to make? | Becomes the decision rules table |
| What automation can support the workflow? | Becomes scripts in `scripts/` |
| What reference material does the agent need? | Becomes docs in `references/` |
| Is this skill standalone or does it depend on others? | Determines cross-references |

### 2. Scaffold the folder structure

```powershell
.github/skills/skill-authoring/scripts/scaffold-skill.ps1 -Name "my-new-skill" -Description "Short description"
```

Or manually create:

```
.github/skills/<skill-name>/
├── SKILL.md            # Core skill (REQUIRED)
├── scripts/            # Automation scripts (optional)
│   └── *.ps1 / *.sh
├── references/         # Reference documents (optional)
│   └── *.md
└── agents/             # Agent interface configs (optional)
    └── openai.yaml
```

### 3. Write SKILL.md using the template

Follow the canonical structure in `references/skill-template.md`. Every SKILL.md must have:

1. **Frontmatter** — `name` and `description` (used by agent discovery)
2. **Title** — H1 with the skill name
3. **Agent-agnostic header** — states this works with any AI agent
4. **Overview** — 2-3 sentences explaining what the skill does
5. **Workflow** — numbered steps with "Follow This Workflow" heading
6. **Decision rules** — table with "Use These Decision Rules" heading
7. **Script parameters** — table documenting each script's parameters
8. **Report format** — how the agent should report results
9. **Escalation rules** — when to stop and ask the human
10. **References** — links to reference docs in the skill folder

### 4. Add automation scripts (if applicable)

Scripts should:
- Use `[CmdletBinding()]` for PowerShell (enables `-Verbose`, `-WhatIf`)
- Include full `.SYNOPSIS`, `.DESCRIPTION`, `.PARAMETER`, `.EXAMPLE` docs
- Use `Set-StrictMode -Version Latest` and `$ErrorActionPreference = "Stop"`
- Return meaningful exit codes (0 = success, non-zero = specific failure)
- Work without user interaction (no `Read-Host`)

### 5. Add reference documents (if applicable)

References provide deep-dive material that would make SKILL.md too long. Common types:

| Reference Type | Purpose | Example |
| --- | --- | --- |
| Playbook | Step-by-step procedures | `remediation-playbook.md` |
| Strategy | Design decisions and rationale | `branch-strategy.md` |
| Profile | Project-specific configuration | `repo-profile.md` |
| Conventions | Standards and formatting rules | `commit-conventions.md` |
| Troubleshooting | Common issues and fixes | `troubleshooting.md` |

### 6. Register the skill

After creating the skill, update `skill-usage-guide.md` to map user prompts to the new skill.

## Use These Decision Rules

| Situation | Action |
| --- | --- |
| Creating a new skill | Run scaffold script, then fill in SKILL.md from template |
| SKILL.md exceeds 200 lines | Extract sections into `references/` docs |
| Workflow has repeatable steps | Create a script in `scripts/` |
| Skill targets a specific AI platform | Add config in `agents/` |
| Skill depends on another skill | Add cross-reference in the References section |
| Skill overlaps with existing skill | Merge or create a clear boundary |

## Skill Quality Checklist

Every skill should pass this checklist before being considered complete:

### SKILL.md

- [ ] Has frontmatter with `name` and `description`
- [ ] Description mentions keywords that trigger this skill
- [ ] Has agent-agnostic header
- [ ] Overview explains purpose in 2-3 sentences
- [ ] Workflow has numbered, actionable steps
- [ ] Each step starts with a verb (imperative mood)
- [ ] Decision rules cover common scenarios
- [ ] Script parameters are documented in tables
- [ ] Report format is specified
- [ ] Escalation rules define when to ask the human
- [ ] References section links to all reference docs

### Scripts

- [ ] Every script has a `.SYNOPSIS` and `.DESCRIPTION`
- [ ] All parameters are documented with `.PARAMETER`
- [ ] Exit codes are documented in `.NOTES`
- [ ] Scripts work without user interaction
- [ ] Error handling uses try/catch with meaningful messages

### References

- [ ] Each reference focuses on one topic
- [ ] References are linked from SKILL.md
- [ ] No duplicate content between SKILL.md and references

### Agents

- [ ] `openai.yaml` has `display_name`, `short_description`, `default_prompt`
- [ ] Default prompt references the SKILL.md path

## Script Parameters

### `scripts/scaffold-skill.ps1`

| Parameter | Description |
| --- | --- |
| `-Name` | Skill name in kebab-case (e.g., `my-new-skill`) |
| `-Description` | Short description for the frontmatter |
| `-WithScripts` | Create the `scripts/` folder with a template script |
| `-WithReferences` | Create the `references/` folder with a template doc |
| `-WithAgents` | Create the `agents/` folder with an openai.yaml template |
| `-Full` | Create all optional folders (equivalent to all three flags) |
| `-SkillsDir` | Base skills directory (default: `.github/skills`) |

## Report Results in This Format

```
Skill: <skill-name>
Location: .github/skills/<skill-name>/
Files created:
  ✓ SKILL.md (core skill)
  ✓ scripts/scaffold-skill.ps1
  ✓ references/skill-template.md
  ✓ agents/openai.yaml
Quality checklist: 11/11 items passed
Status: Ready for use
```

## Escalate Only When Needed

- Escalate if the skill's scope overlaps significantly with an existing skill.
- Escalate if the skill requires platform-specific behavior that can't be abstracted.
- Escalate if the skill needs secrets or credentials to function.

## References

- Canonical SKILL.md template: `references/skill-template.md`
- Naming and organization conventions: `references/conventions.md`

````