Skman

skman — Skill Package Manager

Overview

Generates spec-compliant, cross-platform agent skills from user requirements. Takes a project/tool name, version, and documentation sources (URLs or filesystem paths), then produces complete SKILL.md files that work on pi, opencode, Claude Code, and Codex.

Skills are Markdown-only by default — no scripts or assets unless the user explicitly requests them.

• Scripts — Bash or Python for deterministic tasks (validation, analysis, etc.). Executed by the agent, not loaded into context. Only output consumes tokens.
• Assets — Supporting files (docs, schemas, diagrams). Not executed; supplementary material the agent reads when needed.

When to Use

• Creating a new agent skill for a project, library, or tool
• Converting existing documentation into skill format
• Generating skills from URLs or local codebases
• Updating an existing skill for a new upstream version
• Any task producing .agents/skills/<name>/SKILL.md files

Generation Workflow

Follow these steps in order. All paths relative to the skill directory (where SKILL.md lives).

Step 1: Detect Mode and Validate Input

New vs update:

• New — No existing directory matches the name. Proceed with full generation.
• Update — Existing skill found (e.g., curl-8-19-0 → curl-8-20-0). Read existing SKILL.md, crawl new sources, diff against old content, preserve working sections, update only changed parts. Create a new versioned directory — never overwrite the old one.

Conflict detection — Before creating, check .agents/skills/ for:

• Exact name match → warn user, ask if they meant to update
• Overlapping name without version → suggest versioned naming
• Near-duplicate coverage → note overlap in description

Name validation — Must match ^[a-z0-9]+(-[a-z0-9]+)*$. Include upstream version hyphenated (e.g., curl-8-20-0, fastapi-0-115). If no version, use just the name (e.g., git).

Valid: pdf-processing, data-analysis  |  Invalid: PDF-Processing, -pdf, pdf--processing

Step 2: Crawl and Collect Content

Gather all source material from the provided URLs and filesystem paths.

URL crawling — Recursively follow links within the same domain and subdomains.

Filesystem crawling — Recursively visit files and directories.

Readable extensions:

Skip:

• Binary files (.png, .jpg, .zip, .tar, .gz, .whl, .pyc, .so, .dll, .exe)
• Hidden files/directories (. prefix) unless explicitly requested
• Environment files (.env, .env*) unless explicitly requested
• Version control (.git/, .svn/, .hg/) always
• Do not skip by size — large files may be complex text documents

Step 3: Determine Structure and Write Output

Choose structure:

If content has 2+ distinct subtopics AND agent only needs 1-2 per task → complex (SKILL.md + reference/)
If single cohesive topic OR under 300 lines                                    → simple (SKILL.md only)

• Simple: All content in a single SKILL.md.
• Complex: SKILL.md as overview + navigation hub, reference/ with flat numbered files (01-*.md, 02-*.md).
• Scripts/assets: Only if explicitly requested by the user.

Write YAML header (exactly two fields):

---
name: <skill-name>
description: <1-1024 chars, third person, includes WHAT and WHEN>
---

• name — Max 64 chars. Must match directory name. Regex ^[a-z0-9]+(-[a-z0-9]+)*$.
• description — Formula: [WHAT it does] + [key capabilities] + Use when [specific scenarios]. Aim for 150–400 characters. Third person only. Never "I can help" or "you can use".

Write SKILL.md body — Required sections: ## Overview, ## When to Use, ## Core Concepts. Optional sections (include only when applicable): ## Installation / Setup, ## Usage Examples, ## Advanced Topics (only if reference/ exists). See Templates for full templates.

Write reference files (if complex) — Flat reference/ directory, NN-*.md naming. Each file: heading, table of contents (if over 100 lines), content. Keep individual reference files under 200 lines — split if longer. All reference files must be linked from SKILL.md. Never chain references (reference → reference).

Write scripts (if requested) — See Script Rules below.

Step 4: Validate

Run structural validator:

python3 -B scripts/skman.py validate [--strict] <SKILL_DIR>

Checks YAML header, directory layout, file naming, section presence, and script references. Use --strict to promote warnings to errors.

LLM judgment checks (the script cannot verify these):

• Content accuracy — no hallucinated content, all from crawled sources
• Conciseness — no over-explaining basics the target agent already knows
• Single recommended approach — not multiple options confusing the agent
• Consistent terminology — one term per concept throughout
• Code example quality — correct, copy-pasteable, relevant
• Script clarity — execution intent explicit ("Run" vs "See for reference"), errors handled

Step 5: Report and Update Index

Report success with file tree and validation results.

Regenerate the skills table (after every skill addition, deletion, rename, update, or YAML header edit):

python3 -B scripts/skman.py gen-table [SKILLS_DIR] [README_PATH]

Both arguments optional. Defaults: .agents/skills and README.md.

Rules

Apply these throughout the workflow.

YAML Header

• File starts with --- on line 1, ends header with second ---.

• Exactly two fields: name and description.

• name: max 64 chars, regex ^[a-z0-9]+(-[a-z0-9]+)*$.

• description: 1–1024 chars, third person.

Description Formula

[WHAT it does] + [key capabilities, comma-separated] + Use when [specific scenarios].

• WHAT: Action verb + domain
• WHEN: Specific trigger scenarios for skill selection
• Key terms: Include distinctive keywords from the project/tool name and primary use cases
• Target 150–400 characters. Under 100 = too vague, over 600 = token waste.

Directory and Version

• Directory: <skill-name> or <skill-name>-<version> (e.g., git, plan, curl-8-20-0, project-2025-11-25).

Script Quality

• Handle errors explicitly — never punt to the agent with bare exceptions.
• Document all constants with justification.
• Clear, specific error messages that help the agent fix issues.
• Execution intent explicit: "Run script.py" (preferred) vs "See script.py for reference".
• Prefer execution over reading — deterministic scripts are more reliable than agent-generated equivalents.
• Python: python3 -B script.py, built-in modules only unless user requests otherwise. For third-party: uv run python -B script.py.
• Naming: Default script shares skill base name (e.g., curl for curl-8-20-0). Additional scripts use descriptive names.
• Help system: Every script supports --help. Subcommands support independent --help (e.g., script subcmd --help).

Anti-Patterns to Avoid

• Backslash paths — Always forward slashes (reference/guide.md, not reference\guide.md).
• Too many options — Single recommended approach in SKILL.md. Alternatives go in reference files.
• Time-sensitive info — Don't write "latest version is 3.2". Use labeled "old patterns" section for legacy.
• Over-explaining basics — Target agent knows what HTTP, databases, etc. are. Challenge each paragraph: "Does this justify its token cost?"
• Inconsistent terminology — One term per concept throughout (always "API endpoint", not sometimes "URL" or "route").

Cross-Model Compatibility

Generated skills must work on both small and large LLMs:

• SKILL.md should be scannable in 30 seconds — every paragraph contains at least one actionable instruction or concrete example.
• Reference files under 200 lines each — split if longer.
• One level of references only — all link directly from SKILL.md, never reference → reference.
• Progressive disclosure — SKILL.md gives quick-start + links to details. Agent loads references only when needed.
• No chained navigation — an agent reading SKILL.md should find everything it needs or clear paths to exactly 1–2 reference files.

Commands

sync — Sync local .agents/skills with tangled-skills

python3 -B scripts/skman.py sync [TARGET_DIR]

Fetches the main branch of tangled-skills from GitHub, extracts .agents/skills/ into TARGET_DIR/.agents/skills/, overwriting existing skills with upstream versions. Default target: current directory.

Dependencies: bash, curl, tar

Advanced Topics

Evaluation-Driven Development: Build evaluations before writing skill content, iterate based on real agent behavior → Evaluation-Driven Development

Degrees of Freedom: Match instruction specificity to task fragility — high, medium, or low freedom → Degrees of Freedom

Templates: Full copy-paste templates for SKILL.md and reference files → Templates