An opinionated approach to the www.agentskills.io standard.

Repo structure

The npx skills installer scans for SKILL.md files. This repo intentionally uses:

• skills/<skill-folder>/SKILL.md

This allows npx skills add <repo> --list discovers a collection of skills.

The repo accepts these skill layouts, aligned with Agent Skills specification:

• Behaviour guidance: a single SKILL.md at or under 100 lines for rules or tool-use guidance.
• Simple task inline: a single SKILL.md at or under 500 lines for self-contained task procedures.
• Simple task runbook index: a compact SKILL.md at or under 500 lines with references/*.md runbooks that are optional to load at runtime.
• Multi-step workflow: the repo's multi-file pattern for longer workflows with ordered steps and checkpoints.

If starting fresh, use create-skill. If importing an existing skill that is over 500 lines or needs ordered checkpoints at any length, convert it to the multi-step workflow route by referencing create-skill with the following request to an agent:

Refactor <skill-in-question> to align with the create-skill multi-step workflow route, retaining all content with granular detail moving to reference files

Install

By default, npx skills add installs into the current project's .agents/ directory. Use -g to install these skills at user level instead.

# List skills from this repo
npx skills add <repo-url> --list

# Install interactively at user level
npx skills add <repo-url> -g

# Install one skill only at user level
npx skills add <repo-url> --skill create-skill -g

# Install all skills to all agents at user level without prompts
npx skills add <repo-url> --all -g

Quality gates

Install the Git hooks before your first commit:

pre-commit install
pre-commit install --hook-type commit-msg

This repo uses a centralized pre-commit and CI runner at scripts/run-ci-quality-gates.sh. That runner executes a custom shell-based linter for this repository's opinionated skill structure and enforces parity between local hooks and the GitHub Actions quality gate workflow.