Skill Writing

Skill Writing

Create compact, executable Linux skill contracts that route cleanly and remain useful without optional scripts.

Use When

• Creating a specialist Linux skill or changing an existing skill's trigger, contract, or resources.
• Extracting an entrypoint over 500 lines into directly linked references.
• Adding routing fixtures, acceptance evidence, or a safe degraded mode to a skill.

Do Not Use When

• Executing a Linux administration task; route through linux-sysadmin or the matching specialist.
• Reviewing an already written skill for unsafe instructions only; use skill-safety-audit.
• Changing repository-wide policy without also updating the shared authoring standard and gates.

Required Inputs

Workflow

1. Discover the active catalogue and decide whether an existing skill owns the reusable problem.
2. Define positive, negative, neighbour-collision, limited-capability, and failure-path prompts.
3. Draft the input, output, evidence, capability, degraded-mode, decision, recovery, and acceptance contracts before expanding procedures.
4. Preserve the ## Distro support matrix as the first H2 for every specialist skill; route family differences through common.sh primitives in sk-* guidance.
5. Keep the entrypoint at or below 500 lines. Extract depth to references/, link it directly, and add a parent link to each extracted reference.
6. Run the local validator, routing smoke test, canonical quick validator, canonical engine scanner, link checks, and distro-matrix test.
7. Stop release on any structural or routing finding. Recover by fixing the named contract or by narrowing the trigger; never lower the zero-debt baseline.

Quality Standards

• Keep domain decisions, stop conditions, recovery steps, and observable acceptance in the entrypoint.
• Use only name, description, license, allowed-tools, and metadata frontmatter keys.
• Preserve manual Linux commands as the baseline; scripts are optional accelerators.
• Use British English and evidence-backed examples; qualify anything not executed or observed.

Anti-Patterns

• Copying a generic contract into every skill. Fix: name the actual server evidence, failure, and operator decision.
• Describing only a positive trigger. Fix: distinguish the closest neighbour in Do Not Use When and routing fixtures.
• Claiming a check passed when execution was unavailable. Fix: mark it not assessed and return the narrowest useful result.
• Granting mutation rights to an audit skill. Fix: default audit, analysis, critique, and planning to read-only.
• Keeping a 600-line command catalogue in SKILL.md. Fix: extract it to a linked reference that points back to the parent.
• Naming a runner-specific tool in the portable procedure. Fix: state the required read, search, edit, execute, network, or delegation capability.

Outputs

Evidence Produced

Capability Contract

Read and search are required. Editing is permitted only for an authorised authoring task. Execute repository validators only within the task boundary; network and delegation are optional. Never mutate a server while writing a skill.

Degraded Mode

If editing is unavailable, return a file-specific patch plan. If execution is unavailable, mark every validator and routing check not assessed. If domain evidence is missing, preserve the existing procedure and report the missing decision instead of fabricating it.

Decision Rules

Worked Example

Prompt: "Add guidance for diagnosing slow PostgreSQL queries." Inspect linux-postgresql and linux-perf-profiling; route database query and configuration diagnosis to the former, host-wide bottleneck attribution to the latter, and add a collision fixture that keeps both in the top three for the ambiguous prompt.

References

• Local skill authoring standard
• Skill template
• Engine specification