authoring-skills

---
name: authoring-skills
plugin: agent-extension-authoring
description: >-
  Creates, audits and improves agent skills (SKILL.md folders). Use when the user wants to scaffold a new skill (instructional, executable, or stateful), audit or align an existing skill or skill inventory against authoring standards, add a Docker runtime environment or Azure AI Foundry deployment to a skill, set up an MCP server integration (.mcp.json, stdio, sse, or http), or explore the Agent Skills specification and 64-pattern catalog. Not for whole plugins (use authoring-plugins), sub-agents (use authoring-subagents), rules, AGENTS.md or hooks (use authoring-instructions), GitHub workflows (use authoring-github-workflows) or APM packaging (use packaging-with-apm).
argument-hint: "[create|stateful|audit|docker|azure|mcp|standards] [skill-name or path]"
allowed-tools: Bash, Read, Write, Glob, Grep
---

# Authoring Skills (`authoring-skills`)

Scaffolds skills from templates, audits them against `references/skill-authoring-contract.json`, and holds the specifications and pattern catalog the other authoring skills point to.

## Contents

- [Constraints](#constraints) • [Modes](#modes) • [Quick start](#quick-start) • [Workflow](#workflow) • [Verification](#verification) • [References](#references)

## Constraints

1. **Self-contained**: a skill's scripts, references and assets live inside it; no plugin-root hub, symlinks or copy manifest. Other skills are referred to by name.
2. **Lean router**: `SKILL.md` is 100 lines or fewer; detail goes to `references/` linked directly from it, and long references open with a contents list.
3. **Interactive work is a skill**: multi-turn wizards, interview flows and stateful procedures belong in skills playing out in the main thread ([skills-vs-agents-decision-framework.md](references/skills-vs-agents-decision-framework.md)); subagents are strictly for context isolation, tool sandboxing, or adversarial review.
4. **Gerund names**, directory name equals frontmatter `name`, third-person description that says what and when.
5. Audits are read-only; run both `--mode source` and `--mode installed` before declaring a skill compliant.
6. Model names and tiers belong to the `cli-agent` skill.

## Modes

| Mode | Use when | Entry point | Reference |
|---|---|---|---|
| `create` | New skill, instructional or executable | `scripts/scaffold.py` | [create-skill.md](references/modes/create-skill.md) |
| `stateful` | Interactive skill with persistent state | `scripts/scaffold.py` + template | [create-stateful-skill.md](references/modes/create-stateful-skill.md) |
| `audit` | Check or align one skill or an inventory | `scripts/audit_skill.py` | [audit-skill.md](references/modes/audit-skill.md) |
| `docker` | Skill with a Docker runtime | template guidance | [create-docker-skill.md](references/modes/create-docker-skill.md) |
| `azure` | Skill as an Azure AI Foundry hosted agent | `scripts/scaffold_azure_agent.py` | [create-azure-agent.md](references/modes/create-azure-agent.md) |
| `mcp` | MCP server integration | guidance only | [create-mcp-integration.md](references/modes/create-mcp-integration.md) |
| `standards` | Look up the spec, patterns and sources | reference lookup | [ecosystem-standards.md](references/modes/ecosystem-standards.md), [ecosystem-authoritative-sources.md](references/modes/ecosystem-authoritative-sources.md) |

## Quick start

```bash
python3 scripts/scaffold.py --type skill --name <name> --path plugins/<plugin>/skills --desc "<what it does. Use when ...>" [--variant executable]
python3 scripts/audit_skill.py plugins/<plugin>/skills/<name> --mode source
python3 scripts/audit_skill.py plugins/<plugin> --all --mode source --json
```

## Workflow

1. Pick the mode and read its reference before running anything.
2. Create: choose the variant and the observable success contract first, scaffold, then replace generic steps with real knowledge, commands and validation loops; add evals.
3. Audit: run the audit in both modes and fix findings as reviewed edits.
4. For decisions about structure use [pattern-decision-matrix.md](references/pattern-decision-matrix.md) and the [pattern catalog](references/patterns). On failure follow [fallback-tree.md](references/fallback-tree.md).

## Verification

```bash
python3 scripts/audit_skill.py plugins/<plugin>/skills/<name> --mode installed
```

Tests: `python3 -m pytest tests`. Check the mode's section in [acceptance-criteria.md](references/acceptance-criteria.md).

## References

- Modes: [create](references/modes/create-skill.md) • [stateful](references/modes/create-stateful-skill.md) • [audit](references/modes/audit-skill.md) • [docker](references/modes/create-docker-skill.md) • [azure](references/modes/create-azure-agent.md) • [mcp](references/modes/create-mcp-integration.md) • [standards](references/modes/ecosystem-standards.md) • [sources](references/modes/ecosystem-authoritative-sources.md)
- Authoring: [skills-vs-agents-decision-framework.md](references/skills-vs-agents-decision-framework.md) • [skill-authoring-guide.md](references/skill-authoring-guide.md) • [skill-authoring-contract.json](references/skill-authoring-contract.json) • [authoring-acceptance.md](references/authoring-acceptance.md) • [skill-authoring-fallback.md](references/skill-authoring-fallback.md) • [anthropic-skill-authoring-best-practices.md](references/anthropic-skill-authoring-best-practices.md) • [skill-naming.md](references/skill-naming.md) • [discovery-interview.md](references/discovery-interview.md) • [hitl-interaction-design.md](references/hitl-interaction-design.md) • [language-review.md](references/language-review.md) • [review-rubric.md](references/review-rubric.md) • [skill-evaluation-and-testing.md](references/skill-evaluation-and-testing.md) • [skill-creator-schemas.md](references/skill-creator-schemas.md) • [skills-research.md](references/skills-research.md)
- Platform: [platform-primitives.md](references/platform-primitives.md) • [plugins.md](references/plugins.md) • [workflows.md](references/workflows.md) • [tool-usage.md](references/tool-usage.md) • [npx-skills.md](references/npx-skills.md) • [github-prompts.md](references/github-prompts.md) • [index.md](references/index.md)
- MCP and Azure: [authentication.md](references/authentication.md) • [server-types.md](references/server-types.md) • [azure-foundry-agents.md](references/azure-foundry-agents.md) • [stdio-server.json](references/stdio-server.json) • [http-server.json](references/http-server.json) • [sse-server.json](references/sse-server.json)
- Patterns referenced by modes: [client-side-compute-sandbox-constraint.md](references/patterns/client-side-compute-sandbox-constraint.md) • [cyclical-state-propagation-contract.md](references/patterns/cyclical-state-propagation-contract.md) • [persistent-plugin-configuration.md](references/patterns/persistent-plugin-configuration.md)
- Templates: [skill-layout.md](assets/templates/skill-layout.md)
- Gates: [acceptance-criteria.md](references/acceptance-criteria.md) • [fallback-tree.md](references/fallback-tree.md)

• SKILL.md 7 KB
• assets/templates/SKILL-executable.md.jinja 1 KB
• assets/templates/SKILL.md.jinja 1 KB
• assets/templates/execute.py.jinja 1 KB
• assets/templates/skill-layout.md 1 KB
• evals/evals.json 7 KB
• examples/triggering-examples.md 11 KB
• references/acceptance-criteria.md 4 KB
• references/anthropic-skill-authoring-best-practices.md 5 KB
• references/authentication.md 11 KB
• references/authoring-acceptance.md 1 KB
• references/azure-foundry-agents.md 3 KB
• references/discovery-interview.md 2 KB
• references/fallback-tree.md 12 KB
• references/github-prompts.md 3 KB
• references/hitl-interaction-design.md 6 KB
• references/http-server.json 1 KB
• references/index.md 1 KB
• references/language-review.md 3 KB
• references/npx-skills.md 1 KB
• references/pattern-catalog.md 31 KB
• references/pattern-decision-matrix.md 32 KB
• references/platform-primitives.md 2 KB
• references/plugins.md 5 KB
• references/review-rubric.md 2 KB
• references/server-types.md 11 KB
• references/skill-authoring-contract.json 4 KB
• references/skill-authoring-fallback.md 1 KB
• references/skill-authoring-guide.md 3 KB
• references/skill-creator-schemas.md 12 KB
• references/skill-evaluation-and-testing.md 3 KB
• references/skill-naming.md 4 KB
• references/skills-research.md 18 KB
• references/skills-vs-agents-decision-framework.md 10 KB
• references/sse-server.json 1 KB
• references/stdio-server.json 1 KB
• references/tool-usage.md 12 KB
• references/workflows.md 6 KB
• references/diagrams/skill-architecture.mmd 1 KB
• references/diagrams/skill-execution-flow.mmd 1 KB
• references/modes/audit-skill.md 3 KB
• references/modes/create-azure-agent.md 2 KB
• references/modes/create-docker-skill.md 3 KB
• references/modes/create-mcp-integration.md 3 KB
• references/modes/create-skill.md 4 KB
• references/modes/create-stateful-skill.md 3 KB
• references/modes/ecosystem-authoritative-sources.md 3 KB
• references/modes/ecosystem-standards.md 3 KB
• references/patterns/action-forcing-output-with-deadline-attribution.md 1 KB
• references/patterns/adversarial-objectivity-constraint.md 1 KB
• references/patterns/anti-pattern-vaccination.md 1 KB
• references/patterns/anti-symptom-triage.md 1 KB
• references/patterns/artifact-embedded-execution-audit-trail.md 1 KB
• references/patterns/artifact-generation-xss-compliance-gate.md 2 KB
• references/patterns/artifact-lifecycle.md 1 KB
• references/patterns/artifact-state-interrogative-routing.md 2 KB
• references/patterns/asynchronous-benchmark-metric-capture.md 2 KB
• references/patterns/audience-segmented-information-filtering.md 1 KB
• references/patterns/category-calibrated-benchmark-anchoring.md 4 KB
• references/patterns/category-semantic-deferred-tool-binding.md 3 KB
• references/patterns/chained-command-invocation.md 1 KB
• references/patterns/chained-commands.md 1 KB
• references/patterns/client-side-compute-sandbox-constraint.md 2 KB
• references/patterns/complexity-tiered-output.md 1 KB
• references/patterns/conditional-step-inclusion.md 1 KB
• references/patterns/connector-placeholders.md 1 KB
• references/patterns/cyclical-state-propagation-contract.md 3 KB
• references/patterns/delegated-constraint-verification-loop.md 2 KB
• references/patterns/dual-mode-degradation.md 1 KB
• references/patterns/dual-mode-meta-skill.md 1 KB
• references/patterns/dual-register-communication-enforcement.md 2 KB
• references/patterns/dynamic-specification-fetching.md 1 KB
• references/patterns/embedded-deterministic-scoring-formula.md 1 KB
• references/patterns/escalation-taxonomy.md 1 KB
• references/patterns/explicit-seed-anchored-determinism.md 2 KB
• references/patterns/graduated-autonomy.md 1 KB
• references/patterns/graduated-source-attributed-elicitation.md 3 KB
• references/patterns/highly-procedural-fallback-trees.md 2 KB
• references/patterns/iteration-directory-isolation.md 1 KB
• references/patterns/lifecycle-aware-knowledge.md 1 KB
• references/patterns/local-interactive-output-viewer-loop.md 2 KB
• references/patterns/mandatory-counterfactual-scenario-templating.md 1 KB
• references/patterns/mode-invariant-compliance-gate.md 4 KB
• references/patterns/multi-actor-operational-coordination-manifest.md 3 KB
• references/patterns/multi-dimensional-tone.md 1 KB
• references/patterns/multi-modal-routing.md 1 KB
• references/patterns/multi-source-synthesis.md 1 KB
• references/patterns/multi-variant-trigger-optimizer.md 2 KB
• references/patterns/negative-instruction-constraint.md 2 KB
• references/patterns/output-classification.md 1 KB
• references/patterns/passive-style-injection-payload.md 2 KB
• references/patterns/persistent-plugin-configuration.md 1 KB
• references/patterns/population-normative-distribution-constraint.md 3 KB
• references/patterns/pre-committed-rollback-contract.md 1 KB
• references/patterns/pre-execution-input-manifest.md 1 KB
• references/patterns/pre-execution-workflow-commitment-diagram.md 2 KB
• references/patterns/priority-ordered-scanning.md 1 KB
• references/patterns/quantification-enforcement.md 1 KB
• references/patterns/rigorous-benchmarking-loop.md 2 KB
• references/patterns/severity-stratified-output.md 1 KB
• references/patterns/skill-command-two-tier.md 1 KB
• references/patterns/source-authority.md 1 KB
• references/patterns/source-transparency.md 1 KB
• references/patterns/stage-aware-feedback.md 1 KB
• references/patterns/structured-output-contracts.md 1 KB
• references/patterns/sub-action-multiplexing.md 1 KB
• references/patterns/tainted-context-cleanser.md 2 KB
• references/patterns/temporal-anchoring.md 1 KB
• references/patterns/tiered-source-authority.md 1 KB
• references/patterns/trigger-description-optimization-loop.md 2 KB
• references/patterns/ui-degradation-constraint.md 2 KB
• references/patterns/zero-sum-addition-gate.md 1 KB
• scripts/aggregate_benchmark.py 15 KB
• scripts/analyze_scripts.py 12 KB
• scripts/audit_skill.py 28 KB
• scripts/audit_template_compliance.py 16 KB
• scripts/auto_fix_local_links.py 4 KB
• scripts/build_explicit_inventory.py 4 KB
• scripts/check_skill_boundaries.py 9 KB
• scripts/check_skill_lengths.py 4 KB
• scripts/cleanup_stacked_references.py 3 KB
• scripts/execute.py 4 KB
• scripts/fix_descriptions.py 4 KB
• scripts/generate_report.py 12 KB
• scripts/scaffold.py 10 KB
• scripts/scaffold_azure_agent.py 4 KB
• scripts/update_ranked_skills.py 17 KB
• scripts/validate_local_links.py 7 KB
• scripts/benchmarking/improve_description.py 14 KB
• scripts/benchmarking/run_eval.py 13 KB
• scripts/benchmarking/run_loop.py 32 KB
• scripts/benchmarking/utils.py 2 KB
• scripts/eval-viewer/generate_review.py 18 KB
• scripts/eval-viewer/viewer.html 44 KB
• tests/test_audit_skill.py 7 KB
• tests/test_audit_skill_progressive.py 2 KB
• tests/test_authoring_contract.py 8 KB
• tests/test_authoring_installation.py 2 KB
• tests/test_execute.py 2 KB
• tests/test_run_loop.py 5 KB
• tests/test_scaffold_skill.py 4 KB
• tests/test_template_compliance.py 4 KB