300-sf-docs - SKILL.md Agent Skill

name: 300-sf-docs description: "Maintain docs, metadata, and governance-layout compliance." disable-model-invocation: true argument-hint: [file-path | "readme" | "api" | "components" | "audit" | "update" | "metadata" | "migrate-frontmatter" | "migrate-layout" | "technical" | "technical audit" | "editorial" | "editorial audit"]

Canonical Paths

Before resolving any ShipFlow-owned file, load $SHIPFLOW_ROOT/skills/references/canonical-paths.md ($SHIPFLOW_ROOT defaults to $HOME/shipflow). ShipFlow tools, shared references, skill-local references/*, templates, workflow docs, and internal scripts must resolve from $SHIPFLOW_ROOT, not from the project repo where the skill is running. Project source files resolve from the current target path, but project governance artifacts resolve from the canonical governance root. For monorepos, that means the monorepo-root shipflow_data/, not repeated shipflow_data/ directories inside each app/package.

Instruction Layering

Load $SHIPFLOW_ROOT/skills/references/skill-instruction-layering.md before execution. This skill keeps only activation and gate logic locally; detailed doctrine and large mode playbooks are loaded from references.

Chantier Tracking

Trace category: conditionnel. Process role: support-de-chantier.

Before producing the final report, load $SHIPFLOW_ROOT/skills/references/chantier-tracking.md when this run is attached to a spec-first chantier. If exactly one active shipflow_data/workflow/specs/*.md chantier is identified, append the current run to Skill Run History, update Current Chantier Flow when the run changes the chantier state, and include a final Chantier block. If no unique chantier is identified, do not write to any spec; report Chantier: non applicable or Chantier: non trace with the reason.

Report Modes

Before producing the final report, load $SHIPFLOW_ROOT/skills/references/reporting-contract.md.

Default to report=user: concise and outcome-first. Use report=agent for blocked runs, handoff, or explicit verbose request.

Context

Current directory: !pwd
Project CLAUDE.md: !head -80 CLAUDE.md 2>/dev/null || echo "no CLAUDE.md"
Existing README: !head -20 README.md 2>/dev/null || echo "no README.md"
Project structure sample: !find . -maxdepth 3 -type f $ -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.astro" -o -name "*.vue" -o -name "*.py" $ 2>/dev/null | grep -v node_modules | grep -v .git | grep -v dist | sort | head -40

Mode Detection

file path -> FILE MODE
readme -> README MODE
api -> API MODE
components -> COMPONENTS MODE
audit -> AUDIT MODE
update -> UPDATE MODE
metadata or migrate-frontmatter -> METADATA MODE
migrate-layout or layout -> LAYOUT MIGRATION MODE
technical, technical audit, docs/technical -> TECHNICAL DOCS MODE
editorial, editorial audit, docs/editorial -> EDITORIAL GOVERNANCE MODE
empty args -> AUTO MODE

Required References

Always load:

$SHIPFLOW_ROOT/skills/300-sf-docs/references/core-governance.md
$SHIPFLOW_ROOT/skills/300-sf-docs/references/mode-playbooks.md

Load on demand:

$SHIPFLOW_ROOT/skills/references/technical-docs-corpus.md when mode is technical or update touches technical governance.
$SHIPFLOW_ROOT/skills/references/editorial-content-corpus.md when mode is editorial or update touches public-content surfaces.
$SHIPFLOW_ROOT/skills/references/question-contract.md before any user-facing merge/replace/scope/surface question.
$SHIPFLOW_ROOT/skills/references/documentation-freshness-gate.md when documentation depends on current external framework, SDK, provider, runtime, schema, auth, deployment, or API behavior.
$SHIPFLOW_ROOT/skills/references/skill-context-budget.md only when scope touches skills/, skill discovery metadata, or Codex/Claude skill compliance.
$SHIPFLOW_ROOT/shipflow-metadata-migration-guide.md when mode is metadata/migrate-frontmatter.

Execution Contract

Keep internal contracts in English; user-facing output stays in the active user/project language.
Preserve redaction/security rules: never expose secrets, cookies, tokens, private keys, or private logs.
Preserve documentation-update gates: changed behavior must have docs alignment proof or explicit not impacted because ....
Preserve canonical ShipFlow paths and metadata schema rules.
TEST_LOG.md, BUGS.md, PROJECTS.md, and canonical workflow trackers are operational trackers, not frontmatter-required decision artifacts.
When scope touches skills/, skill README files, site/src/content/skills/*.md, or skill discovery metadata, verify skill contract coherence, public skill-page coherence, and runtime skill visibility together. Route non-trivial skill-contract changes through 009-sf-skill-build.
Do not add ShipFlow governance frontmatter to app-rendered runtime content such as site/src/content/skills/*.md.

Stop Conditions

Stop and report blocked when:

required ShipFlow-owned reference is missing and no safe fallback exists
requested migration would overwrite canonical docs without explicit merge decision
metadata lint fails on changed artifacts and cannot be corrected safely
governance conflicts cannot be resolved (for example AGENTS.md not a symlink to AGENT.md)
a skill documentation update changes the public promise or lifecycle route but has no bounded skill-maintenance contract
external behavior is documented without a required fresh-docs checked or explicit fresh-docs not needed verdict

Validation

Run focused checks for touched surfaces:

python3 tools/shipflow_metadata_lint.py <changed-artifacts>
rg -n "Maintenance Rule|Validation|Owned Files|Entrypoints" shipflow_data/technical templates/artifacts/technical_module_context.md
rg -n "Editorial Update Plan|Claim Impact Plan|pending final copy|surface missing|Astro content schema" shipflow_data/editorial docs/editorial
test ! -e AGENTS.md || { test -L AGENTS.md && test "$(readlink AGENTS.md)" = "AGENT.md"; }

When the scope touches skill discovery or skill docs policy:

python3 tools/skill_budget_audit.py --skills-root skills --format markdown
tools/shipflow_sync_skills.sh --check --all
rg -n "Report Modes|Required References|Validation|Stop Conditions" skills/[0-9][0-9][0-9]-*/SKILL.md skills/*/SKILL.md

When the scope touches public skill pages or docs rendered by the site:

npm --prefix site run build