# Authoring skills and rules for the UFO Tech catalog The catalog at https://ufo-tech.space/en/ai is built from the `ai/` folder of the ufo-tech.space site repository and from providers' public git repositories (GitHub, GitLab, Bitbucket). Every item gets a page with filters, install commands for each agent and an entry in `/ai/catalog.json`, from which agents install it (see the `ufo-catalog` skill). Items of a provider are not copied: the catalog keeps their description and links to the files at the indexed commit. How a repository gets connected: https://ufo-tech.space/en/ai/providers (acceptance is still in development). ## 1. Decide what you are making - **Skill** — a task an agent should do on its own when it fits (a workflow, a generator, a checklist with scripts). Folder: `ai/skills//`. Installed as a folder (`.claude/skills//`, `.agents/skills//`). - **Rule** — instructions the agent should always follow in a project (library usage, code style). Folder: `ai/rules//`. Installed as one markdown file referenced from `CLAUDE.md` / `AGENTS.md` / Cursor / Copilot. `` is short kebab-case Latin (`develop-folder`, `json-rpc-bundle`); it is the skill `name` and never changes after publishing (agents update installed items by slug). ## 2. Folder layout ``` ai/skills// ai/rules// ├── manifest.yaml ├── manifest.yaml ├── README.uk.md ├── README.uk.md ├── README.en.md ├── README.en.md ├── shared/ (optional) └── universal/.md # the rule itself, in English ├── claude/SKILL.md └── codex/SKILL.md ``` - **Variant folders** are agent ids from the catalog config: `claude` (Claude Code), `codex` (Codex); for rules use `universal` — one file for every agent. A skill may also have `universal/` (read by link, not installed). - **`shared/`** holds files common to all variants (scripts, templates, reference docs). At install time they are merged into each variant; a variant's own file with the same path wins. Never copy shared files into variants. - Only real content files: no `.DS_Store`, no secrets, tokens, internal URLs or personal data. - **A provider's repository** uses the same layout: many items in `skills//` and `rules//`, or a single item with `manifest.yaml` (and its variant folders) right in the repository root — then the manifest must give `name` and `type`. Add a license file to the repository root. ## 3. manifest.yaml ```yaml name: my-skill # slug; required for an item in a repository root, otherwise the folder name type: skill # skill | rule; required for an item in a repository root title: uk: Назва українською en: English title summary: uk: Одне-два речення — що робить і коли корисно. en: One or two sentences — what it does and when it helps. authors: # required, like "authors" in composer.json; name is the git name - name: your-git-name email: you@example.com # optional homepage: https://github.com/your-git-name # optional; a GitHub profile gives the avatar role: Developer # optional support: # optional, like "support" in composer.json source: https://github.com/vendor/ai-skills # the public repository page issues: https://github.com/vendor/ai-skills/issues tags: [php, symfony, ai-workflow] # lowercase kebab-case; reuse existing tags from /ai/catalog.json first # rules only, optional: limit the agents a universal variant installs for # agents: [claude, codex, cursor, copilot, agents-md] ``` Titles and summaries are shown on cards and used by search and SEO — concrete, no marketing. ## 4. README..md One file per language with the same name pattern: `README.uk.md` and `README.en.md` (both required). The page shows the README in the visitor's language. Start with `# Title` (it is dropped on the page, the title comes from manifest.yaml), then: what it does, when it is triggered, platforms / requirements, extra install steps the agent will NOT do itself (hooks, settings), and the layout of the installed folder. Links to site pages are written without the language prefix (`/docs/...`, `/ai/rule/`). ## 5. SKILL.md (per agent variant) Follows the open Agent Skills format: ```markdown --- name: description: . Use when — even if the user does not name the skill. --- # Title Instructions… ``` - `name` = slug; `description` is what the agent uses to decide when to load the skill — put the triggers there, keep it under ~1000 characters. - Write instructions in English, imperative, specific; keep SKILL.md under ~500 lines and move long reference material into separate files (usually `shared/`), linked from SKILL.md. - Paths: refer to bundled files relative to the skill folder, and name the install location for the agent: Claude Code `~/.claude/skills//` (global) or `.claude/skills//` (project); Codex `~/.agents/skills//` or `.agents/skills//`. - Agent-specific parts (Claude Code hooks, `CLAUDE.md` vs `AGENTS.md`, tool names) go into the variant's SKILL.md or its own extra files; everything else into `shared/`. - Scripts: provide `.sh` (bash 3.2 compatible, macOS/Linux/WSL/Git Bash) and `.ps1` (Windows PowerShell 5.1) versions with the same behaviour; scripts must be idempotent and never overwrite user files silently. Add `shared/.gitattributes` with `*.sh text eol=lf`. ## 6. Rules - The rule file `universal/.md` is in English, starts with `# Rules: …` or `# Code style: …`, says which library version it is written for, and links to the documentation instead of copying it. - First section "How to work": source of truth (installed code, release notes), don't invent APIs, report conflicts. - Keep it short: rules and pitfalls, not explanations. ## 7. Check before publishing In the site repository (Docker container of the site): ```bash php bin/console app:ai:catalog # fails with a clear message on a broken manifest.yaml or an unknown variant folder php bin/console cache:clear ``` Then open `/uk/ai//` and `/en/...`: the card in the catalog, README in both languages, the file list per agent and the install commands. Run the generated install commands in a temporary folder and check that the agent picks the skill up. Commit on a branch and open a pull request — the catalog is published with the next deploy.