alavida-ai/skill-authoring

Skill Authoring

How to design, structure, and ship a skill in the Agonda system.

What Is a Skill?

A skill is a self-contained capability owned by a domain. It wraps a CLI, API, workflow, or text processing pipeline behind a standardized interface so any domain can adopt it without understanding its internals. The SKILL.md file is the contract — agents navigate to it, read it, and act. Skills are written for LLM consumption first, human consumption second.

Skills are NOT standalone programs. They are documented interfaces backed by an implementation (a script, an API client, a workflow, or a knowledge processing pipeline).

Two Skill Templates

Choose the template that fits. If your skill calls external APIs or wraps a CLI, use CLI/API. If your skill reads/writes markdown files and transforms knowledge, use knowledge processing.

| Template | Use When | Sections | Tools | Example Skills | |----------|----------|----------|-------|----------------| | CLI/API | Wrapping an external API, CLI tool, or deployed service | 13 sections | Bash(./scripts/...) | buying-signals, icp-discovery, lead-discovery | | Knowledge Processing | Processing text — extracting, connecting, or validating knowledge files | 8 sections | Read, Write, Edit, Grep, Glob | reduce, reflect, verify |

Detailed templates: See cli-api-template.md and knowledge-processing-template.md.

YAML Frontmatter Spec

Every SKILL.md requires frontmatter. This is what agents read to decide whether to activate a skill.

---
name: my-skill
description: >
  One-paragraph description with explicit trigger phrases.
  "ALWAYS use this skill when asked to [do X], [do Y], or [do Z]."
last-updated: 2026-02-10
allowed-tools: Bash(./scripts/my-skill.js:*)
---

| Field | Required | Purpose | |-------|----------|---------| | name | Yes | Kebab-case identifier. Must match directory name. Knowledge processing skills use domain:skill-name format. | | description | Yes | Multi-line with explicit trigger conditions. This is the primary triggering mechanism — agents match against it. | | last-updated | Yes | ISO-8601 date. Drives freshness checks. | | allowed-tools | Yes | Exact tool permissions, scoped as tightly as possible. Never grant Bash(*). | | based-on | No | Lineage reference when adapting a published base skill. Format: github.com/{org}/{repo}/{skill-name}@v{semver} |

Trigger phrasing matters. Use explicit language: "ALWAYS use this skill when asked to..." followed by concrete actions. Vague descriptions mean agents won't find the skill.

Tool scoping matters. Bash(./scripts/my-skill.js:*) allows only the skill's own script. Read, Write, Edit, Grep, Glob for knowledge processing. Never over-grant.

Progressive Disclosure

Skills use a three-level loading system to manage context efficiently:

| Level | What Loads | When | Size Target | |-------|-----------|------|-------------| | 1. Metadata | name + description from frontmatter | Always in context | ~100 words | | 2. SKILL.md body | Full instructions and workflow | When skill triggers | <500 lines | | 3. References | references/, templates/, scripts/ | As needed during execution | Unlimited |

Keep SKILL.md body to the essentials and under 500 lines. Split detailed content into references/ files. Always reference split-out files from SKILL.md with clear descriptions of when to read them.

Key principle: When a skill supports multiple variations, keep only the core workflow and selection guidance in SKILL.md. Move variant-specific details into separate reference files. Keep references one level deep — all reference files link directly from SKILL.md.

Skill Directory Layout

skill-name/
├── SKILL.md              # Required — the skill contract
├── scripts/              # Optional — CLI entry points
│   └── skill-name.js
├── references/           # Optional — detail docs loaded on demand
│   └── topic.md
├── templates/            # Optional — output templates
│   └── template.html
└── assets/               # Optional — files used in output (images, fonts)

The SKILL.md is the interface. Everything else is implementation detail. Do not create README.md, CHANGELOG.md, or other auxiliary files — the skill should only contain what an agent needs to do the job.

Writing for Agents

• Common Actions table — map natural language ("User says X") to commands or actions. This is how agents match user intent.
• Numbered workflows — agents follow numbered sequences reliably. Number every step.
• TypeScript for data models — document request/response shapes using TypeScript notation. Use union types for enums, ? for optional fields, inline comments for format hints.
• Freshness notice — include near the top: "If more than 30 days since last-updated, verify the API or data models haven't changed."

Reference Files

| File | Contents | Read when | |------|----------|-----------| | cli-api-template.md | 13-section document structure, config management patterns, CLI patterns, output modes, testing patterns | Building a skill that wraps an API or CLI tool | | knowledge-processing-template.md | 8-section document structure, key differences from CLI/API, quality gates, methodology | Building a skill that processes knowledge files | | checklists.md | Shipping checklists for both templates | Final validation before shipping any skill |

Skill Creation Process

1. Understand — gather concrete examples of how the skill will be used. What would a user say to trigger it?
2. Plan resources — identify reusable scripts, references, and assets. What does an agent need to execute repeatedly?
3. Write SKILL.md — frontmatter first (name, description, triggers), then body following the appropriate template.
4. Build references — split detailed content into references/ files. Keep SKILL.md lean.
5. Test with real tasks — use the skill on actual work, notice struggles, iterate.
6. Ship — validate against the appropriate checklist in checklists.md.