home / skills / numman-ali / openskills / my-first-skill

my-first-skill skill

safe

This skill demonstrates how to structure procedural guidance for AI agents using progressive disclosure in SKILL.md format.

npx playbooks add skill numman-ali/openskills --skill my-first-skill

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.5 KB

---
name: my-first-skill
description: Example skill demonstrating Anthropic SKILL.md format. Load when learning to create skills or testing the OpenSkills loader.
---

# My First Skill

This is an example skill demonstrating the Anthropic SKILL.md format.

## Purpose

This skill shows how to structure procedural guidance for AI coding agents using progressive disclosure.

## When to Use

Load this skill when:
- Learning how skills work
- Testing the OpenSkills loader
- Understanding the SKILL.md format

## Instructions

To create a skill:

1. Create a directory: `mkdir my-skill/`
2. Add SKILL.md with YAML frontmatter:
   ```yaml
   ---
   name: my-skill
   description: When to use this skill
   ---
   ```
3. Write instructions in imperative form (not second person)
4. Reference bundled resources as needed

## Bundled Resources

For detailed information about the SKILL.md specification:

See `references/skill-format.md`

## Best Practices

- Write in imperative/infinitive form: "To do X, execute Y"
- NOT second person: avoid "You should..."
- Keep SKILL.md under 5,000 words
- Move detailed content to references/
- Use scripts/ for executable code
- Use assets/ for templates and output files

## Resource Resolution

When this skill is loaded, the base directory is provided:

```
Base directory: /path/to/my-first-skill
```

Relative paths resolve from base directory:
- `references/skill-format.md` → `/path/to/my-first-skill/references/skill-format.md`
- `scripts/helper.sh` → `/path/to/my-first-skill/scripts/helper.sh`

Overview

This skill is an introductory example that demonstrates how to structure a procedural guidance package for AI coding agents. It serves as a minimal, practical template to learn skill authoring and to validate a universal skills loader. The focus is on progressive disclosure and clear resource resolution.

How this skill works

The skill provides a base directory layout and shows how relative paths resolve to bundled resources. It includes concise procedural instructions for creating a new skill directory, adding metadata, and organizing supporting files. Load the skill to inspect examples of instructions, references, scripts, and assets.

When to use it

Learning how to author a skill for AI coding agents
Testing or validating a universal skills loader implementation
Understanding the expected skill file format and structure
Teaching progressive disclosure and concise procedural writing

Best practices

Write instructions in imperative/infinitive form: 'To do X, execute Y'
Avoid second-person phrasing such as 'you should...'
Keep primary guidance concise (recommendation: under 5,000 words)
Move detailed or large content into a references directory
Place executable helpers in a scripts directory and templates in an assets directory

Example use cases

Onboarding new contributors to author consistent skills
Verifying that a loader correctly resolves relative paths to bundled resources
Using as a checklist for structuring metadata and support files
Demonstrating how to separate concise guidance from in-depth references

FAQ

How are relative paths resolved when the skill is loaded?

The loader provides a base directory for the skill; relative paths in the skill resolve from that base to the referenced files.

Where should long-form or detailed content live?

Place detailed documentation in a references directory and keep the main guidance concise to improve readability and loading performance.