AGENTS.md - MetaSkills

MetaSkills version: 1.1.0

Project Overview

MetaSkills owns the user's canonical shared skills, command wrappers, and agent roles, installed into Claude Code, opencode, and Codex user-level configs.

Canonical skills are project-agnostic: resolve facts from the consuming project's AGENTS.md under AGENTS.template.md; stop rather than guess missing facts. Never embed repo slugs, board IDs, branch defaults, environment URLs, cluster/image names, credentials, deployment facts, or local-machine-only paths.

Code Layout & Tech Stack

• skills/<name>/SKILL.md: canonical skills shared across all three harnesses.
• commands/<name>.md: thin same-named skill + $ARGUMENTS handoffs for opencode commands and Codex prompts, never duplicated workflows. Claude Code uses skills directly as slash commands; no wrapper copies.
• agents/opencode/*.md, agents/claude/*.md, agents/codex/*.toml: subagent/role definitions with identical bodies across dialects; configuration syntax differs.
• AGENTS.template.md: required consuming-project contract, including the MetaSkills version and its change list. Bump minor when projects must update their AGENTS.md or issue templates, patch for low-impact changes, major for pride releases.
• sync.ps1, sync.sh: managed harness installers.
• .opencode/skills/: OpenCode-only repository maintenance. Mirror into skills/ only if behavior should install globally.
• skills/paper-doc/: portable document-generation skill with HTML/CSS/JavaScript assets, a native SVG C4 viewer, a Python scaffold, and authoring references. Its paired wrapper is commands/paper-doc.md.
• docs/: GitHub Pages site, published from master /docs. index.html is a self-contained paper-doc workflow guide; each diagram is inline SVG rendered from the PlantUML or draw.io source embedded beside it. It is pinned to the commit in its masthead. Never installed.

Mostly Markdown, TOML, PowerShell, and Bash, plus the paper-doc browser assets and Python scaffold. Keep changes small, explicit, and portable across Windows/Unix.

Update affected surfaces together:

• Skills: canonical skills/<name>/SKILL.md; commands only when handoffs change.
• Roles: all three dialects.
• Installation: both sync scripts, including added/renamed/removed managed files.
• Layout, installation, or workflows: README.md.
• Anything projects must change: AGENTS.template.md version bump and change entry, plus this file's version line.

Build & Validation

No compiled application. Run sync lint first, then inspect and dry-run:

git status --short
git diff --check
.\sync.ps1 -Check
.\sync.ps1 -WhatIf

For Unix-shell changes, also review sync.sh and run when Bash is available:

./sync.sh --check
./sync.sh --dry-run

--check / -Check verifies skill frontmatter (name, description), bidirectional skill/command pairing, three-dialect agent body parity, PowerShell-only shell samples, and em/en dashes. Both scripts must report identical findings.

Run python3 tests/test_installers.py on Linux (bare or container) for isolated installer regression tests. The suite is Bash-only; Windows and PowerShell coverage were removed, and it skips entirely off Linux. Installer tests must cover hard-linked metadata as well as symlinks, and byte-sensitive fixtures must avoid platform newline translation. tests/workflow-scenarios.md contains manual instruction evaluations, not executable behavioral tests.

For paper-doc scaffold or viewer changes, run the dependency-free regressions (Python 3.10+, Node.js 18+):

python tests/test_paper_doc_scaffold.py
node --test tests/test_paper_doc_c4.cjs

Open skills/paper-doc/assets/template/index.html directly using a file URL for browser verification. Check relevant interactions, desktop/mobile layout, and console errors when assets change; use skills/paper-doc/references/c4.md for the diagram contract. Generated documents must remain compatible with direct file opening. Both sync scripts discover the skill directory and paired command automatically and copy all bundled assets.

Read changed skills/agents to verify the project-fact contract and layout invariants above; lint alone does not validate behavior.

DB tripwire files: none. This repository has no database layer or integration database suite.

Project Board

No board documented. Skills needing board owner, project number, or Status option names must stop and ask.

If added, record owner/org, project number, and Status lifecycle here. Look up field/option IDs live with gh project field-list; never record them.

Repositories

• App repo slug: odytrice/metaskills.
• Deployment repo: none.
• Issue template path: none documented. If no template exists, issue workflows should use their fallback headings.

Environments

None. This repository has no running environments.

Branch Map

• master: primary integration branch and PR base unless the user explicitly names another base.

Agent Login

Not applicable. This repository has no running web application, browser login flow, test credentials, or storage-state file.

Review Notes

Prioritize instruction drift and cross-harness parity over style. Enforce the project-fact, wrapper, role, and installer invariants above. Never alter user-level configs except through sync scripts or an explicit user request.