SkillTk

SkillTk is a declarative AI build system for generating skill/project artifacts from a manifest.

This repository currently provides a single CLI entrypoint: skilltk.py.

Features

• Manifest-driven generation (MANIFEST.yaml or MANIFEST.json)
• Multi-file output with:
  • section-based documents
  • source-based files
• Multiple generation modes:
  • generate
  • preprocess (meta-prompt to final prompt conversion)
  • self
  • enrich
  • template
• Resource processing (copy, git-clone)
• Dependency retrieval into dependencies/
• Post-generation hooks
• JSON schema for manifest validation (manifests/MANIFEST.schema.json)

Requirements

• Python 3.10+
• OpenAI API key
• Dependencies:
  • openai
  • python-dotenv
  • pyyaml (optional, needed for YAML manifests)

Install:

pip install openai python-dotenv pyyaml

Environment

Create .env (or your configured dotenv path):

OPENAI_API_KEY=your_key_here

Installation

Install from the project directory:

pip install .

After install, the CLI is available as a system command:

skilltk --help

Optional (isolated CLI install with pipx):

pipx install .

CLI Usage

python3 skilltk.py <command> [options]

--help Output

Top-level help:

usage: skilltk.py [-h] {init,generate,preprocess} ...

positional arguments:
  {init,generate,preprocess}

options:
  -h, --help       show this help message and exit

init help:

usage: skilltk.py init [-h] [--yaml | --json]

options:
  -h, --help  show this help message and exit
  --yaml
  --json

generate help:

usage: skilltk.py generate [-h]

options:
  -h, --help  show this help message and exit

Commands

init

Create a starter manifest.

python3 skilltk.py init [--yaml | --json]

Options:

• --yaml create MANIFEST.yaml (default)
• --json create MANIFEST.json

Behavior:

• Fails if target manifest file already exists.

generate

Generate outputs from the manifest.

python3 skilltk.py generate

Behavior:

• Loads MANIFEST.yaml first, falls back to MANIFEST.json
• Writes files under config.output_dir
• Processes resources
• Runs post hooks (hooks.post-generate)

preprocess

Preprocesses manifest prompts in-place.

python3 skilltk.py preprocess

Behavior:

• Loads MANIFEST.yaml first, falls back to MANIFEST.json
• For every mode: preprocess, sends prompt (meta-prompt) to LLM
• Replaces prompt with generated final prompt
• Converts mode from preprocess to generate
• Backs up old manifest to _<manifest-name> and writes the new manifest

Manifest Overview

Top-level keys:

• $version (required)
• $schema (optional)
• metadata (required)
• config (required)
• generation (optional defaults)
• files (required)
• resources (optional)
• dependencies (optional)
• hooks (optional)
• agents (optional)

See full schema: manifests/MANIFEST.schema.json.

File Generation Model

Each entry in files must have:

• path
• either sections or source

Section file (sections)

Each section supports mode:

• self: emits content as-is
• generate: uses resolved prompt and model generation
• preprocess: same generation path as generate, intended for preprocess-driven prompts
• enrich: improves content via model
• template: substitutes {{var}} from variables

Source file (source)

Supports the same mode semantics as sections.

Dependencies

Dependencies are declarative external assets (libraries/apps/datasets) that can be retrieved before generation.

Each dependency object contains:

• id
• name
• type (library, application, dataset)
• description
• retrieval-script (shell script run inside that dependency's directory)

Runtime behavior:

• Dependencies are retrieved into output_dir/dependencies/<id>/.
• A summary file is emitted at output_dir/dependencies/DEPENDENCIES.md.
• If SKILL.md is generated, a ## Dependencies section is appended with all dependency entries.
• Prompts can reference dependencies with macros:
  • $dep(id) -> replaced with dependency id/name/type/description
  • $depfile(id, relative/path) -> inlines file contents from dependencies/<id>/relative/path
• Macro expansion is applied for normal generation prompts and preprocess/meta-prompts.

Preprocess Pipeline

Preprocess is prompt synthesis before final artifact generation.

Trigger

Use one of these patterns:

mode: preprocess
prompt: "Generate a detailed final prompt for ..."

or:

mode: generate
prompt: preprocess
preprocess:
  strategy: synthesize
  instructions: ...
  context: [...]

Runtime behavior

Two supported flows:

1. skilltk preprocess flow:
   • reads meta-prompts from items with mode: preprocess
   • generates final prompts
   • rewrites manifest (mode -> generate, prompt -> final prompt)
2. inline preprocess flow during skilltk generate:
   • when prompt: preprocess, resolve_prompt(...) calls run_preprocess(...)
   • generated prompt is used immediately for final generation

Generation Defaults and Overrides

generation values can appear at:

• top-level (generation) as defaults
• per-section/per-source (generation) as overrides
• per-preprocess (preprocess.generation) for prompt synthesis stage

Supported generation fields:

• model
• temperature
• top_p
• max_tokens
• seed (schema-level; may depend on provider support)
• cache (defaults-level)

Example Manifest (YAML)

$version: 1.0.0
$schema: https://example.com/schemas/skilltk.schema.json

metadata:
  name: demo-skill
  description: Demo with preprocess pipeline

config:
  provider: openai
  backend: https://api.openai.com/v1
  model: gpt-5.5
  output_dir: ./generated-skill
  dotenv: .env

generation:
  temperature: 0.3
  top_p: 1.0
  max_tokens: 3000

files:
  - path: SKILL.md
    sections:
      - id: overview
        title: Overview
        mode: generate
        prompt: preprocess
        preprocess:
          strategy: synthesize-structured-instructions
          instructions: |
            Create a precise prompt that asks for a production-grade skill overview.
            Keep it implementation-oriented and concise.
          context:
            - Target audience: developers
            - Output format: markdown
          generation:
            model: gpt-5.5
            temperature: 0.1

  - path: scripts/helper.py
    source:
      mode: self
      content: |
        print("hello from generated helper")

hooks:
  post-generate:
    - chmod +x scripts/*.py

Resources

Supported resource types:

• copy
  • from: local path
  • to: destination relative to output dir
• git-clone
  • repository
  • to (optional)
  • branch (optional)

Error Handling Notes

• Missing OPENAI_API_KEY -> generation fails.
• Missing manifest -> generation fails.
• Unknown mode/resource types -> generation fails.
• prompt: preprocess without preprocess block -> generation fails.

Validation Tips

Validate syntax quickly:

python3 -m py_compile skilltk.py

Optionally add your own JSON schema validation step using manifests/MANIFEST.schema.json.

Project Files

• skilltk.py - CLI/runtime implementation
• manifests/MANIFEST.schema.json - manifest schema
• AGENTS.md - architecture and agent guidance

Quick Start

python3 skilltk.py init --yaml
# edit MANIFEST.yaml
python3 skilltk.py generate