add-new-skill

name	add-new-skill
description	Create a new skill for this repository following the agentskills.io specification with proper structure and packaging

Add New Skill to Skills Repository

This meta skill guides the creation of new skills for this repository, following the agentskills.io specification.

Repository Context

This repository houses skills that are:

• Packaged as individual .zip artifacts via GitHub Actions
• Structured according to agentskills.io specification
• Consumable by Claude Code, Codex, and other AI tools

agentskills.io Specification Summary

Required Structure

Every skill MUST have:

skill-name/
└── SKILL.md          # Required file with YAML frontmatter

Optional Directories

Skills MAY include:

skill-name/
├── SKILL.md          # Required
├── scripts/          # Executable code (Python, Bash, JavaScript)
├── references/       # Additional docs loaded on-demand
└── assets/           # Templates, images, data files

SKILL.md Format

Required Frontmatter

---
name: skill-name
description: A clear description of what this skill does and when to use it (1-1024 characters).
---

Frontmatter Field Rules

name (REQUIRED):

• 1-64 characters
• Lowercase alphanumeric and hyphens only
• Cannot start/end with hyphens
• Cannot contain consecutive hyphens
• MUST match parent directory name

description (REQUIRED):

• 1-1024 characters
• Should explain what the skill does and when to use it
• Be specific and actionable

Optional Frontmatter Fields

---
name: skill-name
description: Description here
license: MIT
compatibility: Requires Python 3.8+, works on Linux/macOS
metadata:
  version: "1.0.0"
  author: "Your Name"
allowed-tools: Read Write Bash
---

Content Guidelines

After frontmatter, include:

• Overview: What the skill does
• When to Use: Clear use cases
• Step-by-Step Instructions: Detailed workflow
• Examples: Real-world usage patterns
• Templates: Output formats or code snippets
• Validation: Checklists or verification steps

Keep SKILL.md under 5000 tokens (recommended) for efficient loading.

Workflow: Adding a New Skill

1. Create Skill Directory

mkdir -p skill-name

CRITICAL: Directory name MUST match the name field in frontmatter.

2. Write SKILL.md

Create skill-name/SKILL.md with:

• Required YAML frontmatter (name, description)
• Clear markdown instructions
• Examples and templates
• Validation steps

3. Add Optional Resources (If Needed)

scripts/ - Add executable code:

mkdir -p skill-name/scripts
# Add Python/Bash/JS files

references/ - Add supporting docs:

mkdir -p skill-name/references
# Add REFERENCE.md, FORMS.md, etc.

assets/ - Add static files:

mkdir -p skill-name/assets
# Add templates, images, data files

4. Validate Skill Structure

Check that:

• Directory name matches frontmatter name field
• Name is lowercase, alphanumeric + hyphens only
• Name doesn't start/end with hyphens
• No consecutive hyphens in name
• Description is 1-1024 characters
• SKILL.md has valid YAML frontmatter
• Instructions are clear and actionable

5. Test Locally (Optional)

Verify zip structure matches specification:

cd skill-name
zip -r ../test-skill.zip . -x "*.git*"
cd ..
unzip -l test-skill.zip
# Should show: skill-name/SKILL.md, skill-name/scripts/, etc.
rm test-skill.zip

6. Commit and Push

git add skill-name/
git commit -m "feat: add skill-name skill

Brief description of what this skill does.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <[e-mail]>"
git push

7. Verify GitHub Actions

After push:

1. Go to Actions tab in GitHub repository
2. Wait for "Package Skills" workflow to complete
3. Check that new skill artifact was created
4. Download and verify zip structure contains parent directory

GitHub Actions Workflow

The repository includes .github/workflows/package-skills.yml which:

• Discovers all directories containing SKILL.md
• Packages each skill with proper directory structure
• Creates individual artifacts per skill (e.g., skill-name.zip)
• Runs on push to main, pull requests, and manual dispatch

Package Structure: Each zip contains the parent directory:

skill-name.zip
└── skill-name/
    ├── SKILL.md
    ├── scripts/
    ├── references/
    └── assets/

This matches the agentskills.io specification for tool consumption.

Examples from This Repository

Example 1: Infrastructure Automation Skill

Directory: new-homelab-guest/

Characteristics:

• Single SKILL.md file with detailed Terraform workflow
• No scripts (relies on external repository)
• Includes prerequisites, step-by-step instructions
• Has troubleshooting section and examples

Good for: Complex multi-step workflows, infrastructure tasks

Example 2: Data Processing Skill

Directory: digitize-pounce-scoresheet/

Characteristics:

• Single SKILL.md with data extraction workflow
• Includes output format template
• Has validation checklist
• Explains domain-specific context (game rules)
• Provides common patterns guide

Good for: Data transformation, format conversion, OCR tasks

Example 3: Meta Skill (This One!)

Directory: add-new-skill/

Characteristics:

• Documents repository conventions
• Links to external specification
• Provides step-by-step workflow
• Includes validation checklist
• References existing examples

Good for: Repository documentation, process guides

Common Skill Patterns

Pattern 1: Step-by-Step Workflow

For tasks with clear sequential steps:

## Workflow

### 1. Prepare Environment
Instructions here...

### 2. Execute Task
Instructions here...

### 3. Validate Output
Checklist...

Pattern 2: Template-Based Output

For skills that generate structured output:

## Output Format Template

```yaml
key: value
nested:
  - item1
  - item2

### Pattern 3: Context + Instructions
For domain-specific tasks:
```markdown
## Domain Context
Background information...

## Processing Steps
1. Step one
2. Step two

## Validation
Checklist...

Naming Conventions

Good Skill Names

• new-homelab-guest - Action-oriented, clear purpose
• digitize-pounce-scoresheet - Verb + specific task
• add-new-skill - Clear action and object
• parse-terraform-state - Specific transformation
• generate-api-docs - Clear output type

Bad Skill Names

• Homelab - Too generic, not action-oriented
• scoresheet_digitizer - Uses underscore (use hyphens)
• new_skill - Uses underscore
• my-awesome-skill - Not descriptive
• -skill-name- - Invalid (starts/ends with hyphen)
• skill--name - Invalid (consecutive hyphens)

Tips for Writing Effective Skills

1. Be Specific: Describe exactly what the skill does and when to use it
2. Include Context: Explain domain-specific concepts needed to execute the task
3. Provide Examples: Show real-world usage patterns
4. Add Validation: Include checklists or verification steps
5. Use Templates: Provide output format templates when applicable
6. Keep It Focused: One skill should do one thing well
7. Consider Progressive Disclosure: Put essential info in SKILL.md, details in references/
8. Test Instructions: Verify steps are complete and executable

Troubleshooting

Skill Not Packaged

Problem: New skill doesn't appear in GitHub Actions artifacts Solution:

• Verify SKILL.md exists in subdirectory
• Check directory depth (should be 2 levels: ./skill-name/SKILL.md)
• Review Actions logs for errors

Invalid Directory Name

Problem: Directory name doesn't match frontmatter Solution:

• Rename directory: git mv old-name new-name
• Or update frontmatter name field to match directory

Workflow Fails on Push

Problem: GitHub Actions fails with zip error Solution:

• Check for special characters in filenames
• Verify YAML frontmatter is valid
• Review workflow logs for specific error

Progressive Disclosure Strategy

Per agentskills.io specification:

Tier 1 - Metadata (~100 tokens): Loaded at startup

• Just the frontmatter fields

Tier 2 - SKILL.md (<5000 tokens): Loaded when skill is activated

• Full instructions in SKILL.md

Tier 3 - Supporting files: Loaded on demand

• Files in scripts/, references/, assets/

Keep SKILL.md concise. Move detailed docs to references/, long code to scripts/, and data/templates to assets/.

Validation Checklist

Before committing a new skill:

• Directory name matches frontmatter name field exactly
• Name uses only lowercase, alphanumeric, and hyphens
• Name doesn't start or end with hyphens
• Name doesn't contain consecutive hyphens
• Description is between 1-1024 characters
• SKILL.md has valid YAML frontmatter (use --- delimiters)
• Instructions are clear and actionable
• Examples or templates are provided where applicable
• Validation steps or checklists included
• SKILL.md is under 5000 tokens (if possible)
• Optional directories (scripts/, references/, assets/) are used appropriately
• Git commit message follows conventional format

Resources

• agentskills.io Specification: https://agentskills.io/specification
• agentskills.io Home: https://agentskills.io/
• This Repository: Check existing skills for patterns and examples
• GitHub Actions Workflow: .github/workflows/package-skills.yml