Skman

skman

Tools and guidelines for creating, validating, and managing agent skills. Use skman.sh to scaffold new skill directories, check format compliance, inspect structure, and regenerate the repository README.

Overview

skman is a skill for scaffolding, validating, and inspecting agent skills (SKILL.md files). It provides four functionalities:

• create — Scaffold a new skill directory with SKILL.md, optional scripts, and references
• validate — Check a skill against the format specification (frontmatter, naming, structure)
• info — Inspect frontmatter, body stats, and heading hierarchy
• generate — Regenerate the repository README.md with skills table and statistics

Usage

# Scaffold a new skill
skman.sh create <name> "<description>"

# Create with version (dir: demo-skill-2-4-1/, H1: # demo-skill 2.4.1)
skman.sh create demo-skill "Dummy example skill" --version 2.4.1

# Create with scripts and references
skman.sh create my-skill "Desc" --with-scripts --with-references

# Validate a skill
skman.sh validate ./my-skill
skman.sh validate --strict ./my-skill

# Inspect frontmatter and structure
skman.sh info ./my-skill

# Regenerate README.md Skills Table and Statistics
skman.sh generate

# Help at every level
skman.sh --help
skman.sh create --help
skman.sh validate --help
skman.sh info --help
skman.sh generate --help

Scaffold New Skill

# Into default location (.agents/skills/my-skill/)
skman.sh create my-skill "Extracts text from PDF files"

# With version (dir: demo-skill-2-4-1/, H1: # demo-skill 2.4.1)
skman.sh create demo-skill "Dummy example skill" --version 2.4.1

# With scripts and references
skman.sh create my-skill "Desc" --with-scripts --with-references

# Into a specific parent directory
skman.sh create my-skill "Desc" -o ./custom-skills

The script validates name and description before creating files.

Validate

Run the built-in validator:

skman.sh validate ./my-skill
skman.sh validate --strict ./my-skill

Skill Format

A skill is a directory containing a SKILL.md file. Everything else is optional.

Directory Layout

<skill-name>/
├── SKILL.md              # Required: frontmatter + instructions
├── scripts/              # Optional: helper scripts (executed, not loaded into context)
│   ├── <skill-name>.sh   # Bash wrapper — the entry point referenced in SKILL.md
│   └── _<skill-name>.py  # Python implementation (underscore prefix, not called directly)

> Use `skman.sh create --with-scripts` to scaffold these.
├── references/           # Optional: detailed docs loaded on demand (numbered prefix)
│   └── 01-topic.md
│   └── 02-abc.md
│   └── 03-xyz.md
└── assets/               # Optional: templates, configs, etc.

Frontmatter Fields

Frontmatter Template

---
name: my-skill
description: What this skill does and when to use it. Be specific.
metadata:
  tags:
    - meta
---

Creating a New Skill

Follow these steps in order:

1. Choose a name — lowercase, hyphens, numbers only (e.g., pdf-processing, git-8-20-0). No leading/trailing/consecutive hyphens.

2. Write the frontmatter — exactly name and description at minimum. The name must match the directory name exactly (e.g., name: demo-skill-2-4-1 for demo-skill-2-4-1/). The description determines when the agent loads this skill; make it specific with trigger terms.

3. Write the body — concise instructions, under 500 lines. Must start with a level-1 heading matching # <name> or # <name> <version>. Structure:

   • # <name> (e.g., # skman) or # <name> <version> (e.g., # demo-skill 2.4.1)
   • ## Overview — what it does
   • ## Usage — Optional: how to use it with examples
   • ## Gotchas — Optional: The most useful part of teaching a skill is listing its hidden traps. Instead of vague advice, provide specific rules that stop the agent from making predictable, common-sense mistakes in that specific environment.
   • ## References — Optional: Provides on-demand reference material for agents. Always use a bulleted list, never a table:

     ## References
     
     - [01-core-expressions](references/01-core-expressions.md) — Symbols, expressions, numbers
     - [02-algebra-polynomials](references/02-algebra-polynomials.md) — Polynomial rings, factoring
     

     Each line: link to the file followed by a dash and a brief topic summary.

4. Create a main script (if automation is needed) — write the implementation as scripts/_<skill-name>.py (underscore prefix) and a thin bash wrapper scripts/<skill-name>.sh that passes all arguments through. Scripts are executed (not loaded into context). The SKILL.md references only the .sh file. Include --help at every level. Default: python3 3.10+ with built-in modules only (see Scripting Defaults below). On explicit user request, any programming language and libraries/frameworks are allowed. Scaffold with --with-scripts.

5. Validate — run the validation script:

   skman.sh validate <path-to-skill>
   

Manual Creation

When writing files directly, ensure:

• Directory is named after the skill (e.g., skman) or <skill-name>-<version> (e.g., demo-skill-2-4-1)
• Frontmatter name must match the directory name exactly (e.g., name: demo-skill-2-4-1 for demo-skill-2-4-1/, or name: skman for skman/)
• SKILL.md exists at the directory root
• Body starts with # <name> or # <name> <version> matching the directory (e.g., # demo-skill 2.4.1 for demo-skill-2-4-1/)

Editing a Skill

Common operations:

• Update description — edit the frontmatter; this is what agents see in the system prompt
• Split long content — move sections >100 lines into references/NN-topic.md, link from SKILL.md
• Add a script — place in scripts/ with the skill's name as base name
• Restructure references — keep references one level deep; all should link directly from SKILL.md

Validation

Checks performed:

• Frontmatter presence and required fields
• Name format (case, characters, length, hyphen rules)
• Description presence, length, and absence of XML/HTML tags
• metadata structure (warns if present but not a mapping; warns if tags is not a string array)
• Body starts with a level-1 heading
• Body line count warning (>500 lines)
• Name vs directory basename consistency (warns on mismatch)
• H1 heading format (# <name> or # <name> <version> — errors on mismatch)
• Recommended section presence (## Overview — warns if missing)
• Truly optional sections (## Usage, ## Gotchas, ## References — no warning when absent)
• Script executability (<name>.sh must be chmod +x — warns if not)
• Script usage references (./<name>.sh → <name>.sh — warns if the body uses ./<name>.sh outside fenced code blocks)

Best Practices

Conciseness

• Context window is shared — every token competes with conversation history
• Default assumption: the model already knows basics (what PDFs are, how libraries work)
• Challenge each paragraph: "Does this justify its token cost?"

Scripting Defaults

• Default: python3 3.10+ with built-in modules only. Allowed stdlib modules include: os, sys, re, math, time, datetime, pathlib, argparse, asyncio, subprocess, urllib, hashlib, json, csv, io, collections, itertools, functools, textwrap, shutil, glob, tempfile, logging, struct, socket, ssl, email, html, xml.etree, and other standard library modules. No third-party packages (no pip install, no requests, no pyyaml, etc.) unless explicitly requested.
• Explicit override: any technology allowed. When the user explicitly requests a specific language, framework, or library — or asks for something that requires external dependencies — use whatever fits. Users have full freedom to write tools for any scenario. The default only applies when no preference is stated.

Match Specificity to Task Fragility

• High freedom (text instructions): multiple valid approaches, context-dependent decisions
• Medium freedom (pseudocode/scripts with parameters): preferred pattern exists, some variation OK
• Low freedom (exact commands): fragile operations, consistency is critical

Description Writing

• Always third person ("Processes Excel files" not "I can help you")
• Include both what the skill does and when to use it
• Include key terms that trigger discovery (file extensions, tool names, task types)
• Combat under-triggering — models tend to under-use skills. Make the description slightly "pushy" by explicitly naming trigger phrases and adjacent contexts the user might say, even if they don't name the skill directly. Example:

  # Weak
  How to build a simple fast dashboard to display internal data.
  
  # Pushy
  How to build a simple fast dashboard to display internal data. Use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a "dashboard."
  

Writing Style

• Use imperative voice — "Run this command" not "You should run this command"
• Explain the why, avoid rigid MUST/ALWAYS/NEVER in caps — modern models respond better to reasoning than rigid commands. If something is critical, explain why it matters

Progressive Disclosure

Skills use a four-level loading system:

1. Metadata (name + description) — always in context (~100 words). This is what determines whether the skill triggers.
2. SKILL.md body — loaded when skill triggers (<500 lines ideal). Contains the core instructions.
3. Scripts — executed (not loaded into context). Run via <name>.sh.
4. References — loaded as needed (unlimited). Reference files load on demand.

Guidelines:

• Keep SKILL.md body under 500 lines
• Move detailed content to references/ files linked from SKILL.md
• Avoid deeply nested references — all reference files should link directly from SKILL.md
• Include a table of contents in reference files longer than 100 lines
• Reference file naming — use numeric prefixes (01-, 02-, 03-, …) for deterministic ordering and easy insertion. Files should be named NN-topic.md where NN is an incrementing number starting from 01
• Multi-domain skills — when a skill supports multiple variants (frameworks, platforms), organize by domain in references:

  cloud-deploy/
  ├── SKILL.md              # workflow + variant selection logic
  └── references/
      ├── 00-aws.md
      ├── 01-gcp.md
      └── 02-azure.md
  

Model Compatibility

• SLMs (small models): need more explicit guidance, numbered steps, less ambiguity
• LLMs (large models): prefer concise instructions, avoid over-explaining
• Aim for instructions that work across both: clear structure, explicit rules, no fluff

Gotchas

• Scaffolded .sh files may lose execute permission — skman.sh create --with-scripts sets chmod 0o755, but editors or git checkouts can strip it. Always verify with ls -l <name>.sh; the validator warns if the bit is missing.
• --strict turns section warnings into errors — only ## Overview produces a warning when missing. ## Usage, ## Gotchas, and ## References are truly optional and never warn (knowledge-only skills often have no Usage section). In strict mode, any warning fails validation.
• Frontmatter name must match the directory basename exactly — e.g., demo-skill-2-4-1/ requires name: demo-skill-2-4-1, skman/ requires name: skman. The validator warns on mismatch. Fix by renaming the directory or correcting the frontmatter.
• H1 heading must match # <name> or # <base> <version> — the validator errors if the first heading doesn't match. For skman/ it must be # skman; for demo-skill-2-4-1/ it must be # demo-skill 2.4.1 (version uses dots, not hyphens). The version in the H1 must correspond to the hyphenated version suffix in the directory/frontmatter name.
• Reference files are loaded on demand, not into context — keep SKILL.md self-contained for core instructions; move deep-dive content to references/NN-topic.md and link from the body.