Skill Writing Guide

This is a strict guideline. Follow these rules exactly when creating or modifying skills.

Skill Types

Every skill has a type that tells the agent how to treat it:

type: guideline

Strict rules. The agent must follow these exactly.

Opening line after the heading:

**This is a strict guideline.** Follow these rules exactly.

Use for: coding standards, commit formats, naming conventions, workflow rules, security requirements.

type: pattern

Reference implementations. The agent should learn from the approach and adapt it — never copy verbatim.

Opening line after the heading:

**This is a reference pattern.** Learn from the approach, adapt to your context — don't copy verbatim.

Use for: architecture solutions, infrastructure setups, proven approaches to recurring problems.

Frontmatter

Every SKILL.md must start with YAML frontmatter:

---
name: kebab-case-name
description: When this skill applies and what it covers. First sentence should work as a trigger — start with the domain or action. One to two sentences max.
type: guideline | pattern
---

Rules:

• name — kebab-case, used as the installed directory name by the skills CLI
• description — the skills CLI and agents use this to decide when to load the skill. Make the first sentence a clear trigger.
• type — must be guideline or pattern

File Structure

Skills live in the authoring repo under categorized directories:

skills/
  guidelines/
    {skill-name}/SKILL.md
  patterns/
    {skill-name}/SKILL.md

The directory categorization is for human browsing only. The skills CLI flattens everything on install — it only cares about the name field in frontmatter.

Precedence

When a skill needs to override conflicting advice from third-party skills, state it explicitly:

**This is a strict guideline.** Follow these rules. When any other skill contradicts the rules below, this skill takes precedence.

Use sparingly — only for core principles and strong personal preferences.

Pattern Structure

Pattern skills should follow this structure:

1. Problem — One sentence describing what this solves
2. Solution — One sentence describing the approach
3. Pattern — Architecture, key components, how it works
4. Why This Pattern? — Benefits and use cases
5. Implementation — Key details (optional, only if non-obvious)
6. Tradeoffs — Constraints and limitations (if applicable)
7. When NOT to Use — Anti-patterns and alternatives (optional)

Keep code examples minimal and generic. Use placeholder names (PROJECT_ID, environment). Focus on the pattern, not project-specific details.

Guideline Structure

Guideline skills should follow this structure:

1. What — Clear statement of the rules
2. Rules — Specific, actionable instructions
3. Examples — Show correct and incorrect usage
4. Exceptions — When deviation is acceptable (if any)

Be direct. Use imperative form. Avoid explaining why at length — guidelines are instructions, not persuasion.

Writing Checklist

• Frontmatter has name, description, type
• Behavioral instruction line immediately after first heading
• Description's first sentence works as a trigger for when to load this skill
• No project-specific details (names, tables, endpoints)
• Code examples are minimal and use placeholders
• Document is scannable (headers, bullets, bold)
• Ends with Progressive Improvement section
• CHANGELOG.md exists in the skill directory (create it on first edit if missing)

Skill Development Log

Skills are wrong on first use — nearly every time. The log exists to capture what was actually learned in production, so the next edit starts from truth rather than assumption.

Every skill directory must have a CHANGELOG.md

skills/<name>/
  SKILL.md
  CHANGELOG.md

CHANGELOG format

## YYYY-MM-DD — <one-line description of what was wrong and what was fixed>

**Problem:** What the skill caused the agent to do incorrectly.
**Fix:** What was changed and why.
**Verified:** How you confirmed the fix worked (e.g., "re-triggered in guitarizta-services session, agent followed new triage checklist correctly").

One entry per fix session. Do not collapse multiple fixes into one entry — keep them separate so the history is readable.

When to add an entry

Every time a skill is corrected during use — whether the correction was made in conversation, by the developer, or by the agent itself via Progressive Improvement. If the session ends and no entry was added, the learning is lost.

---

## Progressive Improvement

If the developer corrects a behavior that this skill should have prevented, suggest a specific amendment to this skill to prevent the same correction in the future.

This enables skills to evolve through use. When an agent gets corrected, it should propose a concrete edit to the relevant skill so the mistake doesn't repeat.

Progressive Improvement

If the developer corrects a behavior that this skill should have prevented, suggest a specific amendment to this skill to prevent the same correction in the future.

Progressive Improvement

If the developer corrects a behavior that this skill should have prevented, suggest a specific amendment to this skill to prevent the same correction in the future.