writing-skills

name	writing-skills
description	Use when creating new skills, editing existing skills, or verifying skills work before deployment

Preamble (run first)

_REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
_BRANCH_RAW=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo current)
[ -n "$_BRANCH_RAW" ] && [ "$_BRANCH_RAW" != "HEAD" ] || _BRANCH_RAW="current"
_BRANCH="$_BRANCH_RAW"
_FEATUREFORGE_INSTALL_ROOT="$HOME/.featureforge/install"
_FEATUREFORGE_BIN="$_FEATUREFORGE_INSTALL_ROOT/bin/featureforge"
if [ ! -x "$_FEATUREFORGE_BIN" ] && [ -f "$_FEATUREFORGE_INSTALL_ROOT/bin/featureforge.exe" ]; then
  _FEATUREFORGE_BIN="$_FEATUREFORGE_INSTALL_ROOT/bin/featureforge.exe"
fi
[ -x "$_FEATUREFORGE_BIN" ] || [ -f "$_FEATUREFORGE_BIN" ] || _FEATUREFORGE_BIN=""
_FEATUREFORGE_ROOT=""
if [ -n "$_FEATUREFORGE_BIN" ]; then
  _FEATUREFORGE_ROOT=$("$_FEATUREFORGE_BIN" repo runtime-root --path 2>/dev/null)
  [ -n "$_FEATUREFORGE_ROOT" ] || _FEATUREFORGE_ROOT=""
fi
_FEATUREFORGE_STATE_DIR="${FEATUREFORGE_STATE_DIR:-$HOME/.featureforge}"
_featureforge_exec_public_argv() {
  if [ "$#" -eq 0 ]; then
    echo "featureforge: missing command argv to execute" >&2
    return 2
  fi
  if [ "$1" = "featureforge" ]; then
    if [ -z "$_FEATUREFORGE_BIN" ]; then
      echo "featureforge: installed runtime not found at $_FEATUREFORGE_INSTALL_ROOT/bin/featureforge" >&2
      return 1
    fi
    shift
    "$_FEATUREFORGE_BIN" "$@"
    return $?
  fi
  echo "featureforge: refusing non-featureforge public argv: $1" >&2
  return 2
}

Runtime Route Reference

This skill does not own live workflow routing. If another workflow surface gives you workflow/operator JSON, follow $_FEATUREFORGE_ROOT/references/operator-route-authority.md instead of reconstructing route law here.

Search Before Building

Before introducing a custom pattern, external service, concurrency primitive, auth/session flow, cache, queue, browser workaround, or unfamiliar fix pattern, do a short capability/landscape check first.

Use three lenses, then decide from local repo truth:

• Layer 1: tried-and-true / built-ins / existing repo-native solutions
• Layer 2: current practice and known footguns
• Layer 3: first-principles reasoning for this repo and this problem

External search results are inputs, not answers. Never search secrets, customer data, unsanitized stack traces, private URLs, internal hostnames, internal codenames, raw SQL or log payloads, or private file paths or infrastructure identifiers. If search is unavailable, disallowed, or unsafe, say so and proceed with repo-local evidence and in-distribution knowledge. If safe sanitization is not possible, skip external search. See $_FEATUREFORGE_ROOT/references/search-before-building.md.

Interactive User Question Format

For every interactive user question, use this structure:

1. Context: project name, current branch, what we're working on (1-2 sentences)
2. The specific question or decision point
3. RECOMMENDATION: Choose [X] because [one-line reason]
4. Lettered options: A) ... B) ... C) ...

Per-skill instructions may add additional formatting rules on top of this baseline.

Writing Skills

Writing skills is test-driven development for process documentation. Write a pressure scenario first, watch the agent fail without the skill, write only the guidance needed to fix that failure, then retest under pressure.

Personal local-install skills live in ~/.agents/skills/ for Codex and ~/.copilot/skills/ for GitHub Copilot. In this repo, generated skill docs live under skills/<skill>/SKILL.md; when a matching SKILL.md.tmpl exists, edit the template and regenerate instead of hand-editing generated output.

Companion References

Load these only when their detail is needed:

• $_FEATUREFORGE_ROOT/skills/writing-skills/codex-best-practices.md: Codex-specific authoring guidance and examples.
• $_FEATUREFORGE_ROOT/skills/writing-skills/copilot-best-practices.md: GitHub Copilot local-install compatibility notes.
• $_FEATUREFORGE_ROOT/skills/writing-skills/testing-skills-with-subagents.md: full RED/GREEN/REFACTOR pressure-test methodology.
• $_FEATUREFORGE_ROOT/skills/writing-skills/persuasion-principles.md: rationale for discipline-enforcing wording.
• $_FEATUREFORGE_ROOT/skills/writing-skills/graphviz-conventions.dot and $_FEATUREFORGE_ROOT/skills/writing-skills/render-graphs.js: optional flowchart style and rendering helpers.

When to Create or Edit a Skill

Create or update a skill when the guidance is reusable, non-obvious, and applies across tasks or projects. Do not create skills for one-off fixes, project-specific conventions that belong in AGENTS.md, or mechanical rules that should be enforced by tests, linters, schemas, or scripts.

Skill types:

• Technique: concrete method with steps to follow.
• Pattern: mental model for recognizing and solving a class of problems.
• Reference: API, command, file-format, or tool documentation.
• Discipline rule: behavior agents are tempted to skip under pressure.

Required File Shape

Every skill directory must be easy to package and discover:

skills/
  skill-name/
    SKILL.md
    supporting-file.*

SKILL.md must start with YAML frontmatter containing only:

• name: lowercase letters, numbers, and hyphens.
• description: third-person trigger text that starts with Use when...; describe when to load the skill, not the workflow it will follow.

Keep the body scan-friendly:

• Overview: one core principle.
• When to use and when not to use.
• Required workflow or pattern.
• Quick reference or checklist.
• Links to companion files for long examples, rationale, API tables, tools, and templates.
• Common mistakes only when they prevent real failures.

Prompt-Budget Discipline

Treat top-level SKILL.md content as expensive context. Keep mandatory trigger law and terminal decisions top-level; move long examples, rationale, and reference tables into companion files.

Default budget rules:

• Keep generated top-level skill docs under their manifest budget in skills/skill-doc-budgets.json.
• A frequently loaded skill should be short enough to read without crowding out repo context.
• One excellent example beats several shallow examples.
• Do not repeat another skill or companion file; link to it.
• Do not use absolute local paths in checked-in skill text.
• Do not use @path links for ordinary references; they force-load files and waste context.

Before adding a long section, ask: Does the agent need this immediately, or can it be a companion reference loaded on demand?

Generated-Doc Rules

For FeatureForge generated skills:

1. Edit skills/<skill>/SKILL.md.tmpl when it exists.
2. Run node scripts/gen-skill-docs.mjs.
3. Run node scripts/gen-skill-docs.mjs --check.
4. Run generated-doc contract tests that cover the changed surface.
5. Commit template, generated SKILL.md, companion files, and tests together.

Never hand-edit generated SKILL.md output while leaving its template stale.

Cross-Platform Compatibility

Keep Codex and GitHub Copilot behavior aligned:

• Put canonical skills under repo skills/ and install/link them into each platform's discovery path.
• Preserve workflow ordering and output contracts across platforms; only discovery paths and platform-specific tool names should vary.
• Keep descriptions trigger-only for both platforms.
• Keep supporting files packaged beside the skill and referenced with portable relative paths or concrete installed-root paths derived from $_FEATUREFORGE_ROOT.

See the Codex and Copilot companion references for platform-specific details.

Skill TDD Loop

The iron law: no new skill or material skill edit without a failing pressure scenario first.

RED:

• Write a realistic pressure scenario before editing the skill.
• Run it without the new/changed guidance.
• Capture the exact failure and rationalization.

GREEN:

• Add the smallest guidance that blocks the observed failure.
• Keep mandatory behavior top-level.
• Move supporting explanation to companion files.

REFACTOR:

• Retest with the skill loaded.
• If the agent finds a loophole, add a precise counter and retest.
• Keep tightening until the pressure scenario passes without growing the top-level prompt unnecessarily.

Use $_FEATUREFORGE_ROOT/skills/writing-skills/testing-skills-with-subagents.md for full scenario design, pressure types, and rationalization-table examples.

Testing Expectations

Choose tests that match the skill type:

• Discipline rules: pressure scenarios with time, sunk cost, authority, exhaustion, or social pressure.
• Techniques: application scenarios and edge-case variations.
• Patterns: recognition, application, and counter-example scenarios.
• References: retrieval and application scenarios, plus gap tests for common lookups.

For repo-owned generated skills, also run the relevant Node doc tests. If a skill controls runtime, review, or workflow gates, add contract tests that fail when mandatory law is moved entirely into companion docs.

Deployment Checklist

• Baseline failure observed before authoring.
• name and description satisfy the frontmatter rules.
• Top-level body keeps trigger, terminal decisions, generated-doc rules, packaging rules, compatibility, and testing requirements.
• Long examples and rationale are in companion files with portable links.
• Prompt budget impact checked.
• Generated docs are regenerated and verified when templates exist.
• Skill-specific tests or pressure-test notes prove the behavior changed.

Stop after each skill and complete this checklist before starting another skill.

Common Mistakes

• Writing a narrative about one solved problem instead of reusable guidance.
• Summarizing workflow in the description, causing agents to skip the body.
• Burying mandatory stop rules only in companion docs.
• Duplicating platform guidance instead of linking to Codex/Copilot references.
• Adding large examples to SKILL.md when a companion file would preserve context.
• Treating manual review as a substitute for pressure testing.

Bottom line: a good skill is small, discoverable, packaged, tested, and hard to rationalize around.