# Skill Writing

> Use when creating or upgrading skills in this repository. Covers repository-specific frontmatter rules, progressive disclosure, reference-file strategy, validation, and the quality bar required for production-grade engineering skills.

- Skill: `peterbamuhigire/skill-writing-3` (Agent Skill, multi-file: 16 files)
- Install (CLI): `npx skillmds@latest add peterbamuhigire/skill-writing-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/peterbamuhigire/skill-writing-3/raw
- Safety review: pending (external: skill-scanner PASS, skillspector WARNING)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools, Security
- Author: peterbamuhigire (https://skillmd.com/u/peterbamuhigire)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/peterbamuhigire/skill-writing-3

---


# Skill Writing

## Inputs

| Input | Source/provider | If absent |
|---|---|---|
| Requested capability, target directory, and neighbouring skills | Requester and live catalogue | Stop drafting and identify the missing scope or neighbours. |
| Local contract, template, validators, and fixtures | Repository | Use the canonical contract only if authorised; mark unavailable gates. |

## Capability Contract

Review and planning default to read-only. Creating or editing skills, references, routers, fixtures, baselines, or CI requires explicit repository authority; deleting or publishing requires separate authority.

## Degraded Mode

Without the live catalogue, validators, or linked references, produce a draft contract and gap list only. Do not claim the skill is routable, linked, or release-ready.

## Decision Rules

| Choice | Action | Failure/risk avoided |
|---|---|---|
| Behaviour selects and executes a distinct workflow | Use a skill entrypoint | Hidden routing contract |
| Content is background or catalogue depth | Use a linked reference | Bloated SKILL.md |
| Description collides with neighbour | Rewrite positive and negative triggers | Wrong activation |

## Evidence Produced

| Category | Artifact | Acceptance condition |
|---|---|---|
| Correctness | Validation and routing record | Structural, link, and expected-route checks pass. |

## Worked Example

For a new source-analysis capability, inspect source-evaluation and source-verification first, define the distinct trigger and stop boundary, then add one positive, one negative, and one collision fixture.
Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, +256 784 464178.

<!-- dual-compat-start -->
## Use When

- Use when creating or upgrading skills in this repository. Covers repository-specific frontmatter rules, progressive disclosure, reference-file strategy, validation, and the quality bar required for production-grade engineering skills.
- The task needs reusable judgment, domain constraints, or a proven workflow rather than ad hoc advice.

## Do Not Use When

- The task is unrelated to `skill-writing` or would be better handled by a more specific companion skill.
- The request only needs a trivial answer and none of this skill's constraints or references materially help.

## Authoring Source Requirements

- Gather relevant project context, constraints, and the concrete problem to solve; load `references, scripts` only as needed.
- Confirm the desired deliverable: design, code, review, migration plan, audit, or documentation.

## Authoring Method Summary

- Read this `SKILL.md` first, then load only the referenced deep-dive files that are necessary for the task.
- Apply the ordered guidance, checklists, and decision rules in this skill instead of cherry-picking isolated snippets.
- Produce the deliverable with assumptions, risks, and follow-up work made explicit when they matter.

## Quality Standards

- Keep outputs execution-oriented, concise, and aligned with the repository's baseline engineering standards.
- Preserve compatibility with existing project conventions unless the skill explicitly requires a stronger standard.
- Prefer deterministic, reviewable steps over vague advice or tool-specific magic.

## Legacy Authoring Warnings

- Treating examples as copy-paste truth without checking fit, constraints, or failure modes.
- Loading every reference file by default instead of using progressive disclosure.

## Initial Authoring Deliverables

- A concrete result that fits the task: implementation guidance, review findings, architecture decisions, templates, or generated artifacts.
- Clear assumptions, tradeoffs, or unresolved gaps when the task cannot be completed from available context alone.
- References used, companion skills, or follow-up actions when they materially improve execution.

## References

- Use the `references/` directory for deep detail after reading the core workflow below.
- Use the `scripts/` directory for repository-native automation before inventing new tooling.
<!-- dual-compat-end -->
Use this skill for repository-native skill authoring. The goal is not to create generic instructional files; it is to encode reusable, high-signal operational knowledge for Claude Code.

## Repository Rules

- Keep `SKILL.md` under 500 lines. Keep deeper markdown references lean and split them when they become hard to load or maintain.
- Use only validator-approved frontmatter keys: `name`, `description`, `license`, `allowed-tools`, `metadata`.
- Make `description` the trigger: what the skill does and when to use it.
- Put deep detail in `references/`; keep `SKILL.md` focused on execution logic.
- Do not add meta-docs inside skills such as `README.md` or `CHANGELOG.md`.

## Authoring Workflow

### 1. Define the Reusable Problem

Create or update a skill only if it captures:

- A repeatable workflow.
- A stable architectural or domain pattern.
- A high-risk area where guardrails materially improve outcomes.

Do not create skills for generic programming knowledge or one-off tasks.

### 2. Choose the Skill Shape

Use one of these structures:

- Workflow skill: step-by-step execution for fragile or sequential work.
- Standards skill: decision rules, checklists, and gates for quality-sensitive domains.
- Domain skill: business concepts, invariants, and recurring implementation patterns.

### 3. Keep the Core Lean

`SKILL.md` should contain:

- Scope and activation clues.
- Ordered workflow or decision logic.
- Non-negotiable standards.
- Short checklists.
- References to deeper files.

Move these to `references/`:

- Large examples
- Review templates
- Detailed schemas
- Long checklists
- Topic-specific deep dives

### 4. Encode Judgment, Not Boilerplate

Good skills tell Claude Code:

- What to prioritize
- What to avoid
- What tradeoffs matter
- What "done" means

Bad skills just restate obvious framework syntax or dump long tutorials.

## Quality Standard

Every skill in this repo should help Claude Code produce outputs that are:

- Production-ready
- Secure by default
- Performance-conscious
- Testable and maintainable
- User-centered
- Explicit about failure handling and operational risk

Use `world-class-engineering` as the baseline when writing engineering skills.

## Frontmatter Standard

Use this template:

```yaml
---
name: skill-name
description: Use when ...
---
```

Guidelines:

- `name` must match the directory name exactly.
- Keep the description direct and specific.
- Front-load the main trigger phrase.
- Avoid filler and marketing language.

## Reference Strategy

If a skill covers multiple subdomains, split references by topic. For example:

- `references/security-gates.md`
- `references/schema-checklist.md`
- `references/review-template.md`

Do not bury important files several levels deep. Link them directly from `SKILL.md`.

## Upgrade Checklist

When improving an existing skill:

- Remove vague or generic advice.
- Add decision rules and release gates.
- Add real failure cases and anti-patterns.
- Tighten the activation description.
- Link to other skills only when the dependency is genuinely useful.
- Re-check line counts after editing.

## Validation

After creating or updating a skill:

1. Run `python -X utf8 skill-writing/scripts/quick_validate.py <skill-dir>` (frontmatter, required sections, dual-compat markers, line limits).
2. Run `python -X utf8 skill-writing/scripts/contract_gate.py --skill <skill-dir>` (Evidence Produced contract from `validation-contract`). Use `--all` to scan the whole repo, `--bundle <path>` to validate a Release Evidence Bundle, and `--strict` to treat warnings as errors.
3. Fix any frontmatter, structure, or contract issues.
4. Sanity-check the skill against a realistic prompt.
5. Ensure the skill still reads cleanly when loaded on its own.

## Authoring Failure Catalogue

- Huge `SKILL.md` files that act like textbooks.
- Trigger descriptions that are too broad to be useful.
- Skills that duplicate existing skills without raising the quality bar.
- Example-heavy files with little operational guidance.
- Instructions that ignore security, performance, testing, or maintainability.

## Companion Skills

- Load `world-class-engineering` when authoring engineering skills.
- Load `skill-safety-audit` before sharing high-impact or security-sensitive skills.

## Workflow

1. Confirm capability, directory, neighbours, and repository rules; stop if scope is ambiguous.
2. Draft neighbour-aware frontmatter and every required contract section.
3. Preserve domain content and extract only deep reference material.
4. Run quick, local, link, line-count, and routing checks.
5. Recover from failures by correcting the named contract and rerunning all gates.

## Outputs

| Artifact | Consumer | Acceptance condition |
|---|---|---|
| Production-ready skill directory | Maintainer and router | Frontmatter, contracts, references, examples, and routing checks pass. |

## Anti-Patterns

- Generic trigger text. Fix: distinguish neighbours.
- Invented decision content. Fix: use domain evidence.
- Missing absent-input behavior. Fix: state stop/recovery.
- Reference dump. Fix: link only required depth.
- Claiming readiness without validation. Fix: run all gates.