# Skill Authoring

> Creates and structures SKILL.md files for AI coding agents, including YAML frontmatter, trigger phrases, directive instructions, decision trees, code examples, and verification checklists. Use when the user asks to write a new skill, create a skill file, author agent capabilities, generate skill documentation, or define a skill template for Claude Code agents.

- **Type:** Skill
- **Install:** `agentstack add skill-rohitg00-skillkit-skill-authoring`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [rohitg00](https://agentstack.voostack.com/s/rohitg00)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [rohitg00](https://github.com/rohitg00)
- **Source:** https://github.com/rohitg00/skillkit/tree/main/packages/core/src/methodology/packs/meta/skill-authoring
- **Website:** https://skillkit.sh

## Install

```sh
agentstack add skill-rohitg00-skillkit-skill-authoring
```

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

## About

# Skill Authoring Guide

You are authoring a SKILL.md for an AI coding agent. A well-written skill provides clear, actionable guidance that agents can follow consistently.

## Core Principle

**A skill's description triggers it; the body teaches it.**

The description tells the agent WHEN to use the skill. The content tells the agent HOW to execute it.

## Skill Anatomy

### SKILL.md Structure

```markdown
---
name: [lowercase-hyphenated-name]
description: [Concrete actions + "Use when..." clause]
version: [Semantic version]
triggers:
  - [keyword 1]
  - [keyword 2]
tags:
  - [tag 1]
---

# [Skill Title]

[Introduction paragraph explaining purpose]

## Core Principle

**[Single most important rule in bold]**

## [Main Content Sections]

## [Decision Points]

## [Verification Checklist]
```

### Frontmatter Fields

| Field | Required | Constraints |
|-------|----------|-------------|
| name | Yes | Lowercase alphanumeric + hyphens, 1–64 chars |
| description | Yes | Must include "Use when..." clause; 1–1024 chars |
| version | Yes | Semantic version (e.g. `1.0.0`) |
| triggers | Recommended | Natural-language phrases that activate the skill |
| tags | Recommended | Categorization tags |

## Writing Effective Triggers

Triggers should be phrases users naturally type.

**Good triggers:**
- "write tests first"
- "tdd"
- "test driven development"

**Bad triggers:**
- "testing methodology" (too vague)
- "red-green-refactor-cycle-for-test-driven-development" (too specific)
- "skill-123" (not natural language)

### Trigger Guidelines

1. **Natural language** — How would a human ask for this?
2. **Multiple variations** — Different ways to say the same thing
3. **Specific enough** — Don't trigger on too many queries
4. **Common terms** — Use terms people actually use

## Writing Skill Content

### Voice and Tone

Use **second person, present tense, active voice**:

- ✅ "Write the test first"
- ✅ "You are implementing TDD"
- ❌ "The developer should..." (passive)
- ❌ "It is recommended that..." (wordy)

### Structure Guidelines

1. **Start with context** — What is the agent doing and why
2. **State the core principle** — Most important rule upfront
3. **Provide process** — Step-by-step guidance
4. **Include examples** — Concrete illustrations
5. **Add a checklist** — Verification criteria
6. **End with integration** — How this connects to other skills

### Directive Language

| Strength | Examples |
|----------|----------|
| Strong (critical rules) | "You MUST…", "ALWAYS…", "NEVER…", "Do NOT…" |
| Soft (recommendations) | "Prefer…", "Consider…", "When possible…" |

## Content Patterns

### Decision Trees

```markdown
## Decision: [What to Decide]

If [condition A]:
→ [Action for A]

If [condition B]:
→ [Action for B]

If uncertain:
→ [Default action]
```

### Process Steps

```markdown
### Step 1: [Action]

[Detailed explanation]

**Verification:** [How to know step is complete]

### Step 2: [Action]
...
```

### Code Examples

```typescript
// BAD
const result = doTheThing(badInput);

// GOOD
const validated = validate(input);
const result = doTheThing(validated);
```

## Anti-Patterns to Avoid

| Anti-pattern | Problem | Fix |
|--------------|---------|-----|
| The Encyclopedia | Too much info, agent gets lost | Focus on actionable guidance only |
| The Vague Guide | "Consider best practices" | Be specific: "Use Arrange-Act-Assert" |
| The Constraint-Free Skill | No clear rules, agent improvises | Include explicit constraints |
| The Monologue | Wall of text | Use headers, lists, tables, code blocks |
| The Outdated Skill | References deprecated patterns | Version skills and review periodically |

## Skill Testing

Before publishing, verify:

1. **Trigger test** — Does it activate on expected phrases?
2. **Completeness test** — Can the agent follow it without external info?
3. **Clarity test** — Is every instruction unambiguous?
4. **Contradiction test** — No conflicting guidance?
5. **Edge case test** — Handles unusual situations?

## Pack Organization

Group related skills under a named pack directory. See `PACKS.md` for full pack manifest format and filesystem conventions.

```
packs/
├── testing/
│   ├── pack.json
│   ├── red-green-refactor/
│   │   └── SKILL.md
│   └── test-patterns/
│       └── SKILL.md
```

## Skill Maintenance

See `MAINTENANCE.md` for detailed versioning policy. Quick reference:

**Version increments:**
- **Patch (1.0.x):** Typos, clarifications, minor fixes
- **Minor (1.x.0):** New sections, examples, capabilities
- **Major (x.0.0):** Breaking changes, fundamental rewrites

**Deprecation frontmatter:**

```yaml
deprecated: true
deprecatedReason: "Superseded by skill-v2"
deprecatedSince: "2024-01-15"
```

Add a visible notice at the top of the body: `> **DEPRECATED:** Use [skill-v2] instead.`

## Publication Checklist

Before publishing, confirm:

- [ ] Frontmatter is complete and valid (name, description, version)
- [ ] Description includes concrete actions and a "Use when…" clause
- [ ] Triggers are natural-language phrases, specific but not over-fitted
- [ ] Core principle is clear and prominent
- [ ] Content uses headers, lists, or tables — no walls of text
- [ ] Code examples demonstrate correct vs. incorrect usage
- [ ] Verification criteria are included
- [ ] Related skills are linked where applicable
- [ ] No spelling/grammar errors
- [ ] Tested with target agents against all trigger phrases

## Source & license

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

- **Author:** [rohitg00](https://github.com/rohitg00)
- **Source:** [rohitg00/skillkit](https://github.com/rohitg00/skillkit)
- **License:** Apache-2.0
- **Homepage:** https://skillkit.sh

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-rohitg00-skillkit-skill-authoring
- Seller: https://agentstack.voostack.com/s/rohitg00
- 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%.