# your-skill-name

Adopt this skill: https://proskills.md/skills/general/ottili-one-skills-templates-skill

Page: https://proskills.md/skills/general/ottili-one-skills-templates-skill
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: templates/skill/SKILL.md
size: 671
sha: 22d5777d89a4c6364926790fde7b6afb8d424fdc
upstream: https://github.com/ottili-one/skills/blob/main/templates/skill/SKILL.md

```text
---
name: your-skill-name
version: "1.0.0"
description: Use when [specific triggering conditions and symptoms the agent should recognize].
category: general
license: MIT
compatibility:
  - Claude Code
  - Codex
  - Cursor
---

# Your Skill Name

## Overview

One or two sentences describing the core principle.

## When to use

- Symptom or situation A
- Symptom or situation B

## When not to use

- Case where another skill or approach is better

## Procedure

1. Step one
2. Step two
3. Validation step

## Output contract

What the agent must deliver when finished.

## References

Link to supporting files in this directory if needed (`references/`, scripts, etc.).
```

## File: README.md
upstream: https://github.com/ottili-one/skills/blob/main/README.md

````text
# Ottili ONE Skills

> ⚠️ **Important Note:** These capabilities and skills were developed within a fully automated, blind, and zero-Human-In-The-Loop (no-HITL) multi-agent system. Consequently, they may contain bugs, edge cases, or features that do not function as intended in all environments.

A repository of **Agent Skills** — folders of instructions, scripts and references that an
AI agent discovers and applies to a specific task — together with the tooling that
validates, indexes, catalogues and installs them.

A skill is a folder that contains a `SKILL.md` with YAML frontmatter:

```yaml
---
name: honest-status
description: Use when writing a status report that claims something works.
---
```

The frontmatter must be followed by the skill body; optional `references/`, `scripts/`,
`tests/` and `config/` subfolders carry supporting material. The format follows the open
Agent Skill standard at [agentskills.io](https://agentskills.io/specification).

This repository holds **39 skills** in 12 packages, the generated `catalog.json` that
describes them, the tools that work with them, and the ten engineering playbooks
(`skills/engineering/**`) that Ottili agents use to build reliable software.

## Repository layout

```
skills/
├── agentic-data/          # 10 data-plane agent skills (browsing, research, MCP, LLM judges, …)
├── business-de/           # 10 German business-domain skills (DATEV, XRechnung/ZUGFeRD, GoBD, …)
├── core/                  # team-maintained official skills
├── curated/               # vetted third-party skills
├── community/             # placeholder for community contributions (no skills yet)
├── ottili-ai/             # placeholder for Ottili AI runtime skills (no skills yet)
├── engineering/           # 10 engineering playbooks + checkers, self-tests and docs
├── orchestrator-preamble/ # the generated orchestrator preamble (1 skill)
└── ref-<subject>/         # 6 reference skills, one per business-de subject
scripts/                   # install, validate, generate, index
├── lib/                   #   install-manifest.sh: the JSON manifest of an install run
└── ottili_contracts/      #   the versioned contracts: schemas, typed view, examples
schema/catalog.schema.json # JSON Schema for catalog.json
templates/skill/SKILL.md   # starting point for a new skill
catalog.json               # GENERATED catalogue of every skill
index/                     # GENERATED index/INDEX.md and index/skills.json
docs/                      # interfaces/, truth/, gaps/, reviews/, R3_OWNERS.json
tests/                     # repository-level test suites (hygiene, orchestrator, reviews)
.github/workflows/         # CI: validate.yml
```

Packages are **derived from the folders** under `skills/` at generation time — there is no
hand-maintained package or skill list anywhere in the tooling.

## Requirements

- `bash`, `git`
- `python3` (CI runs 3.12)
- `node` (the generators and the Node test suites)
- optional: `pip install pyyaml` (required by the problem+json catalogue checker),
  `pip install pytest` for the pytest-style suites, `pip install pydantic jsonschema` for
  the contract tests of the published CLI contracts

## Install the repository

There is no build step and no package manifest — the repository is Markdown, Python and
Node scripts.

```sh
git clone https://github.com/Ottili-ONE/skills.git
cd skills
```

## Install skills into an agent

Each agent reads skills from its own directory. The convention is the same everywhere: a
skill is a folder named after the skill's `name` containing a `SKILL.md` with YAML
frontmatter. Copy (or symlink) the folder into the agent's skills directory and restart
the agent.

`scripts/install.sh` does this for you.

```sh
# Dry-run first: prints every action, writes nothing, exits 0.
./scripts/install.sh --target codex --dry-run pg-rls-multitenant

# Install (copies the skill folder into ~/.codex/skills/).
./scripts/install.sh --target codex pg-rls-multitenant

# Replace an existing installation.
./scripts/install.sh --target claude --force honest-status

# Symlink instead of copy.
./scripts/install.sh --target cursor --link shared-tree-git

# Install every skill of a package.
./scripts/install.sh --target cursor --package engineering
```

| Option | Effect |
| --- | --- |
| `--target <name\|path>` | Required. Named agent, or a literal directory path. |
| `--package <name>` | Install every skill in a package. |
| `--check` | Verify every source and the target without writing anything. |
| `--dry-run` | Print the actions, write nothing, exit 0. |
| `--force` | Remove and re-copy an existing destination folder. |
| `--link` | Create a symlink instead of copying. |
| `--json` | Print the install manifest as one JSON object (contract `ottili.skills.install-manifest/v1`). |
| `--version` | Print the contract id of the manifest, exit 0. |
| `-h`, `--help` | Print help, exit 0. |

| `--target` | Destination |
| --- | --- |
| `codex` | `$HOME/.codex/skills` |
| `claude` | `$HOME/.claude/skills` |
| `cursor` | `$HOME/.cursor/skills` |
| `agents` | `$HOME/.agents/skills` |
| any other value | treated as a literal directory path |

Behaviour:

- **Idempotent** — without `--force` an existing destination folder is left untouched and
  the script prints `skip: … already exists (use --force to overwrite)` and exits 0.
- **Source resolution** — a skill is located by its folder name alone, searched in the
  `skills/` tree next to the script; no catalogue lookup is involved.
- **Packages** — derived at install time from the folders. `generic` installs every skill
  in the repository; `meta` is reserved and ships nothing. The `ref-*` folders are real
  packages: `--package ref-datev-extf` installs that skill.
- **Machine-readable** — `--json` prints exactly one JSON object, the install manifest of
  contract `ottili.skills.install-manifest/v1`; stdout carries the manifest and stderr
  stays empty.
- **Exit codes** — `0` all requested skills installed, linked, skipped or verified, `1` a
  skill or package could not be resolved (or the target could not be created), `2` usage
  error (missing `--target`, missing skill/package, unknown option).

The full contract lives in [`docs/interfaces/install.md`](docs/interfaces/install.md).

### Where agents look for skills

Directory conventions verified against the vendor documentation (retrieved 2026-10-07):

- **Claude Code** — `~/.claude/skills/<name>/SKILL.md`; skills are auto-discovered from
  the skills directory. <https://docs.anthropic.com/en/docs/claude-code/skills>
- **Codex (OpenAI)** — `$CODEX_HOME/skills/<name>/SKILL.md`, typically `~/.codex/skills/`.
  <https://github.com/openai/skills>
- **Cursor** — `~/.cursor/skills/<name>/SKILL.md` (a project-scoped `.cursor/skills/`
  also works). <https://docs.cursor.com/agent/skills>
- **Generic agent runtimes** — `~/.agents/skills/<name>/SKILL.md`, or any directory the
  runtime announces; the folder + `SKILL.md` layout is identical.

`https://github.com/anthropics/skills` ships reusable skill folders in exactly this
layout and is a useful reference for what a well-formed skill looks like.

## Browse and install from the catalogue

`catalog.json` is **generated**, never hand-edited: `scripts/gen-catalog.mjs` walks every
`skills/<package>/<name>/SKILL.md`, reads the frontmatter and writes one entry per skill.
Packages are derived from the `skills/` folders at generation time.

```sh
node scripts/gen-catalog.mjs            # regenerate catalog.json
node scripts/gen-catalog.mjs --check    # exit 1 if the committed catalog would change
```

Two catalogue-driven helpers sit next to it:

```sh
python3 scripts/list-skills.py                       # grouped by package
python3 scripts/list-skills.py --package business-de --format json
python3 scripts/list-skills.py --target codex        # marks already-installed skills
python3 scripts/install-skill.py --list              # list installable skills
python3 scripts/install-skill.py honest-sta
````
