Repo Skill Authoring

Canonical guidance for creating and updating repo-local skills in MetaMask Mobile.

Purpose

Use this standard when the repo needs a reusable agent workflow with stable instructions, validation, or harness shims.

Do not create a skill when one of these is enough:

• AGENTS.md or a narrow tests/AGENTS.md pointer
• Existing product or engineering docs in docs/
• A one-off prompt that does not need to be reused

Create a skill when the work is repeated, fragile, or benefits from a shared workflow across agents.

When To Use This vs Native Skill Creator

Use the native or harness-provided skill-creator guidance for general skill design principles or when creating a skill outside this repository.

Use repo-skill-authoring for any MetaMask Mobile repo-local skill that should live in .agents/skills/, .claude/, or other repo-owned harness folders.

If both apply, use native skill-creator for general design guidance, and use this skill as the source of truth for repository-specific structure, naming, and entrypoints.

Harness Entrypoints

Use these entrypoints:

• Codex skill entrypoint: .agents/skills/repo-skill-authoring/SKILL.md ($repo-skill-authoring)
• Claude skill entrypoint: .claude/skills/repo-skill-authoring/SKILL.md

Repo Skill Shape

Required shape for a repo-local skill:

.agents/skills/<skill-name>/SKILL.md
.agents/skills/<skill-name>/agents/openai.yaml

Optional shape, when the workflow needs it:

.agents/skills/<skill-name>/scripts/
.agents/skills/<skill-name>/references/
.agents/skills/<skill-name>/assets/
.claude/skills/<skill-name>/SKILL.md

Keep .agents/skills/<name>/SKILL.md as the single source of truth. Any harness-specific shim should point directly to it.

Naming And Trigger Rules

• Skill folder names use lowercase letters, digits, and hyphens only.
• The folder name and SKILL.md frontmatter name must match exactly.
• The Codex description must say what the skill does and when to use it.
• Prefer names that describe the reusable workflow, not the implementation detail.
• Keep the skill focused on repo-local conventions that are not already handled by generic guidance.

Agent Execution Standard

For agent implementation and review tasks, follow this workflow:

1. Define the user/problem shape.
   • Write down the jobs the skill should handle.
   • Prefer concrete trigger phrases and in-scope task examples.
2. Split the content deliberately.
   • Put the canonical workflow, conventions, and examples in this SKILL.md.
   • Add scripts/ only when deterministic validation or repeated logic is worth the maintenance cost.
   • Add references/ only when detailed content should be loaded on demand instead of sitting in the skill body.
3. Add the skill entrypoint.
   • Include frontmatter name and description.
   • Keep this file readable by both agents and humans.
4. Add the minimum harness shims required.
   • Add .claude/skills/<name>/SKILL.md when Claude needs a pointer.
   • Point every shim directly back to .agents/skills/<name>/SKILL.md.
5. Sanity check the result.
   • Confirm the skill and any shims all point to the same workflow.

Authoring principle:

• Keep the repo skill as the canonical artifact. Avoid extra pointer layers unless they materially improve discovery or ergonomics.

Required agent response sections:

1. Implementation Checklist
2. Files To Add Or Modify
3. Validation
4. Assumptions

Minimal Examples

Canonical Repo Skill

---
name: topic
description: Create and update the repo-local topic workflow. Use for new skill content or harness shims in this repository.
---

# Topic

## Purpose

Explain when this repo-local skill is needed and when existing repo docs are enough.

## Agent Execution Standard

1. Discover current implementation.
2. Apply repo-specific workflow.
3. Confirm any shims stay aligned.

Claude Skill Shim

---
name: topic
summary: Create or update the repo-local topic workflow.
---

Follow `.agents/skills/topic/SKILL.md`.

agents/openai.yaml

interface:
  display_name: 'Topic'
  short_description: 'Create and validate the repo-local topic workflow.'
  default_prompt: 'Use $topic to create or update the canonical repo-local topic workflow.'