# V1 Skilling It

> Use when creating, writing, editing, or improving shared skills for Codex, Claude Code, or other agent runtimes. Triggers on "create a skill", "write a skill", "improve skill", "skill description", "SKILL.md".

- **Type:** Skill
- **Install:** `agentstack add skill-v1-io-v1tamins-v1-skilling-it`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [v1-io](https://agentstack.voostack.com/s/v1-io)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [v1-io](https://github.com/v1-io)
- **Source:** https://github.com/v1-io/v1tamins/tree/main/plugins/v1tamins/skills/v1-skilling-it

## Install

```sh
agentstack add skill-v1-io-v1tamins-v1-skilling-it
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:**

```markdown
---
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

```yaml
# 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

```yaml
# 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

```markdown
# BAD
You should start by reading the file.

# GOOD
Start by reading the file.
```

### 5. Missing Resource References

```markdown
# 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

```markdown
# 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](https://github.com/v1-io)
- **Source:** [v1-io/v1tamins](https://github.com/v1-io/v1tamins)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-v1-io-v1tamins-v1-skilling-it
- Seller: https://agentstack.voostack.com/s/v1-io
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.