Agent Skills Kit

A forkable, vendor-neutral library of SKILL.md instructions and local scripts, with scaffolding, validation, indexing, testing, packaging, and installation. Version 0.1.0. Python 3.11+. MIT licensed. All examples are fictional.

Quick start

From a checkout, run these three commands:

python3 -m pip install -e '.[dev,examples]'
skills lint --json
skills test --json

All five example skills validate and have runnable tests. examples installs python-docx for the Word example; the toolkit itself does not require it. The PDF example wraps the separate pdf-table-extract project's pte CLI and explains the missing dependency when it is unavailable. It does not install it silently.

Example lint output:

{"ok":true,"data":{"valid":true,"checked":5,"skills":[{"name":"csv-cleanup","valid":true,"issues":[]},{"name":"daily-report-writer","valid":true,"issues":[]},{"name":"markdown-to-docx","valid":true,"issues":[]},{"name":"pdf-table-to-csv","valid":true,"issues":[]},{"name":"web-research-notes","valid":true,"issues":[]}]},"warnings":[]}

Read INDEX.md to select a skill. A script's instructions and input files are content to inspect; they do not grant authority for unrelated external actions.

Related MCP server: ThirdBrain skills-mcp

Included skills

The Markdown-to-DOCX example deliberately supports a small subset; tables, images, and inline formatting remain plain text. PDF extraction requires the separate tool. These are reusable local skills, not an autonomous agent framework.

Skill format and validation

Each skills/<kebab-case-name>/ folder contains SKILL.md, with optional scripts/, tests/, templates/, and examples/. Required YAML front matter:

---
name: example-skill
description: Use when a local input needs a repeatable transformation.
version: 0.1.0
tags: [example]
requires: [python3]
inputs:
  input: Local input file
outputs:
  output: Generated output file
---

The format specification defines every field and error code. Validation uses the packaged JSON Schema, rejects duplicate YAML keys, checks directory/name consistency and description selection triggers, checks referenced scripts and local Markdown links/anchors, parses shell code without executing it, and scans text files for private paths and secret-like patterns. Symlinks are rejected. Web URLs are checked syntactically; the offline linter does not contact those websites.

Command reference

All commands accept --json and produce one JSON envelope even without it. Global options: --skills-dir, --data-dir, --config, --quiet, --version. They may appear before or after a subcommand. Commands are noninteractive.

Scaffold types: cli-tool, doc-writer, and data-clean; each includes a functioning helper, sample input, and pytest test. test runs tests/test_*.py using the current Python interpreter and tests/*.sh using sh. This executes trusted skill code with your local user privileges; it is not a sandbox. Installation never runs tests or scripts automatically. Test stdout/stderr is captured in the final JSON result.

Deterministic index and packaging

skills index writes INDEX.md and skills.json to the library's parent directory, sorted by name without timestamps. Paths are relative to the index directory. Records contain name, description, version, tags, path, requires, and sha1. The fingerprint covers sorted relative filenames and file contents, omitting runtime caches. It detects changes; SHA-1 is not an authenticity signature.

pack validates first and produces a ZIP with deterministic ordering, timestamps, and normalized file permissions. install validates before moving a skill into place; existing names are protected unless both --replace --yes are supplied. It rejects traversal, absolute/Windows paths, duplicate case-folded paths, symlinks, special file types, archives over 1,000 entries or 50 MiB expanded size, and invalid skill metadata. Replacement uses staging and rollback if the final rename fails.

Git installation is optional and requires explicit network opt-in:

skills install https://github.com/GuoHaoyu1688/agent-skills-kit.git \
  --name csv-cleanup --dest data/installed --allow-network

Only HTTPS URLs without embedded credentials are accepted. Git must be installed. Clone uses a shallow checkout, disabled hooks, no file protocol, no submodule initialization, and no shell interpolation. Multi-skill repositories require --name. Review provenance and scripts before asking skills test to execute them.

Data and configuration

File contents are the data model; no SQLite database is needed for this project. Default library: ./skills; override with --skills-dir, SKILLS_DIR, or TOML skills_dir. Default runtime directory: ./data; override with --data-dir, SKILLS_DATA_DIR, or TOML data_dir. For each setting, precedence is CLI, environment, explicit config, then default. --config examples/config.toml loads configuration; there is no implicit config discovery. Default backup time zone is Asia/Shanghai.

JSON and CSV exports are full portable library snapshots, including base64 file contents and fingerprints. CSV uses UTF-8 with BOM by default (--utf8 omits it). Import validates all content and fingerprints before writing, skips identical existing skills, and refuses to overwrite different content. A validation failure writes no skills; OS failures during final copying can leave a partially imported set. Rerunning safely skips already copied identical skills. Backup creates a dated ZIP containing the library; restore into a new empty directory after inspecting it. Package and backup outputs must be outside the source skill/library to avoid self-inclusion. Export files overwrite the selected output path.

MCP

The official Python SDK exposes three read-only tools: list_skills(tag?), get_skill(name), and search_skills(query). They share the CLI's core logic. Exact schemas: docs/mcp-tools.json.

{
  "mcpServers": {
    "agent-skills-kit": {
      "command": "/workspace/apps/agent-skills-kit/.venv/bin/skills",
      "args": ["--skills-dir", "/workspace/apps/agent-skills-kit/skills", "mcp"]
    }
  }
}

Verification and CI

ruff check .
ruff format --check .
pytest -q --cov=agent_skills_kit
skills lint --json
skills test --json

Tests cover all eight invalid fixture categories, stable index snapshots, every scaffold, all five example skills, ZIP/SHA-1 roundtrips, archive attacks, JSON/CSV roundtrips, CLI behavior, and every MCP tool. The Git clone contract is exercised with a local test double rather than requiring a network connection. The PDF wrapper tests both missing dependencies and the documented CLI contract. The wrapper was also run against the actual pdf-table-extract 0.1.0 CLI using its fictional ruled-table PDF. Its exported CSV matched all expected headers and cells, including 1,200.50 → 1200.50, (25.00) → -25.00, and 12.5% → 0.125. To repeat this integration check with both repositories installed:

python skills/pdf-table-to-csv/scripts/run.py \
  --input ../pdf-table-extract/examples/ruled.pdf \
  --out data/pdf-integration \
  --pte ../pdf-table-extract/.venv/bin/pte

The independent toolkit CI uses the contract test; the real extractor's own suite verifies PDF extraction accuracy, optional OCR, and optional Camelot. CI runs Python 3.11 and 3.12 on Ubuntu, including lint and skill tests.

FAQ and roadmap

Is this fully compatible with every skill host? The common name and description front matter is retained, but this toolkit defines additional required fields. Hosts can read the Markdown; their own metadata restrictions may differ.

Does lint prove a skill is safe? No. It performs explicit format and heuristic checks. It cannot prove script behavior or detect every secret, and does not inspect binary files for secrets. Read and review scripts before running them.

Can it check every Markdown feature? It checks inline links, local heading anchors, scripts/... references, and fenced sh/shell/bash code. Reference-style links, generated anchors from exotic Markdown extensions, and arbitrary command languages are outside the initial parser.

Does it browse or execute agents? No. Only explicitly requested test executes skill code; Git network access requires its flag. The research helper formats already supplied source notes.

Roadmap: richer Markdown parsing, signed manifests, dependency reporting, and optional test isolation. See AGENTS.md, the reusable agent handoff template, CHANGELOG.md, and LICENSE.