# Skill Writing

> Authors a new skill - for a skills collection, a project, or your personal setup - gathering requirements including where the skill lives, drafting SKILL.md with enforced conventions, collision-checking the name, and scaffolding an acceptance test plan. Use when the user wants to create, write, or add a skill, or when another skill (codify, retro) hands over a multi-step procedure to capture as a…

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

## Install

```sh
agentstack add skill-bcgen-skills-skill-writing
```

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

## About

# Skill Writing

Author a new skill that meets the authoring conventions the first time —
wherever it lives: a skills collection, a project, or the user's personal
setup. Conventions live in
[references/conventions.md](references/conventions.md)
— read it; it is the same file skill-auditing checks against.

## Step 1 — Gather requirements

Before drafting, establish (ask when unstated — never invent):

- What task or domain does the skill cover?
- The concrete use cases, so the "Use when ..." triggers come from real
  situations, not guesses.
- Where the skill lives: a collection's `skills//`, the project's
  skill directory (`.claude/skills//`; `.agents/skills//` as
  the portable fallback), or the user's global skills directory.
  Recommend from context — an express collection task → the collection; a
  codify/retro handoff of a project procedure → that project; a personal
  workflow → global — and ask one question when unclear.
- Does it need executable scripts (deterministic ops only) or just
  instructions?
- Any reference material or existing skill it relates to.

## Step 2 — Name and collision-check

Propose a name in the right family (gerund for managed-unit tools, short
for standalone acts — see conventions). Then check skills.sh:

```sh
npx skills find ""   # look for an exact @ match
```

An exact collision → report it with its install count and offer
alternatives before continuing. The registry check applies to collection
additions; elsewhere (project or personal), only avoid names already
installed at the destination.

## Step 3 — Draft

Create `SKILL.md` at the destination gathered in Step 1. Draft per
conventions: frontmatter (name == directory, capability + "Use when"
≤1024 chars), body ≤100 lines with detail split into `references/`,
English only, original content, numbered steps. Add scripts only for
deterministic operations.

## Step 4 — Scaffold acceptance

Write `tests//README.md`: scenarios plus mechanical checks
(grep/regex/count/diff) that skill-testing can run. Design these with the
skill, not after — if a rule can't be mechanically checked, either sharpen
the SKILL.md or record it as needing human review. Every destination
keeps the same discipline; place the plan where the destination keeps
tests (default `tests//README.md`, or alongside a personal skill).

## Step 5 — Review and verify

Present the draft and test plan for the user's review. On approval, verify
with the **skill-testing** skill when installed. If skill-testing is not
installed, leave the test plan as a manual checklist and mention the
install option at most once.

## Review checklist

| Check | Requirement |
| --- | --- |
| name == directory | frontmatter matches folder |
| description shape | capability sentence + "Use when ..." ≤1024 chars |
| body length | ≤100 lines; detail in references/ |
| English only | no CJK anywhere |
| triggers | derived from gathered use cases |
| originality | authored here, nothing vendored |
| acceptance | test plan with mechanical checks (default `tests//README.md`) |

## Source & license

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

- **Author:** [BCGen](https://github.com/BCGen)
- **Source:** [BCGen/skills](https://github.com/BCGen/skills)
- **License:** MIT
- **Homepage:** https://skills.sh/BCGen/skills

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-bcgen-skills-skill-writing
- Seller: https://agentstack.voostack.com/s/bcgen
- 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%.