add-new-skill

name	add-new-skill
description	Guide for creating effective Agent Skills for the torrust-tracker-demo project. Use when you need to create a new skill (or update an existing skill) that extends AI agent capabilities with specialized knowledge, workflows, or tool integrations. Triggers on "create skill", "add new skill", "how to add skill", or "skill creation".
metadata	{"author":"torrust","version":"1.0"}

Creating New Agent Skills

This skill guides you through creating effective Agent Skills for the Torrust Tracker Demo project.

About Skills

What are Agent Skills?

Agent Skills are specialized instruction sets that extend AI agent capabilities with domain-specific knowledge,workflows, and tool integrations. They follow the agentskills.io open format and work with multiple AI coding agents (Claude Code, VS Code Copilot, Cursor, Windsurf).

Progressive Disclosure

Skills use a three-level loading strategy to minimize context window usage:

1. Metadata (~100 tokens): name and description loaded at startup for all skills
2. skill.md Body (<5000 tokens): Loaded when a task matches the skill's description
3. Bundled Resources: Loaded on-demand only when referenced (scripts, references, assets)

When to Create a Skill vs Updating AGENTS.md

Use AGENTS.md for...	Use Skills for...
Always-on rules and constraints	On-demand workflows
"Always do X, never do Y"	Multi-step repeatable processes
Baseline conventions	Specialist domain knowledge
Rarely changes	Can be added/refined frequently

Example: "Use conventional commits" → AGENTS.md rule. "How to add a new service to the compose setup" → Skill.

Core Principles

1. Concise is Key

Context window is shared between system prompt, conversation history, other skills, and your actual request.

Default assumption: Claude is already very smart. Only add context Claude doesn't already have.

Challenge each piece of information:

• "Does Claude really need this explanation?"
• "Can I assume Claude knows this?"
• "Does this paragraph justify its token cost?"

Example:

✅ Good (20 tokens):

## Check spelling

Run: `npx cspell "**/*"`

❌ Bad (80 tokens):

## Check spelling

Spell checking is important to ensure documentation quality. CSpell is a
spell checker that supports many file types. To run it, you need Node.js
installed. Then you can use npx to run it without installing it globally...

2. Set Appropriate Degrees of Freedom

Match specificity to task fragility:

High freedom (text-based instructions):

• Multiple approaches are valid
• Decisions depend on context
• Heuristics guide the approach

Medium freedom (pseudocode or scripts with parameters):

• A preferred pattern exists
• Some variation is acceptable
• Configuration affects behavior

Low freedom (specific scripts, few/no parameters):

• Operations are fragile and error-prone
• Consistency is critical
• Specific sequence must be followed

Analogy: Think of Claude as a robot exploring a path:

• Narrow bridge with cliffs: Provide exact instructions (low freedom)
• Open field with no hazards: Give general direction (high freedom)

3. Anatomy of a Skill

A skill consists of:

• skill.md: Frontmatter (metadata) + body (instructions)
• Optional bundled resources: scripts/, references/, assets/

Keep skill.md concise (<500 lines). Move detailed content to reference files.

4. Progressive Disclosure

Keep skill.md under 500 lines. Split detailed content into reference files that are loaded only when needed.

Pattern: Main skill.md provides overview with links to detailed materials:

## Advanced Features

**Full specification**: See [specification.md](references/specification.md) for Agent Skills spec
**Proven patterns**: See [patterns.md](references/patterns.md) for workflow patterns
**Examples**: See [examples.md](references/examples.md) for real skill examples

5. Content Strategy: Duplication vs Linking

Three-tier approach for organizing skill content relative to official project documentation:

Tier 1: Self-Contained in skill.md (Core Workflows)

Include essential commands and workflows directly:

• Command syntax: cargo run --bin linter all
• Step-by-step workflows
• Quick reference tables

Why: Agent executes immediately without extra file reads.

Tier 2: Progressive Disclosure via references/ (Supporting Details)

Place detailed information in references/ directory:

• Detailed descriptions (what each tool does)
• Configuration options and flags
• Troubleshooting guides
• Examples and patterns

Why: Keeps skill.md concise; agent loads selectively when needed.

Tier 3: Links to Official Docs (Deep Context & Authority)

Link to official documentation for context that already exists elsewhere. Avoid duplicating content that has a single authoritative source.

Why: Official docs are the single source of truth.

Decision Tree:

Is this essential to execute the workflow immediately?
├─ YES → Include in skill.md (Tier 1)
└─ NO → Is this supporting detail agent may need?
    ├─ YES → Include in references/ (Tier 2)
    └─ NO → Link to official docs (Tier 3)

Skill Creation Process

Step 1: Understanding the Skill

Start with concrete examples of when the skill should activate:

Questions to answer:

• What specific queries should trigger this skill?
• What tasks does it help accomplish?
• What domain knowledge does it provide?

Example:

"I want a skill that helps with deploying tracker instances. It should activate when users ask 'deploy tracker', 'provision environment', or 'full deployment workflow'."

Step 2: Planning Reusable Contents

Identify what resources the skill needs:

Scripts (scripts/):

• Validation scripts
• Code generation utilities
• Deterministic operations

References (references/):

• API documentation
• Detailed specifications
• Domain-specific guides
• Configuration schemas

Assets (assets/):

• Templates
• Boilerplate code
• Images/diagrams
• Example files

Step 3: Creating Directory Structure

Skills live under .github/skills/, one directory per skill:

.github/skills/
└── add-new-skill/   # Meta skill
└── skill-name/      # Other skills

Create the skill directory:

mkdir -p .github/skills/skill-name/references
touch .github/skills/skill-name/skill.md

Naming convention: Use gerund form (verb + -ing) or noun phrases:

• ✅ Good: writing-documentation, adding-services, managing-backups
• ❌ Avoid: helper, utils, tools (too vague)

Step 4: Writing skill.md

Frontmatter (Required)

---
name: skill-name
description: What this skill does AND when to use it. Include trigger phrases here because the body is only loaded AFTER the skill is triggered. Triggers on "keyword1", "keyword2", "keyword3".
metadata:
  author: torrust
  version: "1.0"
---

Important: description must be a plain single-line string. Do not use YAML block scalars (|) or folded scalars (>). The IDE skill-file parser treats multi-line forms as unexpected indentation and reports unsupported attributes, causing the skill to fail to load.

Critical: The description must include:

1. What the skill does
2. When to use it (trigger conditions)
3. Key terms and trigger phrases

Why? Claude uses the description to decide whether to load the skill. If trigger phrases aren't in the description, the skill won't activate.

Body Structure

Recommended sections:

1. Overview - Brief introduction
2. When to Use - Specific scenarios
3. Workflow/Instructions - Step-by-step process
4. Common Patterns - Frequently used approaches
5. References - Links to bundled resources

Keep instructions:

• Imperative/infinitive form ("Run this", "Check that")
• Focused and actionable
• Free of unnecessary explanations

Step 5: Adding Bundled Resources

Create reference files for detailed information:

# Example: API documentation
cat > .github/skills/skill-name/references/api-reference.md << 'EOF'
# API Reference

Complete API documentation...
EOF

Structure longer reference files with table of contents:

# API Reference

## Contents

- Authentication and setup
- Core methods (create, read, update, delete)
- Advanced features
- Error handling patterns

## Authentication and setup

...

Keep references one level deep from skill.md. Avoid nested references.

Step 6: Validation

Install the validation tool (first time only):

pip install agentskills

Validate your skill:

skills-ref validate .github/skills/skill-name

Fix any validation errors before testing.

Step 7: Testing and Iteration

1. Test with trigger phrases: Ask Claude various questions that should activate the skill
2. Observe behavior: Does Claude load the skill? Follow instructions correctly?
3. Iterate based on usage: Refine instructions, add missing information, improve clarity
4. Get feedback: Ask team members to try the skill

Example test queries:

• Direct: "How do I use the [skill-name] skill?"
• Implicit: "[trigger phrase from description]"
• Edge cases: "[uncommon but valid trigger]"

skill.md Frontmatter Reference

Required Fields

name (required):

• Maximum 64 characters
• Lowercase letters, numbers, hyphens only
• No XML tags, no reserved words ("anthropic", "claude")

description (required):

• Non-empty, maximum 1024 characters
• Must be a plain single-line string — never use YAML block (|) or folded (>) scalars
• Include WHAT the skill does
• Include WHEN to use it
• List trigger phrases/keywords
• Use third person ("Processes Excel files" not "I can help you process")

Optional Fields

metadata (optional):

metadata:
  author: torrust
  version: "1.0"
  last-updated: "2026-02-06"

allowed-tools (optional):

allowed-tools: Read Bash(npx markdownlint-cli2:*) Bash(npx cspell:*)

compatibility (optional):

compatibility: Requires Node.js (for npx markdownlint-cli2 and npx cspell)

skill.md Body Patterns

Pattern 1: High-Level Guide with References

# PDF Processing

## Quick Start

Extract text with pdfplumber:

```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

Advanced Features

**Form filling**: See forms.md for complete guide
**API reference**: See reference.md for all methods
**Examples**: See examples.md for common patterns

Note: Example pattern - replace with your skill's actual reference files.

Pattern 2: Domain-Specific Organization

For skills with multiple domains, organize content by domain:

# BigQuery Data Analysis

## Available Datasets

**Finance**: Revenue, ARR → See finance.md
**Sales**: Pipeline, opportunities → See sales.md
**Product**: API usage, features → See product.md

Note: Hypothetical domain-specific example - adapt to your skill's needs.

Claude loads only the relevant domain's reference file.

Pattern 3: Conditional Details

# DOCX Processing

## Creating Documents

Use docx-js for new documents. See docx-js.md.

## Editing Documents

For simple edits, modify the XML directly.

**For tracked changes**: See redlining.md
**For OOXML details**: See ooxml.md

Note: Hypothetical example showing conditional progressive disclosure. Purpose: Executable code for deterministic operations

Examples:

• Validation scripts
• Code generators
• File processors

Guidelines:

• Make scripts solve problems, not punt to Claude
• Handle errors explicitly
• Document parameters

References Directory

Purpose: Detailed documentation loaded on-demand

Examples:

• API references
• Configuration schemas
• Domain-specific guides

Guidelines:

• Keep each file focused on one topic
• Use table of contents for files >100 lines
• Link clearly from skill.md

Assets Directory

Purpose: Files used in skill output

Examples:

• Templates
• Boilerplate code
• Configuration examples

Guidelines:

• Reference assets explicitly
• Keep files small and focused
• Version templates when needed

Validation and Integration

Validation with skills-ref

# Validate single skill
skills-ref validate .github/skills/skill-name

# Validate all skills
skills-ref validate .github/skills

Common validation errors:

Error	Fix
Invalid frontmatter YAML	Check YAML syntax, required fields
Name too long	Shorten to ≤64 characters
Invalid characters in name	Use only lowercase, numbers, hyphens
Empty description	Add comprehensive description
XML tags in metadata	Remove < and > characters

Testing with GitHub Copilot

1. Enable skills in VS Code: Settings → chat.useAgentSkills → enable
2. Reload VS Code: Command Palette → "Reload Window"
3. Test activation: Ask questions using trigger phrases from description
4. Verify behavior: Check that Claude follows skill instructions
5. Iterate: Refine based on observed behavior

Integrating with AGENTS.md

If the skill should be referenced from AGENTS.md for discoverability, add a note under a relevant section pointing to the skill path: .github/skills/skill-name/skill.md.

Examples and Patterns

For detailed examples, see:

• references/specification.md - Full Agent Skills spec
• references/patterns.md - Proven patterns and workflows
• references/examples.md - Example skills from this project

Quick Reference

Task	Command/Action
Create skill directory	mkdir -p .github/skills/skill-name/references
Validate skill	skills-ref validate .github/skills/skill-name
Test with Copilot	Enable chat.useAgentSkills in VS Code
Install validation tool	pip install agentskills

Tips

• Start simple: Begin with just skill.md, add resources as needed
• Test early: Validate and test before adding complex content
• Be specific in descriptions: Include all trigger phrases and use cases
• Use progressive disclosure: Keep skill.md focused, move details to references
• Iterate based on usage: Refine after observing how Claude uses the skill
• Learn from examples: Study skills in references/examples.md