# Skill Authoring

> Create, revise, route, validate, or audit tested repo-local skills as a progressive-disclosure engineering handbook. Use when changing AGENTS.md or .codex/skills, adding durable tested contracts, reorganizing routes, synchronizing skill UI metadata, removing placeholders, or checking reachability and routing integrity.

- Skill: `greenpau/skill-authoring-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add greenpau/skill-authoring-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/greenpau/skill-authoring-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: greenpau (https://skillmd.com/u/greenpau)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/greenpau/skill-authoring-2

---


# Skill Authoring

## Inherit the default workflow

Read and apply the installed `$skill-creator` skill completely before changing
a repo-local skill. Apply its naming, initialization, frontmatter, imperative
writing, progressive disclosure, resource selection, UI metadata, validation,
and forward-testing guidance.

Do not initialize an existing skill again. For a new skill, use the installed
initializer once, then replace every placeholder and remove every unused
example or resource directory. Keep repository rules additive; do not weaken
the default skill requirements.

## Author concise engineering contracts

Keep each `SKILL.md` focused on durable, non-obvious knowledge another agent
needs to implement or verify behavior:

- responsibility and exclusions;
- inputs, outputs, state, and lifecycle;
- invariants, ordering, bounds, and decision rules;
- errors, cancellation, partial evidence, cleanup, and recovery;
- security and compatibility boundaries;
- language-neutral acceptance scenarios.

Use imperative or infinitive wording. Keep source-symbol inventories and
session transcripts out of the contract. Prefer observable behavior and
package ownership; mention an algorithm only when compatibility or correctness
depends on it.

Keep detailed variants in a directly linked `references` file only when they
would bloat the body. Keep references one level from `SKILL.md`, explain exactly
when to read each one, and do not duplicate its content in the body. Add scripts
only for repeated deterministic work and test every added script. Add assets
only when they are consumed in repository output.

## Maintain skill metadata

Use a sibling directory named exactly `.codex/skills/<skill-name>`. Use
lowercase letters, digits, and hyphens and keep the name under 64 characters.

Put only `name` and `description` in `SKILL.md` frontmatter. Make the
description state both the capability and concrete trigger conditions because
it controls discovery before the body loads.

Keep `agents/openai.yaml` synchronized with the finished skill:

- derive a human-facing display name from the skill;
- keep the short description concise and aligned with the responsibility;
- make the default prompt explicitly invoke `$<skill-name>` for a representative
  task;
- include no optional interface fields unless they are deliberately supplied.

Regenerate metadata with the installed `$skill-creator` generator when it is
stale. Do not hand-maintain divergent descriptions.

## Build forward-only actionable routing

Store every discoverable skill as a direct sibling under `.codex/skills`.
Express hierarchy only with an actionable Markdown sentence that:

1. starts with the imperative `Use`;
2. links the exact skill name to its relative `SKILL.md`;
3. contains `to` followed by a concrete task or trigger;
4. appears in the narrowest router able to make that decision.

Treat only that complete sentence form as hierarchy. A supporting prose link is
not a route. Do not add parent metadata, ancestry sections, routing-only
backlinks, or a leaf routing section with no delegates.

Keep this canonical topology:

- route only `implementation-architecture`, `skill-authoring`, and
  `source-code-management` from `AGENTS.md`;
- route `coding-directives`, `implementation-test-pipeline`,
  `implementation-coverage`, `implementation-reporting`, and
  `scripts-and-automation` from `implementation-architecture`;
- keep those specialized skills as leaves unless a future cohesive domain
  justifies a forward child.

Ensure every route points forward, every target exists, every action is
selective, every sibling is reachable from `AGENTS.md`, and no cycle exists.
Put shared invariants in the router and specialized behavior in its leaf rather
than copying the same contract into both.

## Revision workflow

1. Read `AGENTS.md`, inventory every sibling skill and `agents/openai.yaml`, and
   follow all current actionable routes.
2. Read the source, tests, raw logs, or user correction that establishes the
   durable behavior. Distinguish required behavior from implementation status.
3. Select the narrowest existing owner. Add a new skill only when loading the
   concern independently improves cohesion or context use.
4. Edit the contract in imperative form. Mark unimplemented or partial behavior
   honestly instead of describing intended automation as present.
5. Add or change one forward actionable route at the narrowest dispatch point.
6. Refresh UI metadata when responsibility or triggering changed.
7. Remove all initializer instructions, unfinished markers, example placeholders,
   unused resources, duplicate guidance, and routing-only backlinks.
8. Run `make skills-check`. Treat this dependency-free repository validator as
   the CI authority for frontmatter, UI metadata, placeholders, exact route
   targets, canonical topology, reachability, and cycle detection. When the
   installed `quick_validate.py` and its YAML dependency are available, run it
   against every changed skill as a supplementary compatibility check.
9. Review the validator's route inventory starting at `AGENTS.md`; resolve any
   missing target, ambiguous action, topology mismatch, cycle, or unreachable
   sibling instead of weakening the check.
10. Report the repository-relative routing chain and every validator result.

## Validation expectations

Treat frontmatter validation as the minimum, not the complete audit. Also
confirm:

- directory and frontmatter names match;
- frontmatter contains only the two allowed fields;
- descriptions contain concrete triggers;
- bodies are imperative, concise, and free of placeholders;
- every `agents/openai.yaml` matches its skill;
- all sibling skills are reachable through the canonical forward graph;
- specialized implementation contracts retain raw-evidence, status,
  incompleteness, security, compatibility, determinism, and verification
  requirements relevant to their owner.

Keep `scripts/skillcheck` standard-library-only and test malformed metadata,
stale prompts, missing targets, cycles, unreachable skills, and unfinished
placeholders. Update its canonical topology expectation in the same change as
an intentional handbook route change.

Forward-test a complex or substantially revised skill with a fresh agent when
that can be done safely. Give it the skill path and a realistic task, not the
intended answer or prior diagnosis, then revise the skill if it cannot guide the
task without leaked context.