# 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:

```sh
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:

```json
{"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](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.

## Included skills

| Skill | Working behavior |
| --- | --- |
| [csv-cleanup](skills/csv-cleanup/SKILL.md) | Trim cells, reject malformed row widths, remove empty rows, and deduplicate while preserving order. |
| [daily-report-writer](skills/daily-report-writer/SKILL.md) | Produce a dated Markdown report from explicit task states and evidence paths. |
| [markdown-to-docx](skills/markdown-to-docx/SKILL.md) | Convert headings, paragraphs, lists, and code blocks into a real DOCX. |
| [pdf-table-to-csv](skills/pdf-table-to-csv/SKILL.md) | Invoke `pte extract PDF --out DIR --format csv --json`, preserving argument boundaries. |
| [web-research-notes](skills/web-research-notes/SKILL.md) | Organize supplied source notes and uncertainties with attribution; no fetching or claimed live verification. |

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:

```yaml
---
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](docs/spec.md) defines every field and error code.
Validation uses the packaged [JSON Schema](src/agent_skills_kit/core/schema.json),
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.

| Command | Example |
| --- | --- |
| `new` | `skills new table-helper --template data-clean` |
| `lint` | `skills lint`; `skills lint csv-cleanup` |
| `index` | `skills index`; `skills index --out output/catalog` |
| `test` | `skills test`; `skills test csv-cleanup --timeout 60` |
| `pack` | `skills pack csv-cleanup --out data/csv-cleanup.zip` |
| `install` | `skills install data/csv-cleanup.zip --dest data/installed` |
| `list` | `skills list --tag data --json` |
| `show` | `skills show csv-cleanup --json` |
| `search` | `skills search "csv local" --json` |
| `export` | `skills export --format json --out data/library.json` |
| `import` | `skills import data/library.json --skills-dir data/restored` |
| `backup` | `skills backup --out data/backups` |
| `mcp` | `skills mcp` |

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:

```sh
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](docs/mcp-tools.json).

```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

```sh
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:

```sh
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](AGENTS.md), the reusable
[agent handoff template](templates/AGENTS.md), [CHANGELOG.md](CHANGELOG.md), and [LICENSE](LICENSE).