Skip to main content

Skills

Skills in Venue.sh are reusable AI workflow instructions - step-by-step guidance that coding agents load when a task matches the skill's trigger conditions. Venue.sh automatically discovers and catalogs skills from your connected Git repositories.

Skills follow the agentskills.io specification. You do not register skills manually. Venue.sh finds them during repository content ingestion and keeps the catalog in sync as repositories change.

Key Capabilities​

  • Discovery - Browse skills discovered across your organization's connected repositories.
  • Search - Filter by name or description keywords.
  • Inspection - View skill metadata, including triggers, author, version, license, and companion content inventory.
  • Reading - View the rendered markdown from each skill's SKILL.md file.
  • Assistant integration - Ask the Assistant about available skills using natural language.

Discovered skills are also synced to the software catalog as Skill entities, so you can relate them to Components and other catalog entities.

Browsing Skills​

  1. Open Skills from the sidebar (under AI).
  2. Use the search box to filter by name or description.
  3. Click a skill to open its detail page.

The list shows each skill's name, description, source repository, and when it was last updated.

How skills appear

Skills are discovered automatically when repository content ingestion finds SKILL.md files in connected repositories. New skills appear after the next ingestion run. Removed skills are dropped from the catalog when their SKILL.md file is deleted.

For prerequisites and configuration, see Ingestion & Summary.

Viewing Skill Details​

Each skill detail page shows:

  • Metadata - Name, description, trigger summary, author, version, license, compatibility, and allowed tools (when present in frontmatter).
  • Companion content inventory - Which optional directories exist alongside the skill (scripts/, references/, agents/, assets/, rules/) and how many files each contains.
  • Source - The repository and directory path where the skill was discovered.
  • Skill body - The rendered markdown content from SKILL.md.

The trigger summary is extracted from phrases like "Use when..." in the skill description or body, helping you quickly see when an agent should load the skill.

Authoring Skills in Your Repository​

To make a skill discoverable in Venue.sh, add a skill directory to a connected repository with a SKILL.md file at its root. The filename is matched case-insensitively (SKILL.md or skill.md).

Directory structure​

A skill is a directory, not a single file. The minimum requirement is SKILL.md. Optional companion directories provide supporting material:

my-skill/
├── SKILL.md          # Required - skill definition and instructions
├── scripts/          # Optional - executable scripts the agent can run
├── references/       # Optional - reference documents
├── agents/           # Optional - agent definitions
├── assets/           # Optional - images, templates, or other assets
└── rules/            # Optional - rule files

Venue.sh catalogs the companion directory inventory and file counts. It does not ingest the full content of companion files into the Skills catalog.

SKILL.md format​

SKILL.md uses YAML frontmatter followed by markdown body content:

---
name: my-skill
description: Short summary of what this skill does. Use when the user asks to sync mkdocs navigation.
license: Apache-2.0
compatibility: Cursor, Claude Code
metadata:
  author: Platform Team
  version: '1.0'
allowed-tools: bash, read, write
---

# My Skill

Detailed instructions for the agent go here.

## Workflow

1. Step one
2. Step two

Frontmatter fields​

FieldRequiredDescription
nameYesLowercase identifier (letters, numbers, hyphens; max 64 characters)
descriptionRecommendedBrief summary (max 1024 characters). Include "Use when..." to define trigger conditions
licenseNoSPDX license identifier or free text
compatibilityNoWhich agents or tools the skill supports (max 500 characters)
metadataNoKey-value map for additional fields such as author and version
allowed-toolsNoTools the skill expects the agent to use (experimental)

If frontmatter is missing or incomplete, Venue.sh derives the skill name from the directory name and extracts a description from the first paragraph of the markdown body.

Common locations​

Skills can live anywhere in a connected repository. Common conventions include:

  • .cursor/skills/<skill-name>/SKILL.md - Cursor plugin and workspace skills
  • skills/<skill-name>/SKILL.md - Repository-level skills

Skills with the same name in different repositories are treated as separate catalog entries, disambiguated by their source repository.

Useful Things to Ask About​

The Assistant can answer questions about skills discovered from your connected repositories. For example:

  • "What skills are available for Helm chart scaffolding?"
  • "Show me skills related to mkdocs navigation"

Permissions​

Skill catalog access follows the same pattern as repository content:

RolePermissions
Admin, Editor, Contributor, Viewer, DemoRead (list and detail)

Skills are created, updated, and removed automatically by the ingestion pipeline. There is no manual registration or deletion in the dashboard.

Troubleshooting​

SituationWhat to do
Skill not appearing after commitWait for the next repository content ingestion run. Confirm the repository is connected, ingestion is enabled, and the file is named SKILL.md (case-insensitive). See Ingestion & Summary.
Skill disappeared from the catalogThe SKILL.md file or its parent directory may have been removed from the repository.
Invalid skill name errorThe name field must use only lowercase letters, numbers, and hyphens (max 64 characters).
Missing trigger summaryAdd a "Use when..." phrase to the description frontmatter field or the markdown body.
Cannot access the Skills pageYour role may not include Skill read permission. Contact your Venue administrator.

See Also​