Skip to content

create-your-first-skill.md

Latest commit

 

History

History
176 lines (118 loc) · 4.59 KB

create-your-first-skill.md

File metadata and controls

176 lines (118 loc) · 4.59 KB
Raw

Create Your First Skill

AgentOps is built out of skills. A good first contribution is not "make a huge framework." It is "teach the system one reusable intent."

This guide shows the smallest current path to adding a new skill without tripping the repo gates.

Before You Start

Pick a skill idea that is:

  • Narrow: one clear job, not an entire workflow
  • Reusable: something you would invoke more than once
  • Observable: it should produce an artifact, decision, or validation step someone can check

Good first-skill ideas:

  • A focused validator for one common failure mode
  • A domain-specific research or triage helper
  • A contribution helper for one external tool or service
  • A narrow knowledge-management skill that transforms one artifact type into another

Avoid first-skill ideas that:

  • duplicate an existing skill in docs/SKILLS.md
  • require a big new runtime abstraction
  • mix discovery, implementation, and release into one entrypoint

The Minimum Shape

Create a directory:

mkdir -p skills/your-skill-name

Then create skills/your-skill-name/SKILL.md using the current frontmatter contract:

---
name: your-skill-name
description: 'What this skill does. Triggers: "trigger phrase", "other phrase".'
skill_api_version: 1
context:
  window: fork
  intent:
    mode: task
  sections:
    exclude: [HISTORY]
metadata:
  tier: execution
---

# your-skill-name

## Purpose

What this skill is for and what problem it solves.

## When to Use

- Trigger condition one
- Trigger condition two

## Inputs

- What the user should provide
- Any repo or runtime assumptions

## Instructions

1. The first concrete step.
2. The main execution flow.
3. The validation or closeout step.

## Output

- What artifact, decision, or side effect this skill should produce

## Examples

```text
Example prompt or invocation

Use [templates/skill.template.md](templates/skill.template.md) as a starting point if you want a copyable scaffold.

## Pick The Right Tier

Most first contributions should use one of these:

- `execution`: a focused task skill
- `session`: onboarding, status, or recovery help
- `knowledge`: transforms or traces knowledge artifacts
- `product`: product, docs, or release oriented
- `contribute`: contribution-specific workflow support

See [SKILL-API.md](SKILL-API.md) for the full frontmatter contract and [../skills/SKILL-TIERS.md](https://github.com/boshu2/agentops/blob/main/skills/SKILL-TIERS.md) for the full taxonomy.

## Keep The Entry Point Lean

Your `SKILL.md` should be the operator surface, not the whole encyclopedia.

If the skill needs more detail, add:

- `references/*.md` for deeper guidance
- `scripts/*.sh` for helper logic or validation
- `schemas/*.json` only when downstream tooling consumes a structured contract

If you add files under `references/`, make sure `SKILL.md` links to them. CI fails when reference files exist but are not linked.

## Common CI Footguns

These are the most common ways first skill PRs fail:

- Missing or stale frontmatter
- New references not linked from `SKILL.md`
- Adding a skill directory without syncing counts
- Leaving `TODO` or `FIXME` text in `SKILL.md`
- Adding symlinks anywhere in the repo

This repo is strict because skills are shipped artifacts, not informal notes.

## Validate Before You Open A PR

Run the current local checks:

```bash
# Required for any skill change
bash skills/skill-builder/scripts/heal.sh --strict

# Required when docs or skill counts change
bash tests/docs/validate-doc-release.sh

# If you added or removed a skill directory
python3 scripts/generate-skill-mesh.py

# Recommended fast changed-surface check
ao gate check --fast --scope worktree

Codex loads the same skills/your-skill-name/ package; nothing is generated for it. If your skill is explicit-only (disable-model-invocation: true), give it an agents/openai.yaml with policy.allow_implicit_invocation: false, then run:

bash scripts/validate-codex-api-conformance.sh

Where To Look For Good Examples

Start from a simple, high-signal skill rather than the biggest orchestration layer.

Useful examples:

Opening The PR

Explain four things clearly:

  • the user intent the skill handles
  • why an existing skill was not enough
  • what artifact or outcome it produces
  • what checks you ran locally

Useful supporting docs: