V1 Skilling It

Skilling It

Create effective shared agent skills following best practices for discovery, progressive disclosure, and maintainability.

Quick Start

Create a skill in 5 steps:

1. Create directory: repo canonical path plugins/v1tamins/skills/v1-my-skill-name, Codex user-global path ~/.codex/skills/v1-my-skill-name, or Claude Code user-global path ~/.claude/skills/v1-my-skill-name
2. Create SKILL.md with frontmatter (see template below)
3. Write description as triggering conditions ("Use when...")
4. Add instructions in imperative form
5. Validate against the checklist

Minimal template:

---
name: v1-my-skill-name
description: Use when [triggering condition 1], [triggering condition 2]. Triggers on "[phrase 1]", "[phrase 2]".
---

# My Skill Name

## Quick Start
[Fastest path to value]

## Instructions
[Core guidance]

## Examples
[Concrete usage]

When to Use

Create a skill when you have:

• Non-obvious solutions worth preserving
• Workflows that require specific steps
• Domain knowledge the agent wouldn't naturally have
• Reusable patterns across projects

Don't create skills for:

• One-off solutions
• Standard practices well-documented elsewhere
• Project-specific conventions (use CLAUDE.md instead)

Skill Structure

v1-skill-name/
├── SKILL.md              # Required - core instructions (/SKILL.md` as the canonical source for v1tamins. The plugin package is installed directly by Codex and Claude Code through the manifests under `plugins/v1tamins/`.

| Surface | Purpose | Rule |
|---------|---------|------|
| `plugins/v1tamins/skills/v1-/SKILL.md` | Shared source of truth | Edit this first |
| `plugins/v1tamins/skills/v1-/agents/openai.yaml` | Codex UI metadata | Keep short and trigger-oriented |
| `plugins/v1tamins/.codex-plugin/plugin.json` | Codex plugin manifest | Keep `skills` pointed at `./skills/` |
| `plugins/v1tamins/.claude-plugin/plugin.json` | Claude Code plugin manifest | Keep plugin metadata aligned |

After creating or renaming a skill, run:

```bash
scripts/validate-plugin.sh

This verifies frontmatter, plugin skills, manifest metadata, bundled asset references, known skill references, and portable helper paths. scripts/sync-skill-hosts.sh remains only as a legacy compatibility wrapper.

Progressive Disclosure

Skills load in three levels:

| Level | What Loads | When | Size Target | |-------|------------|------|-------------| | 1. Metadata | name + description | Always | ~100 words | | 2. SKILL.md body | Core instructions | Skill triggers | 10k words, include grep patterns in SKILL.md

• Avoid duplication: Information lives in SKILL.md OR references, not both

Scripts (scripts/)

Executable code for deterministic or repetitive tasks.

• When to use: Code that would be rewritten repeatedly
• Benefits: Token-efficient, can execute without loading into context
• Note: May need to be read for patching or environment adjustments

For detailed guidance on writing scripts for skills, see [references/executable-code.md](references/executable-code.md).

Assets (assets/)

Files used in output (not loaded into context).

• When to use: Templates, images, fonts, boilerplate
• Examples: assets/logo.png, assets/template.pptx

Quality Checklist

Structure:

• [ ] SKILL.md exists with valid YAML frontmatter
• [ ] Name is lowercase, hyphens only, max 64 chars
• [ ] Directory name matches frontmatter name, unless using a legacy underscore-prefixed directory
• [ ] SKILL.md under 500 lines (detailed content in references/)
• [ ] References are one level deep from SKILL.md
• [ ] Long reference files (>100 lines) have a TOC

Description:

• [ ] Uses third person ("Use when...")
• [ ] Contains triggering conditions only (NOT workflow summary)
• [ ] Includes specific phrases users would say
• [ ] Under 1024 characters

Invocation posture (v1tamins plugin skills):

• [ ] Side-effectful skills and deliberate rituals the user always summons by name set invocation_posture: explicit_only in agents/openai.yaml plus disable-model-invocation: true in frontmatter; before hiding a skill, check the live routing evals for natural-phrase traffic that would misroute to neighbors
• [ ] v1-menu updated when a skill is added, renamed, removed, or changes posture (validate-plugin.sh fails on menu drift)

Content:

• [ ] Instructions use imperative form (not "you should")
• [ ] Each instruction passes the Instruction Value Gate
• [ ] Consistent terminology throughout (no synonym alternation)
• [ ] Degrees of freedom match task fragility
• [ ] Examples are concrete with real input/output
• [ ] No time-sensitive information
• [ ] References supporting files if they exist
• [ ] No sensitive information, internal URLs, private paths, customer data, or incident-specific identifiers
• [ ] Shared skills pass the public-safe extraction gate

Testing:

• [ ] Skill triggers on expected user queries
• [ ] Instructions are clear and actionable
• [ ] Referenced files exist
• [ ] Tested with real usage scenarios (see [references/iterative-development.md](references/iterative-development.md))
• [ ] scripts/validate-plugin.sh passes

Anti-Patterns

1. Workflow Summary in Description

# BAD: The agent will follow this shortcut instead of reading the full skill
description: Use for TDD - write test first, watch it fail, write minimal code, refactor

2. Everything in SKILL.md

# BAD: 8,000 words in one file
skill-name/
└── SKILL.md  (bloated)

# GOOD: Progressive disclosure
skill-name/
├── SKILL.md  (1,800 words)
└── references/
    ├── patterns.md (2,500 words)
    └── advanced.md (3,700 words)

3. Vague Descriptions

# BAD: Won't trigger correctly
description: Helps with documents

# GOOD: Specific triggers
description: Use when extracting text from PDFs, filling PDF forms, or merging documents. Triggers on "PDF", "form filling", "document extraction".

4. Second Person Instructions

# BAD
You should start by reading the file.

# GOOD
Start by reading the file.

5. Missing Resource References

# BAD: The agent doesn't know references exist
[No mention of references/]

# GOOD: The agent knows where to look
## Reference Files
- **references/patterns.md** - Detailed patterns
- **references/api.md** - API documentation

6. Generic Quality Exhortations

# BAD: Sounds useful but does not change the next action
Be rigorous, careful, and comprehensive.

# GOOD: Defines the action and proof
Before finalizing, compare the output against every requested item. Mark missing items as `[blocked]` with the exact blocker.

Skill Locations

| Location | Purpose | |----------|---------| | plugins/v1tamins/skills/ | Canonical v1tamins plugin skills (committed to git) | | ~/.codex/skills/ | Codex default user-global install path | | ~/.claude/skills/ | Claude Code default user-global install path |

Troubleshooting

Skill doesn't trigger:

1. Check description includes specific phrases users say
2. Verify frontmatter YAML is valid (no tabs, proper indentation)
3. Add more trigger words to description

Multiple skills conflict:

• Make descriptions more distinct
• Use different trigger phrases
• Narrow each skill's scope

Skill too large:

• Move detailed content to references/
• Keep SKILL.md under 500 lines
• Use progressive disclosure

Reference Files

For detailed patterns and extended guidance, see:

• [references/iterative-development.md](references/iterative-development.md) - Agent A/B testing, evaluation-driven development, observing navigation
• [references/discipline-enforcement.md](references/discipline-enforcement.md) - TDD for documentation, rationalization-proofing, gate functions
• [references/executable-code.md](references/executable-code.md) - Script best practices, error handling, MCP tools, dependency management
• [references/public-safe-extraction.md](references/public-safe-extraction.md) - Public-safe framing and privacy scans for shared skills
• [references/diagnosis.md](references/diagnosis.md) - Named failure modes for reviewing skills: no-op, duplication, sediment, sprawl, premature completion, the two loads, leading words, completion criterion
• [references/patterns.md](references/patterns.md) - Reusable body patterns: template, input/output examples, conditional workflow, progress checklist, feedback loop

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: v1-io
• Source: v1-io/v1tamins
• License: MIT

Install and usage instructions live in the source repository linked above.