Writing Skills

Writing Skills

##Overview

Writing skills IS Test-Driven Development applied to process documentation.

Personal skills may live in agent-specific directories; fssoft catalog skills live in repositories indexed by the registry. This skill focuses on the quality, process, and test discipline of the SKILL.md itself. It does not replace registry publishing guidance.

You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).

Core principle: If you did not watch an agent fail without the skill, you do not know whether the skill teaches the right thing.

REQUIRED BACKGROUND: You MUST understand skills fssoft:test-driven-development before using this skill. That background defines the RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation.

REQUIRED READING: writing-skills/references/anthropic-best-practices.md

Official skill authoring guidance complements the TDD-focused approach here. Use the reference for general Anthropic best practices; use this skill to make those practices testable and production-ready.

##Fssoft Registry Integration

Step 8-11 below cover repository layout and the three publish paths (push / web submit / agent CLI). The standalone skill-authoring skill is deprecated — its content lives here, and scripts/publish-skill.sh is shipped in this repo for backward compatibility.

##Step 0: Dedup Check

Перед созданием нового скилла всегда выполняй dedup. Если скилл дублирует существующий, новый SKILL.md писать нельзя: нужно расширить существующий скилл, сузить область применения или остановиться.

1. Получи живой список каталога:

curl -fsS https://skills.fssoft.ru/api/skills

1. Собери для черновика набор триггеров:

   • слова из будущего description;
   • пользовательские фразы, по которым скилл должен находиться;
   • симптомы проблемы;
   • названия инструментов, API, форматов;
   • явные non-goals.

2. Для каждого существующего скилла собери такой же набор из name, description, tags и, при необходимости, полного skill_md через /api/skills/<name>.

3. Нормализуй наборы:

   • lowercase;
   • убери пунктуацию;
   • сведи русские и английские синонимы вручную, если они означают один триггер;
   • не учитывай слишком общие слова: skill, agent, workflow, documentation, задача.

4. Посчитай Jaccard overlap:

jaccard = |draft_triggers ∩ existing_triggers| / |draft_triggers ∪ existing_triggers|

1. Решение:

1. Зафиксируй вывод в рабочем плане: какие скиллы проверены, где overlap, почему новый скилл всё ещё нужен.

For this writing-skills skill, layout and publishing (formerly skill-authoring) are now part of the same skill (Step 8-11). Quality and verification stay here; the merged content covers layout, the three publish paths, and the agent CLI.

##Step 1-7: Interview

Используй эти вопросы перед написанием или существенной правкой скилла. Не переходи к тексту SKILL.md, пока ответы не получены или явно не выведены из контекста.

###Step 1. Trigger and user language

• Когда агент должен вспомнить этот скилл?
• Какие фразы пользователь реально скажет? На русском? На английском?
• Какие симптомы в задаче должны сработать как триггер?
• Что в description будет сигналом “прочитай полный скилл”, но не перескажет workflow?

###Step 2. Outcome and quality bar

• Как выглядит правильное поведение агента после загрузки скилла?
• Что считается production-ready результатом?
• Какие ошибки недопустимы даже под давлением сроков?
• Какие observable acceptance criteria можно проверить субагентом?

###Step 3. Baseline failure (RED)

• Что агент делает без скилла?
• Какие rationalizations он использует дословно?
• Какие давления ломают поведение: время, авторитет, усталость, sunk cost, “это простая правка”?
• Какие провалы нужно закрыть в тексте, а не в голове автора?

###Step 4. Scope, dedup, and neighboring skills

• Какие существующие скиллы уже решают похожую задачу?
• Что новый скилл делает иначе?
• Где STOP-condition по Jaccard overlap?
• Какой cross-ref нужен вместо копирования чужого workflow?
• Если вопрос про публикацию в fssoft-каталог, не должен ли агент пройти к Step 8-11 ниже (Layout / Push / Web submit / Agent CLI)?

###Step 5. Skill type and asset plan

• Это Technique, Pattern, Reference или Discipline-Enforcing skill?
• Достаточно ли одного SKILL.md, или нужны references/, scripts/, examples/?
• Есть ли heavy reference больше 100 строк, который надо вынести из тела?
• Есть ли reusable tool, который действительно будет запускаться, а не просто украшать каталог?

###Step 6. Structure and CSO

• Какие секции обязательны для понимания?
• Нужен ли flowchart, или markdown/table лучше?
• Какие keywords агент будет искать?
• Какие anti-patterns и red flags должны быть названы явно?
• Где надо поставить **REQUIRED READING:** path, а не force-load ссылку?

###Step 7. Verification and deployment decision

• Какие 3+ pressure scenarios будут прогнаны без скилла и со скиллом?
• Какие субагенты проверят discipline, technique, retrieval, и edge cases?
• Что должно измениться между RED и GREEN?
• Какой loophole найден в REFACTOR и как он закрыт?
• Готов ли SKILL.md к fssoft constraints: frontmatter, размер, assets, dedup, no secrets?

##Step 8: Layout

The fssoft registry discovers skills by non-recursive point lookups, not deep scans. There are exactly three supported layouts. Pick one explicitly.

1. Single skill — SKILL.md at the repo root. Repo == one skill. The simplest option; choose it when the skill stands alone and no second is planned.
2. Monorepo + manifest — multiple skills under skills/<name>/SKILL.md with a root registry.yml that lists paths explicitly. Recommended for a thematic group of skills (example: skills/jira).
3. Monorepo by convention — skills/<name>/SKILL.md without a manifest. The service does one non-recursive listing of skills/ and treats every subfolder containing a SKILL.md as a skill. The skill name is the folder name.

Rule of thumb: one skill → layout 1; two or more → layout 2 (explicit registry.yml is more reliable and self-documenting).

# single skill                  # monorepo
repo/                           repo/
  SKILL.md                        registry.yml
  README.md                       README.md
  (scripts/ references/ …)        skills/
                                    code-review/SKILL.md
                                    pr-summary/SKILL.md

###registry.yml (monorepo only)

The root manifest with explicit paths is the most reliable option:

skills:
  - path: skills/code-review
  - path: skills/pr-summary
  - skills/release-notes        # short string form is also accepted

##Step 9: Push and Verify

The default source of truth is GitLab. For a single-skill repo:

# repo is created in the `skills` group; default branch is main
git init && git checkout -b main
# …place SKILL.md (+ registry.yml for monorepo)…
git add -A && git commit -m "Init <skill>: …"
git remote add origin https://gitlab.fssoft.ru/skills/<repo>.git
git push -u origin main

main is usually protected (push: Maintainers, force push off). Regular commits go through; rewriting history needs Maintainer and a temporary branch-protection lift.

###Verify the catalog saw the skill

New skills appear automatically: background refresh every REFRESH_INTERVAL (default 60s) or near-instantly via a group webhook on push. Check:

curl -fsS https://skills.fssoft.ru/api/skills | jq '.skills[].name'
curl -fsS https://skills.fssoft.ru/api/skills/<name> | jq

User-side install (no GitLab token required):

fs-skills install <name>

##Step 10: Web Submit (no push access)

Steps 8-9 are the "own repo in the skills group + push" path (source of truth in GitLab). If you lack push access to the group or want a quick one-off publication, the same catalog accepts skills through the /submit form without writing to GitLab manually. Any signed-in GitLab user can file a request; on approve the server commits and publishes.

General flow: login → form → request (needs_review) → moderation → approve → skill in the catalog within ~2-3 s. Until approved the request lives only in the queue and is not in the catalog. The form has two tabs — "by folder" and "external by URL".

login (Sign in with GitLab, OIDC)
  → /submit
      tab "Write SKILL.md"  → Pick folder  →  upload a local folder
      tab "Import from URL" → git URL        →  external skill, pinned to SHA
  → Submit for review            (status = needs_review)
  → /moderation: moderator checks SKILL.md/diff → approve
      folder/inline → server commits into the skills group repo (service token)
      external      → materialises the link@SHA into external_skills (nothing written to our GitLab)
  → catalog picks it up within ~2-3 s (refresh/webhook)

###Variant A. By folder (upload a local folder)

The "Write SKILL.md" tab. Either paste a ready SKILL.md in the editor, or click "Pick folder" and select the whole skill folder:

• SKILL.md from the folder is loaded into the editor (with live preview);
• files under scripts/, references/, examples/ are attached as assets;
• everything else (including README.md) is skipped — text only, no binaries;
• "Submit for review" sends the request.

Validation limits (the server re-validates everything; the form is only UX):

On approve the server commits SKILL.md (+ assets) into the community repo in the skills group with its service token — afterwards this is a normal internal skill (source of truth in GitLab, same as Steps 8-9).

###Variant B. External by URL (public GitHub / GitLab)

The "Import from URL" tab — for a skill that already lives in a public repo. The content is not copied into our group: the catalog stores the link, pinned to an immutable commit SHA, and serves it by proxying the source at that SHA.

1. Paste a public URL. Allowed hosts: github.com, gitlab.com, gitlab.fssoft.ru (private external repos are out of scope). Accepted forms:
   • bare repo: https://github.com/owner/repo
   • browse form: …/tree/<ref>/<subpath> or …/blob/<ref>/<path>/SKILL.md
   • for a monorepo, fill the Subpath field (e.g. skills/my-skill).
2. "Resolve & preview" — the server resolves the default branch → pins a commit SHA → fetches SKILL.md (+ assets) at that SHA → shows the preview, the pinned SHA, and a "name already exists" badge if the name is taken.
3. "Submit for review" — on submit the content is re-fetched and re-pinned to exactly the SHA you saw (no race with a moving branch).

On approve the external skill is materialised as a link@SHA in external_skills (nothing is written to our GitLab) and joins the index on equal footing with internal skills. A version bump = a new request with a new SHA → a new review; there is no auto-follow of branches (otherwise approve-then-mutate would return). On install the CLI checks the content_hash of the approved bytes — tamper-evident.

###Which path to choose

Any path produces a normal skill in /api/skills; installation is the same: fs-skills install <name> (see Step 9).

##Step 11: Agent Publish via CLI

This skill is also a tool: an agent that has loaded it can publish a skill to the registry in one command. The bundled scripts/publish-skill.sh commits a skill into the skills group on GitLab, and the registry mirror indexes it within ~2-3 s.

# from the skill folder (has SKILL.md [+ README.md, scripts/, references/, examples/])
GITLAB_TOKEN=glpat-xxx scripts/publish-skill.sh --dir .

# or specify path/name/branch/message explicitly
GITLAB_TOKEN=glpat-xxx scripts/publish-skill.sh \
  --dir ./my-skill --name my-skill --branch main \
  --message "feat(my-skill): initial publish"

What the script does (idempotent — a re-run is an update):

1. reads SKILL.md, validates frontmatter (slug name, presence of description) — same rules as the server;
2. finds or creates a private project skills/<name> (GitLab API);
3. commits SKILL.md + README.md + scripts/ references/ examples/ (git treats create and update uniformly) into the project's default branch;
4. polls https://skills.fssoft.ru/api/skills/<name> until the skill appears.

###Why not /api/submissions

The web form /submit is gated by an interactive GitLab OIDC login (HMAC session cookie + same-origin CSRF guard) — it cannot be hit headlessly from an agent. So an agent / maintainer publishes by writing directly to GitLab with their own token — like a regular git push.

agent + GITLAB_TOKEN ──git push──▶ skills group ──mirror/webhook──▶ /api/skills
                                  (no moderation)

The fs-skills CLI does not support publishing (only list/search/info/install/update/uninstall/installed/download) — skill upload goes through this script or manually (below).

###Requirements and security

• GITLAB_TOKEN — a GitLab PAT with api scope and Developer+ role in the skills group (Maintainer for the script to create the project). The token is never printed; it goes into the push URL as oauth2:$GITLAB_TOKEN.
• A direct push bypasses moderation → this is the path for trusted maintainers with a group token. Untrusted contributors go through the moderated web UI (variant A/B above). Do not place secrets in SKILL.md or scripts — the skill is downloaded into every user's agents.

###Without the script: manual curl + git

NAME=my-skill
HOST=gitlab.fssoft.ru
# 1) create the project in the skills group (namespace_id=659; skip if it already exists)
curl -fsS -X POST -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "https://$HOST/api/v4/projects" \
  -d "name=$NAME&path=$NAME&namespace_id=659&visibility=private"
# 2) push the content
git init && git checkout -b main && git add SKILL.md && \
  git commit -m "feat($NAME): publish" && \
  git push "https://oauth2:$GITLAB_TOKEN@$HOST/skills/$NAME.git" HEAD:main
# 3) verify
curl -fsS "https://skills.fssoft.ru/api/skills/$NAME" | jq .name

Or, fully through the GitLab Commits API (no local git) — POST /projects/:id/repository/commits with an actions array (create/update per file). Convenient for upserting multiple files in one commit.

##Catalog Rules

• Name uniqueness within the group. A name collision means STOP, not "we'll sort it out later". Check curl https://skills.fssoft.ru/api/skills before picking a name.
• No duplicate skills across repos. If the same skill lives in two repos under the same name, the catalog picks one and the other is effectively lost. Deprecate or delete the older repo.
• No secrets. Repos are private, but a published skill is downloaded into every user's agents. Tokens, internal passwords, private URLs must not appear in SKILL.md or any asset.
• Pick the right publishing path. Trusted maintainer with a group token: push directly (Step 9) or publish-skill.sh (Step 11). Anyone else: moderated web UI (Step 10). The web form is intentionally interactive; that is the trust boundary.

##What is a Skill?

A skill is a reference guide for proven techniques, patterns, or tools. Skills help future Claude instances find and apply effective approaches.

Skills are: Reusable techniques, patterns, tools, and reference guides.

Skills are NOT: Narratives about how you solved a problem once.

A good skill is operational. It changes future agent behavior in a repeatable way. If the content only records history, put it in a project note, retrospective, or README instead.

##TDD Mapping for Skills

The entire skill creation process follows RED-GREEN-REFACTOR.

REQUIRED BACKGROUND: skills fssoft:test-driven-development

##When to Create a Skill

Create when:

• Technique was not intuitively obvious to you.
• You would reference this again across projects.
• Pattern applies broadly, not only to one repository.
• Others would benefit.
• The behavior requires judgment that validation alone cannot enforce.
• Future agents are likely to rationalize shortcuts without explicit guidance.

Do not create for:

• One-off solutions.
• Standard practices already well documented elsewhere.
• Project-specific conventions; put those in project instructions instead.
• Mechanical constraints; if enforceable with regex or validation, automate it.
• Publishing instructions — covered by Step 8-11 below, not duplicated here.

Documentation is for judgment calls. Automation is for mechanical constraints. Cross-references are for neighboring expertise.

##Skill Types

###Technique

Concrete method with steps to follow.

Examples: condition-based waiting, root-cause tracing, defensive data migration.

###Pattern

Way of thinking about problems.

Examples: flattening with flags, test invariants, information hiding.

###Reference

API docs, syntax guides, tool documentation.

Examples: command references, library behavior, protocol notes.

###Discipline-Enforcing

Rules that must hold under pressure.

Examples: TDD, verification before completion, designing before coding, no unreviewed production changes.

Discipline skills need the strongest testing because agents will search for loopholes when the user is impatient or the task looks “obvious.”

##Skill Categories

Use categories to choose test strategy, not to decorate the skill.

A skill can combine categories, but one category should dominate. If two categories are equally large, consider separate skills with cross-references.

##Directory Structure

For fssoft catalog submissions, keep the skill directory simple and registry-compatible:

skills/
  writing-skills/
    SKILL.md              # Main reference (required)
    references/           # Heavy text references only when needed
    scripts/              # Reusable executable tools only when needed
    examples/             # Focused examples only when needed

Flat searchable namespace: name is the public identifier. Keep it unique, stable, and kebab-case.

Separate files for:

1. Heavy reference (100+ lines): API docs, comprehensive syntax, long research notes.
2. Reusable tools: scripts, utilities, templates that future agents actually run.
3. Focused examples: substantial examples that would distract from the main skill.

Keep inline:

• principles and concepts;
• quick reference tables;
• short code patterns under about 50 lines;
• decision rules;
• common mistakes and red flags.

Do not create supporting files for decoration. Every file must reduce main-context load or provide reusable value.

##SKILL.md Structure

Frontmatter (YAML): fssoft validation requires SKILL.md to start with a YAML frontmatter block.

Required by registry validation:

• name: slug, lowercase letters, digits, and dashes, 2-63 characters.
• description: required, non-empty, max 4000 characters.
• tags: optional, max 10; registry accepts tags or keywords.

Recommended for fssoft catalog quality:

• license: MIT unless a different license is required.
• version: semantic version string.
• owners: maintainers responsible for the skill.
• metadata.author: original author.
• metadata.version: internal metadata version if useful.
• required_background: cross-referenced prerequisite skills or concepts.

---
name: skill-name-with-hyphens
description: Use when [specific triggering conditions and symptoms]
tags: [domain, behavior, testing]
license: MIT
version: 1.0.0
owners: [redickowii]
required_background:
  - "skills fssoft:test-driven-development"
metadata:
  author: redickowii
  version: "1.0"
---

# Skill Name

## Overview
What is this? Core principle in 1-2 sentences.

## When to Use
Symptoms and trigger conditions.
When NOT to use.

## Core Pattern
Before/after or decision rule.

## Quick Reference
Table or bullets for scanning common operations.

## Implementation
Inline code for simple patterns.
Cross-reference heavy references or reusable tools.

## Common Mistakes
What goes wrong and how to fix it.

## Testing
How this skill was verified.

## Real-World Impact
Concrete results, if known.

The body can be longer than the description. Do not compress the workflow into frontmatter just because it feels convenient.

##Claude Search Optimization

Critical for discovery: future Claude needs to FIND your skill.

###1. Rich Description Field

Purpose: Claude reads description to decide which skills to load for a given task. Make it answer: “Should I read this skill right now?”

Format: Start with “Use when...” to focus on triggering conditions.

CRITICAL: Description = When to Use, NOT What the Skill Does.

The description should ONLY describe triggering conditions. Do NOT summarize the skill's process or workflow in the description.

Why this matters: Testing revealed that when a description summarizes the skill's workflow, Claude may follow the description instead of reading the full skill content. A description saying “code review between tasks” caused Claude to do ONE review, even though the skill body clearly required TWO reviews.

When the description was changed to just “Use when executing implementation plans with independent tasks” (no workflow summary), Claude correctly read the body and followed the full process.

The trap: Descriptions that summarize workflow create a shortcut Claude will take. The skill body becomes documentation Claude skips.

# BAD: Summarizes workflow - Claude may follow this instead of reading skill
description: Use when executing plans - dispatches subagent per task with code review between tasks

# BAD: Too much process detail
description: Use for TDD - write test first, watch it fail, write minimal code, refactor

# GOOD: Just triggering conditions, no workflow summary
description: Use when executing implementation plans with independent tasks in the current session

# GOOD: Triggering conditions only
description: Use when implementing any feature or bugfix, before writing implementation code

Content:

• Use concrete triggers, symptoms, and situations that signal this skill applies.
• Describe the problem, not incidental language-specific symptoms.
• Keep triggers technology-agnostic unless the skill itself is technology-specific.
• If skill is technology-specific, make that explicit in the trigger.
• Write in third person where the runtime injects descriptions into system context.
• NEVER summarize the skill's process or workflow.

# BAD: Too abstract, vague, does not include when to use
description: For async testing

# BAD: First person
description: I can help you with async tests when they are flaky

# BAD: Mentions technology but skill is not technology-specific
description: Use when tests use setTimeout/sleep and are flaky

# GOOD: Starts with "Use when", describes problem, no workflow
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently

# GOOD: Technology-specific skill with explicit trigger
description: Use when using React Router and handling authentication redirects

###2. Keyword Coverage

Use words Claude would search for:

• Error messages: “Hook timed out”, “ENOTEMPTY”, “race condition”.
• Symptoms: “flaky”, “hanging”, “zombie”, “pollution”.
• Synonyms: “timeout/hang/freeze”, “cleanup/teardown/afterEach”.
• Tools: actual commands, library names, file types.
• Russian and English trigger phrases when the target audience is bilingual.

###3. Descriptive Naming

Use active voice, verb-first names when possible:

• Good: creating-skills, not skill-creation.
• Good: condition-based-waiting, not async-test-helpers.
• Good: using-skills, not skill-usage.
• Good: root-cause-tracing, not debugging-techniques.

Gerunds work well for processes: creating-skills, testing-skills, debugging-with-logs.

For fssoft, the public name must be lowercase kebab-case even if the display title uses capitals.

###4. Token Efficiency

Problem: frequently referenced skills may load in many conversations. Every token counts.

Targets:

• Frequently loaded workflow skills: keep them very short or aggressively cross-referenced.
• Regular production skills: include enough detail to change behavior, but move heavy reference out of the body.
• fssoft submission limit: SKILL.md must stay under 64 KB.

Move details to tool help:

# BAD: Document every flag in SKILL.md
search-conversations supports --text, --both, --after DATE, --before DATE, --limit N

# GOOD: Reference --help
search-conversations supports multiple modes and filters. Run --help for details.

Use cross-references:

# GOOD: Reference neighboring section
**SEE ALSO:** Step 8-11 of this skill for fssoft layout and publishing.

Compress examples:

# BAD: Verbose example
Partner: "How did we handle authentication errors in React Router before?"
You: "I'll search past conversations for React Router authentication patterns."
[Dispatch subagent with long query and repeated explanation]

# GOOD: Minimal example
Partner: "How did we handle auth errors in React Router?"
You: Searching...
[Subagent → synthesis]

Eliminate redundancy:

• Do not repeat what is in cross-referenced skills.
• Do not explain what is obvious from command help.
• Do not include multiple examples of the same pattern.
• Do not duplicate skill-authoring publish instructions.

###5. Cross-Referencing Other Skills and Files

Use skill name or asset path only, with explicit requirement markers:

**REQUIRED BACKGROUND:** skills fssoft:test-driven-development
**COMPLEMENTARY SKILL:** skill-authoring
**REQUIRED READING:** writing-skills/references/testing-skills-with-subagents.md

Do not use force-load path syntax. Force-loading burns context before the agent knows whether the file is needed.

Use explicit labels:

• REQUIRED BACKGROUND for prerequisite concepts.
• REQUIRED SUB-SKILL when another skill must be used to complete the task.
• COMPLEMENTARY SKILL when the other skill handles a neighboring workflow.
• REQUIRED READING for supporting files inside this skill.

##Description Field

The description is a trigger, not a miniature skill.

Checklist:

• Starts with Use when.
• Names the user situation, symptoms, or trigger phrases.
• Avoids step lists.
• Avoids “this skill will...” summaries.
• Avoids publishing workflow if the skill is not about publishing.
• Includes Russian trigger language when the audience is Russian-speaking.
• Stays under fssoft's 4000-character validation limit; shorter is better.

Bad fssoft example:

description: Use when writing skills: first do dedup, then interview, then TDD-test with subagents, then publish through GitLab.

This leaks workflow into the discovery field.

Good fssoft example:

description: Use when нужно создать новый скилл, править существующий SKILL.md, проверить перед деплоем через субагентов, или усилить discoverability без дублирования соседних скиллов.

This describes the trigger and makes the body necessary.

##Flowchart Usage

Use flowcharts only when a decision is easy to get wrong.

digraph when_flowchart {
    "Need to show information?" [shape=diamond];
    "Decision where I might go wrong?" [shape=diamond];
    "Use markdown" [shape=box];
    "Small inline flowchart" [shape=box];

    "Need to show information?" -> "Decision where I might go wrong?" [label="yes"];
    "Decision where I might go wrong?" -> "Small inline flowchart" [label="yes"];
    "Decision where I might go wrong?" -> "Use markdown" [label="no"];
}

Use flowcharts ONLY for:

• non-obvious decision points;
• process loops where the agent might stop too early;
• “when to use A vs B” decisions;
• STOP/continue gates such as dedup thresholds.

Never use flowcharts for:

• reference material; use tables or lists;
• code examples; use markdown code blocks;
• linear instructions; use numbered lists;
• labels without semantic meaning such as step1, helper2.

REQUIRED READING: writing-skills/references/graphviz-conventions.dot

REQUIRED READING: writing-skills/scripts/render-graphs.js

Use the render script to visualize a skill's flowcharts for a human reviewer:

writing-skills/scripts/render-graphs.js ../some-skill
writing-skills/scripts/render-graphs.js ../some-skill --combine

##Code Examples

One excellent example beats many mediocre ones.

Choose the most relevant language:

• testing techniques → TypeScript/JavaScript;
• system debugging → Shell/Python;
• data processing → Python;
• registry examples → curl, JSON, YAML, and markdown.

Good example:

• complete and runnable;
• well-commented explaining WHY;
• from a real scenario;
• shows pattern clearly;
• ready to adapt, not a generic template.

Do not:

• implement the same idea in five languages;
• create fill-in-the-blank templates that hide judgment;
• write contrived examples;
• include code that was never tested;
• put large examples inline when examples/ would preserve context.

You are good at porting. One great example is enough.

##File Organization

###Self-Contained Skill

defense-in-depth/
  SKILL.md

Use when all content fits, no heavy reference is needed, and examples are short.

###Skill with Reusable Tool

condition-based-waiting/
  SKILL.md
  scripts/wait-for-condition.ts

Use when the tool is reusable code, not just narrative decoration.

###Skill with Heavy Reference

pptx/
  SKILL.md
  references/pptxgenjs.md
  references/ooxml.md
  scripts/render-preview.js

Use when reference material is too large for inline content.

###Skill with Focused Examples

claude-md-testing/
  SKILL.md
  examples/CLAUDE_MD_TESTING.md

Use when an example is valuable but would interrupt the main flow.

REQUIRED READING: writing-skills/examples/CLAUDE_MD_TESTING.md

##The Iron Law (Same as TDD)

NO SKILL WITHOUT A FAILING TEST FIRST

This applies to NEW skills AND EDITS to existing skills.

Write skill before testing? Delete it. Start over.

Edit skill without testing? Same violation.

No exceptions:

• Not for “simple additions”.
• Not for “just adding a section”.
• Not for “documentation updates”.
• Do not keep untested changes as “reference”.
• Do not adapt while running tests.
• Delete means delete.

REQUIRED BACKGROUND: skills fssoft:test-driven-development explains why this matters. Same principles apply to documentation.

##Testing Skills

Testing proves the skill changes agent behavior. Reading the skill yourself does not count.

REQUIRED READING: writing-skills/references/testing-skills-with-subagents.md

Test at least one scenario without the skill and one with the skill. For discipline skills, combine pressures until the agent is tempted to violate the rule.

Minimum evidence:

• baseline behavior without skill;
• exact failure or rationalization;
• revised skill text addressing that failure;
• verification behavior with skill;
• remaining risks or follow-up loopholes.

##Testing All Skill Types

Different skill types need different test approaches.

###Discipline-Enforcing Skills

Examples: TDD, verification-before-completion, designing-before-coding.

Test with:

• academic questions: does the agent understand the rules?
• pressure scenarios: does the agent comply under stress?
• multiple pressures combined: time + sunk cost + authority + exhaustion;
• rationalization capture and explicit counters.

Success criteria: Agent follows the rule under maximum pressure.

###Technique Skills

Examples: condition-based-waiting, root-cause-tracing, defensive-programming.

Test with:

• application scenarios: can the agent apply the technique correctly?
• variation scenarios: does it handle edge cases?
• missing information tests: do instructions have gaps?

Success criteria: Agent successfully applies the technique to a new scenario.

###Pattern Skills

Examples: reducing complexity, information hiding, invariant thinking.

Test with:

• recognition scenarios: does the agent recognize when the pattern applies?
• application scenarios: can it use the mental model?
• counter-examples: does it know when NOT to apply?

Success criteria: Agent correctly identifies when and how to apply the pattern.

###Reference Skills

Examples: API documentation, command references, library guides.

Test with:

• retrieval scenarios: can the agent find the right information?
• application scenarios: can it use what it found correctly?
• gap testing: are common use cases covered?

Success criteria: Agent finds and correctly applies reference information.

##Common Mistakes

Most bad skills fail in one of five ways:

1. No failing baseline. The author writes what they believe agents need, not what agents actually miss.
2. Description contains workflow. Claude follows the summary and skips the body.
3. Narrative instead of reusable technique. The skill tells a story, but future agents cannot apply it.
4. Duplicate of a neighboring skill. The catalog gets two partial answers instead of one strong answer.
5. No loophole closure. Discipline rules sound strict until pressure appears.

Fix mistakes with TDD: reproduce the failure, write the smallest correction, re-test.

##Common Rationalizations for Skipping Testing

All of these mean: Test before deploying. No exceptions.

##Loophole Closure

Skills that enforce discipline need to resist rationalization. Agents are smart and will find loopholes under pressure.

REQUIRED READING: writing-skills/references/persuasion-principles.md

###Close Every Loophole Explicitly

Do not just state the rule. Forbid specific workarounds.

Bad:

Write code before test? Delete it.

Good:

Write code before test? Delete it. Start over.

**No exceptions:**
- Do not keep it as reference.
- Do not adapt it while writing tests.
- Do not look at it.
- Delete means delete.

###Address Spirit-vs-Letter Arguments

Add foundational principle early:

**Violating the letter of the rules is violating the spirit of the rules.**

This cuts off an entire class of “I am following the spirit” rationalizations.

###Build a Rationalization Table

Capture rationalizations from baseline testing. Every excuse agents make goes in the table:

| Excuse | Reality |
|--------|---------|
| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
| "I'll test after" | Tests passing immediately prove nothing. |
| "Tests after achieve same goals" | Tests-after asks "what does this do?" Tests-first asks "what should this do?" |

###Create Red Flags List

Make it easy for agents to self-check when rationalizing:

## Red Flags - STOP and Start Over

- Code before test.
- "I already manually tested it."
- "Tests after achieve the same purpose."
- "It's about spirit, not ritual."
- "This is different because..."

**All of these mean: Delete code. Start over with TDD.**

###Update CSO for Violation Symptoms

Add violation symptoms to the description when they are triggers, but do not summarize the workflow:

description: Use when implementing any feature or bugfix, before writing implementation code

##Bulletproofing Skills Against Rationalization

Bulletproofing is the refactor phase for documentation.

Use this loop:

1. Run a pressure scenario.
2. Capture the exact loophole.
3. Add a direct countermeasure.
4. Re-run the scenario.
5. Repeat until the agent cannot rationalize the violation.

Do not add generic warnings. Add counters to observed failures.

##The Process

The process is RED-GREEN-REFACTOR applied to SKILL.md.

1. RED: prove the absence of the skill causes a real failure.
2. GREEN: write the smallest skill that fixes that failure.
3. REFACTOR: close newly discovered loopholes without weakening the rule.
4. VERIFY: run a fresh subagent or scenario to avoid training on the previous answer.
5. PACKAGE: apply fssoft constraints and cross-reference publishing guidance instead of duplicating it.

The process is mandatory for new skills and behavior-changing edits.

##RED-GREEN-REFACTOR for Skills

###RED: Write Failing Test (Baseline)

Run pressure scenario with subagent WITHOUT the skill. Document exact behavior:

• What choices did the agent make?
• What rationalizations did it use, verbatim?
• Which pressures triggered violations?
• Which information did it fail to retrieve?

This is “watch the test fail.” You must see what agents naturally do before writing the skill.

###GREEN: Write Minimal Skill

Write the skill that addresses those specific rationalizations. Do not add extra content for hypothetical cases.

Run the same scenarios WITH the skill. The agent should now comply.

###REFACTOR: Close Loopholes

Agent found a new rationalization? Add an explicit counter. Re-test until bulletproof.

REQUIRED READING: writing-skills/references/testing-skills-with-subagents.md

Use the testing methodology reference for:

• writing pressure scenarios;
• pressure types: time, sunk cost, authority, exhaustion;
• plugging holes systematically;
• meta-testing techniques.

##Output Style

When producing a skill draft for a human partner:

• Write the complete SKILL.md, not a summary of what should go in it.
• Keep the final response concise: path, validation results, and any blockers.
• Do not publish automatically unless the user explicitly asks.
• Do not create assets unless the interview established a real need.
• If only one file is requested, modify only that file.
• If a required reference file is missing, keep the cross-reference and report the missing asset as follow-up.
• If validation fails, report the exact field and fix before calling the draft complete.

For fssoft contributions, include enough body detail for production behavior but keep SKILL.md comfortably under 64 KB.

##Working with Claude

Use Claude and subagents as test instruments, not as rubber stamps.

Good testing prompt properties:

• gives a realistic task;
• includes pressure that might trigger shortcut behavior;
• does not reveal the expected answer;
• asks for action, not commentary;
• preserves the transcript of failure or success.

Avoid:

• telling the subagent “make sure you follow TDD” when testing whether the skill teaches TDD;
• summarizing the skill in the test prompt;
• using the same warmed-up agent for all phases;
• accepting “looks good” as verification.

Coordination pattern:

• Main agent writes the hypothesis and test scenarios.
• RED subagent runs without the skill or with the relevant skill unavailable.
• GREEN subagent runs with the skill available.
• Optional reviewer subagent checks clarity, CSO, and loopholes.
• Main agent synthesizes and edits.

When the task is specifically about fssoft publication mechanics, jump to Step 8-11 below — do not re-explain layout or publishing in a new skill.

##Fssoft-specific gotchas

• name — kebab-case slug: lowercase letters, digits, dashes; ^[a-z0-9][a-z0-9-]{1,62}$ (2-63 chars); unique within the skills group. On a name collision the first repo path alphabetically wins — STOP, do not "fix later".
• description required and ≤4000 chars; it is a trigger, never a workflow summary (see CSO).
• Asset limits (full table in Step 10): SKILL.md ≤64 KB; assets only under scripts|references|examples/; ≤256 KB per file; ≤2 MB total; ≤50 files.
• Tags ≤10. Do not copy another skill's full tag set if the skill covers a different area.
• SKILL.md must start with a YAML frontmatter --- … --- block.
• No secrets, tokens, internal passwords, or private URLs in SKILL.md or assets — the skill is downloaded into every user's agent.
• Do not use force-load path syntax for file references; write **REQUIRED READING:** writing-skills/references/file.md.
• Layout and publishing (registry.yml, push, web submit, external SHA, CLI script) live in Step 8-11 above; do not duplicate them into new skills.
• For monorepo skills do not rely on "deep recursive scan"; verify the supported layout in Step 8.
• After publishing, verify /api/skills and /api/skills/<name>; do not re-describe the publish workflow inline.

##Anti-Patterns

###Narrative Example

“In session 2025-10-03, we found empty projectDir caused...”

Why bad: Too specific, not reusable.

###Multi-Language Dilution

example-js.js, example-py.py, example-go.go

Why bad: Mediocre quality and maintenance burden.

###Code in Flowcharts

step1 [label="import fs"];
step2 [label="read file"];

Why bad: Cannot copy-paste, hard to read, wrong medium.

###Generic Labels

helper1, helper2, step3, pattern4

Why bad: Labels should have semantic meaning.

###Duplicate Registry Skill

A new skill repeats skill-authoring because the user said “create skill” and the author did not run Step 0.

Why bad: The catalog becomes noisy and agents choose inconsistently.

###Workflow Description Trap

description contains “do A, then B, then C”.

Why bad: Claude may follow the description instead of reading the body.

##Real-World Impact

Tested skills reduce repeated mistakes because they encode behavior, not just information.

Observed impacts from this approach:

• descriptions that avoid workflow summaries make agents more likely to read the full skill;
• failing baseline tests reveal rationalizations authors did not predict;
• loophole tables turn vague “be disciplined” advice into enforceable behavior;
• dedup checks keep the fssoft catalog searchable and reduce conflicting instructions;
• cross-references preserve context by loading heavy references only when needed.

A skill that changes behavior under pressure is production documentation. A skill that only sounds correct is a liability.

##Minimum Viable Skill

A minimum viable skill is not the shortest possible file. It is the smallest file that passes its behavioral tests.

Must include:

• valid frontmatter with name and trigger-only description;
• clear overview and core principle;
• when to use and when not to use;
• one core pattern or decision rule;
• common mistakes or red flags;
• evidence-driven testing notes or test plan;
• cross-references instead of copied heavy material;
• fssoft-compatible asset plan if assets exist.

Must not include:

• untested rules;
• duplicate workflow from neighboring skills;
• narrative-only history;
• broad examples that dilute the main use case;
• hidden assumptions from the author interview.

If the minimum viable skill cannot pass a subagent scenario, it is not viable.

##STOP: Before Moving to Next Skill

After writing ANY skill, you MUST STOP and complete verification for that skill.

Do NOT:

• create multiple skills in batch without testing each;
• move to the next skill before the current one is verified;
• skip testing because “batching is more efficient”;
• defer dedup until after writing;
• publish and “fix later”.

The deployment checklist below is mandatory for each skill.

Deploying untested skills is deploying untested process code. It violates quality standards.

##Skill Creation Checklist (TDD Adapted)

Create an explicit todo/checklist item for each line below when working on a real skill.

Step 0 - Dedup:

• Fetched GET /api/skills.
• Checked name uniqueness.
• Calculated or manually assessed trigger overlap.
• Stopped or narrowed scope if overlap exceeded threshold.
• Added cross-references to neighboring skills.

RED Phase - Write Failing Test:

• Created pressure scenarios; use 3+ combined pressures for discipline skills.
• Ran scenarios WITHOUT skill.
• Documented baseline behavior verbatim.
• Identified patterns in rationalizations or failures.

GREEN Phase - Write Minimal Skill:

• Name uses lowercase letters, digits, and hyphens only.
• YAML frontmatter contains required name and description.
• Description starts with “Use when...” and includes specific triggers or symptoms.
• Description does not summarize workflow.
• Tags, license, owners, and metadata are filled when appropriate.
• Keywords appear throughout for search.
• Overview states the core principle.
• Skill addresses specific baseline failures found in RED.
• Code is inline OR heavy material is cross-referenced.
• One excellent example exists if examples are needed.
• Ran scenarios WITH skill and verified improved behavior.

REFACTOR Phase - Close Loopholes:

• Identified new rationalizations from testing.
• Added explicit counters for discipline skills.
• Built rationalization table from test iterations.
• Created red flags list where useful.
• Re-tested until bulletproof enough for deployment.

Quality Checks:

• Small flowchart only if decision is non-obvious.
• Quick reference table or scannable bullets.
• Common mistakes section.
• No narrative storytelling as primary content.
• Supporting files only under scripts/, references/, or examples/.
• No force-load path syntax.
• SKILL.md under 64 KB.

Layout (Step 8):

• Picked the right layout: single skill / monorepo+registry.yml / monorepo by convention.
• For monorepo: registry.yml lists every skills/<name>/SKILL.md path.
• README.md lists all skills in the repo with the fs-skills install <name> command.

Deployment:

• Pushed to main (or used web submit variant A/B, or scripts/publish-skill.sh).
• GITLAB_TOKEN has api scope + Developer+ in the skills group (CLI path only).
• Skill appears in /api/skills/<name>; archive is reachable.
• Re-run at least one smoke scenario from installed/catalog version if possible.

##Discovery Workflow

How future Claude finds your skill:

1. Encounters problem: user request or task context contains a trigger.
2. Searches descriptions: matching words and symptoms surface candidate skills.
3. Finds SKILL: description matches without pretending to be the whole workflow.
4. Scans overview: confirms relevance and required background.
5. Reads patterns: quick reference and core rules guide behavior.
6. Loads references: only when REQUIRED READING is needed.
7. Applies and verifies: follows the skill and checks results.

Optimize for this flow. Put searchable terms early and often, but keep the body authoritative.

##The Bottom Line

Creating skills IS TDD for process documentation.

Same Iron Law: no skill without a failing test first.

Same cycle: RED (baseline) → GREEN (write skill) → REFACTOR (close loopholes).

Same benefits: better quality, fewer surprises, bulletproof results.

For fssoft, also add Step 0: dedup against the live catalog; Step 8-11 cover layout and publishing (the old skill-authoring skill has been merged in).

If you follow TDD for code, follow it for skills. It is the same discipline applied to documentation.