skill-creation

name	Skill Creation
description	Create, structure, and publish skills through the skill-plugin-marketplace pipeline

Skill Creation

You create, structure, and publish skills for the systemprompt.io platform. Skills are the atomic units of knowledge that agents use to perform tasks. Every skill lives in services/skills/ and flows through a pipeline to reach agents and the marketplace.

The Skill-Plugin-Marketplace Pipeline

services/skills/{skill_id}/        <- 1. AUTHOR HERE (source of truth)
├── config.yaml                       Metadata: id, name, description, tags
└── index.md                          Content: frontmatter + markdown body

        ↓ referenced by

services/plugins/{plugin-id}/      <- 2. PLUGIN BUNDLES SKILLS
├── config.yaml                       Lists skill IDs in skills.include
└── .claude-plugin/plugin.json        Claude Code plugin metadata

        ↓ exported via `systemprompt core plugins generate`

Plugin output bundle               <- 3. EXPORTED AS SKILL.md
└── skills/{kebab-name}/SKILL.md      Rebuilt: frontmatter (name + description) + body

        ↓ imported by marketplace users

Marketplace / User environment     <- 4. CONSUMED BY AGENTS
├── config.yaml (recreated)           Parsed from frontmatter
└── index.md (recreated)              Parsed from body

Key principle: The skill itself always lives in services/skills/{skill_id}/. Plugins reference skill IDs -- they do not contain skill content. When a plugin is exported, skills are bundled into SKILL.md files. When imported, they are unpacked back into config.yaml + index.md.

Skill Directory Structure

Every skill is a directory under services/skills/ with exactly two files:

services/skills/{skill_id}/
├── config.yaml          <- System metadata (id, name, enabled, tags, assigned_agents)
└── index.md             <- Skill content (frontmatter + markdown instructions)

Optional subdirectories for complex skills:

services/skills/{skill_id}/
├── config.yaml
├── index.md
├── references/          <- Reference data (CSV, JSON, templates)
├── templates/           <- Output templates
└── examples/            <- Example inputs/outputs

Creating a Skill

Step 1: Create the directory and config

# CLI method (interactive)
systemprompt core skills create --name my_skill --display-name "My Skill" --description "What this skill does" --tags "tag1,tag2"

# Or create manually:
mkdir -p services/skills/my_skill

config.yaml format:

id: my_skill
name: "My Skill"
description: "What this skill does in one sentence"
enabled: true
version: "1.0.0"
file: "index.md"
assigned_agents:
  - agent_name
tags:
  - tag1
  - tag2

Field	Required	Description
id	Yes	Unique identifier, snake_case, must match directory name
name	Yes	Human-readable display name
description	Yes	One-sentence description
enabled	Yes	Whether skill is active
version	Yes	Semantic version
file	Yes	Always "index.md"
assigned_agents	No	List of agent names that use this skill
tags	No	Search/categorization tags

Step 2: Write the index.md

The index.md must start with YAML frontmatter between --- markers:

---
name: "My Skill"
description: "What this skill does in one sentence"
---

# My Skill

Instructions for the agent go here...

Frontmatter fields (parsed by the export/import pipeline):

Field	Required	Description
name	Yes	Skill name (used during marketplace import)
description	Yes	Skill description (used during marketplace import)

The name and description in frontmatter must match the values in config.yaml. During plugin export, the system strips existing frontmatter from index.md and rebuilds it using values from config.yaml, so config.yaml is the source of truth for metadata. The frontmatter in index.md exists so that standalone SKILL.md files (after export) are self-describing.

Body content (after the closing ---) is the full skill instruction set in markdown. Write it as if speaking directly to the agent: "You do X. Use Y command. Follow Z workflow."

Step 3: Register the skill

Add the skill to services/skills/config.yaml:

includes:
  - my_skill/config.yaml

Step 4: Assign to a plugin

Add the skill ID to a plugin's config.yaml:

# services/plugins/{plugin-id}/config.yaml
plugin:
  skills:
    source: explicit
    include:
      - my_skill          # Add here

Step 5: Sync and validate

# Sync skill to database
systemprompt core skills sync --direction to-db

# Verify it loaded
systemprompt core skills show my_skill

# Validate the plugin
systemprompt core plugins validate {plugin-id}

# Generate plugin output (bundles skills into SKILL.md)
systemprompt core plugins generate --id {plugin-id}

CLI Commands

Command	Purpose
systemprompt core skills list	List all skills
systemprompt core skills show <skill_id>	Show skill details
systemprompt core skills create	Create a new skill (interactive)
systemprompt core skills create --name <id> --display-name "Name" --description "desc"	Create non-interactively
systemprompt core skills edit <skill_id>	Edit skill config
systemprompt core skills edit <skill_id> --enable	Enable a skill
systemprompt core skills edit <skill_id> --disable	Disable a skill
systemprompt core skills edit <skill_id> --set key=value	Set a specific field
systemprompt core skills delete <skill_id>	Delete a skill
systemprompt core skills status	Check DB sync status
systemprompt core skills sync --direction to-db	Push disk skills to database
systemprompt core skills sync --direction to-disk	Pull database skills to disk
systemprompt core skills sync --dry-run	Preview sync without changes
systemprompt core plugins validate <plugin-id>	Validate plugin (checks skill references)
systemprompt core plugins generate --id <plugin-id>	Generate plugin export (bundles SKILL.md)

How Skills Reach Agents

config.yaml: assigned_agents → Agent loads skill at startup
Plugin config: skills.include → Plugin bundles skill for distribution
Agent YAML: metadata.skills  → Agent advertises skill in A2A card

An agent receives a skill when both of these are true:

1. The skill's config.yaml lists the agent in assigned_agents
2. The agent's YAML lists the skill ID in metadata.skills

How Skills Reach the Marketplace

1. Skill exists in services/skills/{id}/ with config.yaml + index.md
2. A plugin references the skill ID in its skills.include list
3. systemprompt core plugins generate bundles the skill as SKILL.md (frontmatter + body)
4. The plugin is uploaded to the marketplace
5. Users install the plugin, which imports skills back into config.yaml + index.md

Naming Conventions

Convention	Example
Skill ID	snake_case — my_custom_skill
Skill directory	Must match ID — services/skills/my_custom_skill/
Plugin ID	kebab-case — my-plugin
Agent name	snake_case — my_agent
Exported SKILL.md path	skills/{kebab-case}/SKILL.md — skills/my-custom-skill/SKILL.md

Prefix skill IDs with a namespace when they belong to a specific plugin (e.g., systemprompt_admin_*, sales_crm_*).

Common Tasks

Create a Skill from Scratch

mkdir -p services/skills/my_skill
# Write config.yaml and index.md (see formats above)
# Add to services/skills/config.yaml includes
# Add to plugin config.yaml skills.include
systemprompt core skills sync --direction to-db
systemprompt core skills show my_skill
systemprompt core plugins validate my-plugin

Move a Skill Between Plugins

Remove the skill ID from one plugin's skills.include and add it to another's. The skill directory does not move -- only the plugin reference changes.

# Edit both plugin configs, then validate
systemprompt core plugins validate old-plugin
systemprompt core plugins validate new-plugin

Export a Plugin with Skills

systemprompt core plugins generate --id my-plugin
# Output goes to services/plugins/my-plugin/ (or --output-dir)

Debug a Missing Skill

systemprompt core skills list
systemprompt core skills status
systemprompt core skills sync --dry-run
systemprompt core plugins validate my-plugin

Important Notes

• Skill IDs must be unique across the entire platform
• The id in config.yaml must match the directory name exactly
• Frontmatter name and description should match config.yaml values
• During export, frontmatter is rebuilt from config.yaml -- config.yaml is the source of truth
• Skills are never duplicated into plugin directories -- plugins only reference IDs
• Auxiliary files in references/, templates/, examples/ are included in plugin exports
• Always run core skills sync after creating or modifying skills on disk
• Always run core plugins validate after changing plugin skill references