Skip to content

skill-style-guide.md

Latest commit

 

History

History
116 lines (83 loc) · 3.47 KB

skill-style-guide.md

File metadata and controls

116 lines (83 loc) · 3.47 KB
Raw

Skill Style Guide

This guide is the normative style contract for LLM-first skills shipped with or created inside gentle-pi projects.

Purpose

A skill is a runtime instruction contract for an LLM. It should make future agent behavior more reliable by encoding reusable workflow rules, decision gates, and output expectations.

A skill is not a tutorial, article, README, or generic checklist for humans.

When to create a skill

Create or update a skill when:

  • a workflow or convention is reused across sessions;
  • project-specific constraints differ from generic best practices;
  • a decision tree helps the agent choose safely;
  • templates, schemas, or local references improve repeatability;
  • agents keep missing the same instruction without an explicit runtime contract.

Do not create a skill for:

  • one-off tasks;
  • generic documentation;
  • rules that belong in tests, linters, or executable code;
  • broad background context without concrete execution rules.

Required structure

Use this directory shape:

skills/{skill-name}/
├── SKILL.md
├── assets/       # optional: templates, schemas, examples, fixtures
└── references/   # optional: longer local docs or rationale

SKILL.md must use this section order:

  1. Activation Contract
  2. Hard Rules
  3. Decision Gates
  4. Execution Steps
  5. Output Contract
  6. References

Omit optional supporting directories when they are not needed.

Frontmatter

Use YAML frontmatter with this shape:

---
name: {kebab-case-skill-name}
description: "Trigger: {phrases users or agents will say}. {What this skill does}."
license: Apache-2.0
metadata:
  author: gentleman-programming
  version: "1.0"
---

Rules:

  • name must be kebab-case and match the skill directory unless there is a deliberate compatibility reason.
  • description must be one physical line, quoted, YAML-safe, and trigger-rich.
  • Put essential trigger words first in description.
  • Do not add a Keywords section.
  • Preserve license and metadata unless the project has a stronger local convention.

Writing rules

  • Write imperative runtime instructions, not explanatory prose.
  • Keep SKILL.md concise: target 180–450 tokens, recommended max 700, hard max 1000.
  • Prefer bullets and compact decision tables over paragraphs.
  • State when to activate the skill and when not to activate it.
  • Preserve author intent when improving an existing skill.
  • Do not invent domain policies, triggers, or constraints. Ask or mark ambiguity instead.
  • Move long examples, schemas, generated templates, and background rationale to assets/ or references/.
  • References must point to local files that ship with the project or package.

Decision gates

Use a table when choices matter:

| Situation | Action |
| --- | --- |
| Missing frontmatter | Fix required fields |
| Existing skill covers it | Update the existing skill instead |
| Long examples needed | Move them to `assets/` |

Decision gates should prevent unsafe overreach, duplicate skills, and unnecessary ceremony.

Output contract

Every skill should tell the agent what to return. Good output contracts include:

  • files created or modified;
  • commands or verification run;
  • registry refresh needed;
  • unresolved ambiguities;
  • residual risks.

Registry expectations

After creating, removing, moving, or renaming project skills, refresh the skill registry when available:

/skill-registry:refresh

The registry is an index. SKILL.md remains the source of truth.