skills: Instructions file for Codex

AGENTS.md

This file provides guidance to AI agents working with code in this repository.

Project Overview

This repository contains agent skills — custom tools and capabilities for AI agents, managed with Tessl.

Repository Structure

skills/<name>/
├── tile.json   # Skill metadata and version
└── SKILL.md    # Agent instructions

Development Workflow

Creating a skill

Note: tessl skill new has a bug where it generates a nested structure. Create skills manually.

// skills/<name>/tile.json
{
  "name": "nagaakihoshi/<name>",
  "version": "0.1.0",
  "summary": "<description>",
  "private": true,
  "skills": {
    "<name>": {
      "path": "SKILL.md"
    }
  }
}

Naming convention

Use gerund form for skill names (e.g., developing-tessl-skills, not tessl-skill-dev).

Preparing a skill for PR

1. Optimize: tessl skill review --optimize skills/<name>
   • Aim for a score of 70% or higher
2. Bump version in tile.json following semver
3. Lint: tessl skill lint skills/<name>
4. Stage both SKILL.md and tile.json

Note: tessl skill review requires local login (tessl login). It cannot authenticate in CI.

CI behavior

• PR: tessl skill lint runs on changed skills only
• Merge to main: tesslio/publish@main publishes to the Tessl Registry

Skill Authoring Guidelines

Follow the Claude skill best practices.

Frontmatter

• name: lowercase, hyphens only, max 64 chars, gerund form (e.g., processing-pdfs)
• description: third person, max 1024 chars, must describe what the skill does AND when to use it

# Good
description: Runs the complete local development lifecycle for a Tessl skill. Use when preparing a skill for pull request or publication.

# Bad — first person, no trigger condition
description: Helps you prepare Tessl skills for publishing.