Skill Creator — Progressive Disclosure Blueprint

When to Use

• A new Cortex-OS skill is needed to capture repeatable workflows, domain knowledge, or tool integrations.
• An existing skill requires a major revision (schema changes, new resources, governance updates).
• Governance reviews flagged a skill for missing metadata, inconsistent bundling, or outdated resources.
• Multiple teams need a shared template to keep skill authoring consistent across repos.

How to Apply

1. Gather concrete usage examples and stakeholder expectations for the target skill.
2. Map workflows, decide on bundled resources (scripts/references/assets), and run init_skill.py to scaffold.
3. Draft SKILL.md following the blueprint, moving deep reference material into companion files.
4. Execute validation scripts (quick_validate.py, custom lint) and update resources per findings.
5. Package the bundle with package_skill.py, capture Evidence Triplet, and log Local Memory outcomes.

Success Criteria

• SKILL.md metadata is specific, third-person, and aligned with triggering scenarios.
• Required sections (When to Use, How to Apply, Success Criteria, 0–12 blueprint) are complete and actionable.
• Bundled resources are referenced in resources: and validated for existence/no orphans.
• Validation scripts and governance checks pass; evidence is archived under the task directory.
• Local Memory entry records skillUsed: "skill-creator" with effectiveness ≥0.8 and links to the final bundle.

0) Mission Snapshot — What / Why / Where / How / Result

• What: Produce high-quality Cortex-OS skills packaged with progressive disclosure and CI-ready validation artefacts.
• Why: Consistent skills accelerate agent onboarding, reduce hallucinations, and satisfy governance gates.
• Where: Applies to all skills under skills/ (single-file or bundled) and mirrored repositories.
• How: Use the planning workflow, scaffolding scripts, validation utilities, and evidence capture steps documented here.
• Result: Approved skill bundle with documented provenance, ready for inclusion in releases and MCP registry sync.

1) Contract — Inputs → Outputs

Inputs include the skill brief, example scenarios, API/domain documentation, and reviewer assignments. Outputs are a structured skill bundle (SKILL.md + resources), validation logs, evaluation questions, and Local Memory references. The bundle is versioned and linked to governance evidence for audit.

2) Preconditions & Safeguards

• Read .cortex/rules/skills-system-governance.md and confirm coverage expectations.
• Capture at least five usage examples and identify required scripts/references before drafting.
• Ensure vibe check, model/tool health, and SBOM tasks are logged in the task directory.
• Define the North-star acceptance test for the skill's workflows.
• Align with security/compliance requirements (no secrets, brand logs, accessible outputs).

3) Implementation Playbook (RED→GREEN→REFACTOR or analogous phases)

1. Discover (RED): Interview stakeholders, document concrete scenarios, and inventory potential resources. Use anthropic-mcp-builder-reference.md for supplemental guidance.
2. Design & Scaffold (GREEN): Run resources/scripts/init_skill.py to scaffold directories; populate frontmatter and progressive disclosure structure.
3. Bundle Resources: Move reusable scripts, references, and assets into resources/ with concise descriptions.
4. Draft Guidance: Write SKILL.md instructions focusing on workflow steps, decision points, and progressive disclosure hints.
5. Validate & Package (REFACTOR): Execute quick_validate.py, adjust metadata, run tests/evaluations, and archive logs. Package with package_skill.py for distribution.

4) Observability & Telemetry Hooks

• Emit structured logs when scaffolding, validating, and packaging skills (include correlation IDs).
• Track metrics for skill creation throughput and validation pass rate; alert on repeated failures.
• Store evaluation results and inspector transcripts under the task folder for downstream analytics.

5) Safety, Compliance & Governance

• Adhere to RULES_OF_AI: no fabricated telemetry, brand logs included, accessibility respected.
• Validate that scripts avoid destructive defaults and document permissions.
• Ensure references do not include confidential data; scrub PII before bundling.
• Capture reviewer approvals using .cortex/rules/code-review-checklist.md templates.

6) Success Criteria & Acceptance Tests

• Run quick_validate.py and project lint suite; zero blockers remain.
• Evaluate the skill with at least three realistic scenarios; document outcomes in Local Memory.
• Reviewer checklist signed with no unresolved major issues.
• Evidence Triplet stored (red log/pre-validation failure, green log/post-fix pass, mutation/property proof if applicable).

7) Failure Modes & Recovery

• Incomplete metadata: Re-run validation, tighten name/description to trigger correctly.
• Orphaned files: Execute bundle validator to list unreferenced assets; update resources: or remove files.
• Validation failures: Inspect logs under validation/ and rerun after fixes.
• Reviewer conflicts: Record decisions, apply follow-up tasks, and iterate until acceptance.

8) Worked Examples & Snippets

• Use the bundled init_skill.py to scaffold a new skill quickly.
• Reference package_skill.py when preparing archives for registry sync or distribution.
• Review the appended Anthropic reference guide for additional checklists and template text.

9) Memory & Knowledge Integration

• After each skill creation, store a Local Memory entry summarising scope, effectiveness rating, and key learnings.
• Link related memories (e.g., domain-specific policies) using relationship_type_enum: "reinforces" or "depends_on".
• Update json/memory-ids.json in the task directory to maintain memory parity.

10) Lifecycle & Versioning Notes

• Version skill bundles semantically; document changes in SKILL.md and changelog.
• Revisit bundles quarterly to ensure scripts and references stay current.
• Deprecate or supersede skills with a successor bundle when workflows change materially.

11) References & Evidence

• resources/anthropic-mcp-builder-reference.md — extended Anthropic guide mirrored locally.
• resources/scripts/*.py — scaffolding, packaging, and validation helpers.
• Task artefacts: validation logs, evaluation XML, inspector transcripts, Local Memory entries.

12) Schema Gap Checklist

• Update skills-tooling CLI to emit structured output metadata once registry v1 lands.
• Automate Local Memory logging via MCP after skill packaging completes.
• Add lint to enforce third-person descriptions across all skill frontmatter.

See resources/anthropic-mcp-builder-reference.md for the full Anthropic reference guide mirrored under the Apache-2.0 license.