Skill Package Format & Runtime Conventions

This reference defines the file structure, metadata schema, exclusion rules, initialization lifecycle, and runtime conventions for FastGPT Agent Skills.

1. Package Directory Layout

A standard FastGPT Skill project follows a unified workspace directory layout:

/
├── skills/                      # Skill collection directory (required)
│   ├── extract-emails/          # First skill directory
│   │   ├── SKILL.md             # Skill metadata and execution instructions (required)
│   │   └── extract.py           # Execution script
│   └── format-report/           # Second skill directory (optional)
│       ├── SKILL.md             # Corresponding metadata and instructions
│       └── render.py            # Execution script
├── entrypoint.sh                # Runtime initialization script (optional)
├── requirements.txt             # Python dependency manifest (optional)
├── package.json                 # Node.js dependency manifest (optional)
└── .gitignore                   # Packaging exclusion rules (recommended)

Core layout conventions:

• skills/ must reside at the project root; first-level subdirectories represent individual skill units.
• Every skill unit directory must contain a SKILL.md entry file.
• The project root may contain shared scripts, dependency manifests, and environment initialization files.

2. SKILL.md Metadata Format

The SKILL.md file in each skill directory declares metadata via YAML Frontmatter and provides runtime task guidelines in Markdown:

---
name: extract-emails
description: Extract all email addresses from text, deduplicate, and preserve original order.
---

# Email Extraction Skill

Identifies email addresses from text input, deduplicating them in first-seen order.

## Execution

Invoke via Python script:

```bash
python3 skills/extract-emails/extract.py "<input_text>"
```

Metadata schema definitions:

Body guidelines:

• Specific task objectives: Detail expected input formats, processing logic, and output values.
• Concrete execution commands: Include clear terminal commands (such as python3 ... or node ...) guiding the Agent to execute scripts in the sandbox.

3. Multiple Skills In One Resource

A single Skill resource supports organizing multiple related skills. Create multiple first-level subdirectories under skills/, each maintaining its own SKILL.md and supporting scripts.

When an Agent associates this Skill resource, it reads all declared skill descriptions and dynamically dispatches the appropriate skill unit matching user requests.

4. Packaging And Exclusion Rules

Publishing a version packages workspace files into a standard ZIP snapshot. The packaging process enforces the following exclusion and security rules:

System Default Exclusions

The system automatically applies the built-in DEFAULT_GITIGNORE_CONTENT list, excluding the following categories:

• Dependency directories: node_modules/, .npm/, .yarn/, .pnpm-store/, .venv/, venv/, env/
• Build and Python cache artifacts: dist/, build/, .next/, out/, .nuxt/, __pycache__/, *.pyc, .pytest_cache/, *.egg-info/, .eggs/
• Editor, OS, and binary archive files: .vscode/, .idea/, .DS_Store, package.zip, media/archive binaries, and *.log

Root .gitignore Merging

During packaging, exclusions declared in the project root .gitignore merge with the system default rules.

Credential, Git Metadata, and Custom Cache Exclusions

.env, .env.*, .git/, and .cache/ are outside DEFAULT_GITIGNORE_CONTENT. To keep local credentials, Git repository history, and custom cache directories out of distributed ZIP packages, declare them explicitly in the project root .gitignore:

.env
.env.*
.git/
.cache/
*.key
*.pem

Explicit exclusion keeps local credentials out of distributed packages.

5. Dependency Preparation And Initialization

Third-party dependencies are prepared automatically via entrypoint.sh in the project root.

Execution Lifecycle

When an application deploys an associated Skill, the sandbox executes entrypoint.sh during workspace initialization:

#!/bin/bash
set -e

if [ -f "requirements.txt" ]; then
  pip install --no-cache-dir -r requirements.txt
fi

versionId Deduplication

The sandbox tracks successfully initialized versionId records in ~/.fastgpt/runtime/state.json. Subsequent conversations reusing the sandbox instance skip script execution for previously completed versions, enabling rapid startup.

See the Initialization Script Guide for execution limits and fault-tolerance policies.

6. Runtime Conventions

Published Skills running in applications adhere to the following environment conventions:

• Deployment path: The skill package unpacks into ./projects/<versionId>/ inside the sandbox virtual machine.
• Runtime support: The sandbox provides Python 3 and Node.js runtimes with standard libraries.
• Output transmission: Standard output (stdout) from scripts returns to the Agent as tool execution observations.
• Version isolation: Live applications execute immutable published snapshots, keeping unreleased edits in the workspace isolated from production.

7. Related Guides

• Skill Development Tutorial
• Initialization Script
• Versions & Publishing
• Using Skills in Agents