diff --git a/.agents/skills/legibility--enhancer/SKILL.md b/.agents/skills/legibility--enhancer/SKILL.md index 01f255a..d4df0ac 100644 --- a/.agents/skills/legibility--enhancer/SKILL.md +++ b/.agents/skills/legibility--enhancer/SKILL.md @@ -1,6 +1,6 @@ --- name: legibility--enhancer -description: Collaboratively walks a human through creating high-quality AGENTS.md files throughout a codebase, implementing progressive disclosure architecture. Use when creating or updating AGENTS.md files, onboarding a repository to agent-first practices, or remediating findings from legibility--auditor. Do not use when evaluating existing documentation coverage (use legibility--auditor) or when creating agent skills (use meta--skill-creator). +description: Collaboratively walks a human through creating high-quality AGENTS.md files throughout a codebase, implementing progressive disclosure architecture. Use when creating or updating AGENTS.md files, onboarding a repository to agent-first practices, or remediating findings from legibility--auditor. Do not use when evaluating existing documentation coverage (use legibility--auditor) or when creating agent skills (follow `docs/skill-development.md` instead). --- # Legibility Enhancer diff --git a/.agents/skills/meta--onboarding/SKILL.md b/.agents/skills/meta--onboarding/SKILL.md index a6b093f..3c5ce16 100644 --- a/.agents/skills/meta--onboarding/SKILL.md +++ b/.agents/skills/meta--onboarding/SKILL.md @@ -388,7 +388,8 @@ Once the onboarding outcomes are proven, these ongoing skills become more useful | `autonomy--sre-agent` | When investigating production issues, errors, or incidents | | `legibility--auditor` | Quarterly, to audit documentation coverage as the codebase evolves | | `autonomy--test-readiness-auditor` | When test infrastructure changes or new modules are added | -| `meta--skill-creator` | When you need to create new project-specific skills | + +If the team later needs project-specific skills, treat that as follow-on library maintenance rather than part of the six-outcome proof loop. Use `docs/skill-development.md` as the canonical guide for authoring or revising those skills. ### Recommended Cadence diff --git a/.agents/skills/meta--skill-creator/SKILL.md b/.agents/skills/meta--skill-creator/SKILL.md deleted file mode 100644 index 03e9aa3..0000000 --- a/.agents/skills/meta--skill-creator/SKILL.md +++ /dev/null @@ -1,313 +0,0 @@ ---- -name: meta--skill-creator -description: Best practices and template for creating new agent skills in the code-mint framework. Use when creating a new skill, authoring SKILL.md files, or structuring skill directories. Do not use when editing an existing skill's logic (edit directly instead) or when creating AGENTS.md files (use legibility--enhancer). ---- - -# Skill Creator - -Create new skills that follow code-mint conventions. This skill guides you through the full lifecycle: gathering requirements, writing the SKILL.md, creating reference files, and verifying the result. - -## External Reference - -For broader skill-authoring guidance, see Anthropic's `skill-creator`: -https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md - -Use the general lessons from that guide, but prefer code-mint conventions over product-specific tooling or Claude-only mechanics. - -## Step 1: Gather Requirements - -Before writing anything, extract what you can from the current conversation, existing files, and any examples the user already gave you. Ask only for the missing pieces. - -Then answer these questions: - -1. **Category:** Which category does this skill belong to? - - `meta--` — Onboarding and skill-library management (including authoring new skills) - - `autonomy--` — Agent independence (env, runtime, test readiness, SRE tooling) - - `legibility--` — Codebase understandability - - `clarity--` — Collaborative planning and high-quality executable tickets (post-core onboarding) - -2. **Purpose:** What specific task does this skill perform? - -3. **Trigger scenarios:** When should an agent invoke this skill? When should it NOT? - -4. **Auditor or Creator?** If this is part of a pair: - - Auditors evaluate and produce a report to `.agents/reports/{name}-audit.md` - - Creators consume an auditor report and remediate findings - - See the Auditor/Creator Pattern section below - -5. **Output:** What artifact does this skill produce? (report, code changes, documentation, etc.) - -6. **Domain knowledge:** What does the agent need to know that it wouldn't already know? - -7. **Customization needs:** Which project-local facts belong in explicit `[CUSTOMIZE]` blocks, and which instructions should remain fully reusable? - -8. **Validation style:** Should this skill be validated with objective checks, human review, or both? - -9. **Existing asset reuse:** Is this a new skill, or should it preserve and improve an existing skill's name, structure, and reference files? - -### Discovery Rules - -- Infer purpose, triggers, outputs, and constraints from conversation context before interviewing the user. -- Ask about edge cases, failure modes, and competing trigger scenarios early enough to avoid rewriting later. -- Prefer realistic user phrasing over abstract examples when discussing how the skill should be invoked. -- If the user wants to improve an existing skill, preserve the skill name unless they explicitly want a rename. - ---- - -## Step 2: Create the Directory - -``` -.agents/skills/{category}--{skill-name}/ -├── SKILL.md # Required -└── references/ # Optional — only if needed - └── detailed-guide.md -``` - -**Naming rules:** -- Lowercase letters, numbers, and hyphens only -- Max 64 characters total -- Double-hyphen `--` separates category from skill name -- Use descriptive names: `autonomy--env-auditor` not `autonomy--env` - ---- - -## Step 3: Write the SKILL.md - -### Frontmatter - -```yaml ---- -name: {category}--{skill-name} -description: {What this skill does}. Use when {trigger scenarios}. Do not use when {negative examples}. ---- -``` - -**Description rules:** -- Max 1024 characters -- Write in third person ("Evaluates...", "Creates...", not "I evaluate..." or "You can use this to...") -- Include both WHAT (capabilities) and WHEN (triggers) -- Include at least one "Do not use when" clause -- Be specific enough that the agent can distinguish this skill from similar ones -- Put trigger guidance in the description, not scattered through the body - -### Body Structure - -Follow this skeleton. Omit sections that don't apply. - -```markdown -# {Skill Title} - -{One-sentence summary of what this skill does and why.} - -## Step 1: {First Action} -{Instructions} - -## Step 2: {Next Action} -{Instructions} - -## Output -{What artifact is produced and where it goes} - -## Detailed Criteria -Link to a real file under `references/` (for example `references/readiness-checklist.md`). Do not use placeholder markdown links that resolve to non-existent paths. -``` - -**Body rules:** -- Under 500 lines -- Use numbered steps for sequential workflows -- Use checklists (`- [ ]`) for evaluation criteria -- Provide exact commands where possible (agents should be able to copy-paste) -- State assumptions rather than asking questions (anti-pedantry rule) -- One term per concept throughout — no mixing "endpoint" / "route" / "URL" -- If the skill needs project-local facts, isolate them in explicit `[CUSTOMIZE]` blocks -- Prefer explaining why an instruction matters over piling on rigid MUST/NEVER language -- If repeated examples imply the same deterministic helper, promote it into `scripts/` or `references/` instead of making the agent reinvent it each run - ---- - -## Step 4: Draft Usage Tests - -Before finalizing the skill, draft a small set of realistic prompts: - -1. **Trigger prompts (2-3):** prompts a real user would say when this skill should fire -2. **Near-miss prompts (1-2):** prompts that share vocabulary or context but should NOT trigger this skill -3. **Edge-case prompts (optional):** prompts that stress the fragile parts of the workflow - -Use these prompts to review: - -- whether the description is specific enough to trigger in the right situations -- whether the instructions handle realistic user phrasing rather than only tidy examples -- whether the skill is overfit to one example instead of a reusable pattern - -### Validation Guidance - -- For objective skills, define what artifact, command result, or pass/fail signal would prove the skill works. -- For subjective skills, prefer human review with concrete example outputs over fake precision. -- Do not force a rigid scoring system onto skills whose quality depends mostly on judgment. - ---- - -## Step 5: Write Reference Files (If Needed) - -Move detailed content to `references/` when: -- The SKILL.md would exceed 500 lines without it -- The content is a detailed checklist, scoring rubric, or template -- The content is only needed for specific sub-tasks within the skill - -**Reference file rules:** -- Keep references one level deep (`SKILL.md` links to `references/`; avoid chains where one reference links to another). -- **Exception:** Linking to another skill’s `references/` file is allowed when sharing one canonical guide (for example the runtime creator linking to the runtime auditor’s smoke-test guide). Prefer a single home for shared content. -- Each reference file should be self-contained. -- Name files descriptively: `testing-standards.md`, `readiness-checklist.md`, `ticket-formats.md` - ---- - -## Step 6: Verify - -Run through this checklist before finalizing: - -- [ ] Name is `{category}--{skill-name}`, lowercase/hyphens only, under 64 chars -- [ ] Description includes WHAT, WHEN, and at least one DO NOT USE WHEN -- [ ] Description is under 1024 characters -- [ ] SKILL.md body is under 500 lines -- [ ] Instructions use consistent terminology throughout -- [ ] Sequential workflows use numbered steps -- [ ] Commands are exact and copy-pasteable -- [ ] Reference files (if any) follow the depth rules above (including the cross-skill exception when applicable) -- [ ] If this is an auditor: output report path is `.agents/reports/{name}-audit.md` -- [ ] If this is a creator: reads from `.agents/reports/{auditor-name}-audit.md` and archives after completion -- [ ] Report instructions mention that `.agents/reports/` stays in Git via `.gitkeep`, while generated report files are ignored by `.gitignore` -- [ ] Project-local facts are isolated in `[CUSTOMIZE]` blocks rather than scattered through the file -- [ ] You have at least one explicit invocation prompt, one implicit trigger prompt, and one negative-control prompt for this skill -- [ ] The skill has been reviewed against 2-3 realistic user prompts, not just tidy examples -- [ ] The description has been checked against near-miss prompts that should not trigger it -- [ ] The instructions explain key reasoning where that improves generalization -- [ ] Repeated deterministic work has been promoted into `scripts/` or `references/` where appropriate -- [ ] If improving an existing skill, the current name and reusable assets have been preserved unless the user approved a rename - ---- - -## Step 7: Iterate - -Good skills are usually discovered through a small feedback loop, not written perfectly in one pass. - -Use this cycle: - -1. Draft the skill structure and description. -2. Review it against realistic trigger and near-miss prompts. -3. Check whether the instructions solve a reusable pattern rather than one narrow example. -4. Revise based on feedback, missing edge cases, or confusing trigger behavior. -5. Repeat until the skill is clear, lean, and reliable. - -### Iteration Rules - -- Generalize from feedback instead of hard-coding one example's quirks. -- Remove instructions that are not pulling their weight. -- Watch for repeated helper logic across examples; bundle it once rather than regenerating it repeatedly. -- If the user prefers a lightweight collaborative pass instead of formal evaluation, keep the loop conversational but still test the skill against realistic prompts. - ---- - -## Auditor/Creator Pattern - -When creating a paired auditor and creator: - -### Auditor Skills - -- Evaluate the current state against defined criteria -- Produce a structured report at `.agents/reports/{skill-name}-audit.md` -- Report format: Summary, itemized findings with severity (Critical/High/Medium/Low), recommended actions -- Include: `Next Skill / Step` -- End with: "Run `{creator-skill-name}` to remediate findings." -- Update `docs/onboarding-checklist.md` and `.agents/code-mint-status.json` with the relevant outcome status and date after completion. Optionally refresh `docs/skills-status.md` if the repository keeps the compatibility view. - -### Creator Skills - -- Begin by reading the auditor report from `.agents/reports/{auditor-name}-audit.md` -- If no report exists, instruct the user to run the auditor first -- Walk through findings collaboratively with the user (do not auto-generate without human input where domain knowledge is required) -- Add approval checkpoints before any supervised, destructive, or hard-to-reverse action -- After remediation, archive the report to `.agents/reports/completed/{name}-audit-{YYYY-MM-DD}.md` -- Update `docs/onboarding-checklist.md` and `.agents/code-mint-status.json` with the relevant outcome status and date after completion. Optionally refresh `docs/skills-status.md` if the repository keeps the compatibility view. - ---- - -## Common Patterns - -### Evaluation Pattern (Auditors) - -```markdown -## Step 1: Discover -{Gather facts about the current state} - -## Step 2: Evaluate -{Check against criteria} - -## Step 3: Score/Report -{Produce structured output} -``` - -### Remediation Pattern (Creators) - -```markdown -## Step 1: Read Audit Report -{Load findings from .agents/reports/} - -## Step 2: Prioritize -{Order findings by severity} - -## Step 3: Remediate -{Walk through each finding with the user} - -## Step 4: Verify -{Confirm fixes address findings} - -## Step 5: Archive -{Move report to completed/} -``` - -### Customization Pattern - -```markdown -## Project-Local Customization - -Fill these `[CUSTOMIZE]` blocks collaboratively with the user: - -- [CUSTOMIZE: project-local fact] -- [CUSTOMIZE: project-local fact] -``` - -### Workflow Pattern (Investigation And Clarity Skills) - -```markdown -## Step 1: Gather Context -{Collect evidence} - -## Step 2: Analyze -{Form hypotheses or triage} - -## Step 3: Execute -{Take action} - -## Step 4: Verify -{Confirm the action succeeded} -``` - -### Improvement Pattern (Existing Skills) - -```markdown -## Step 1: Read Current Skill -{Understand the current purpose, triggers, and assets before editing} - -## Step 2: Preserve Stable Identity -{Keep the skill name and reusable structure unless a rename is explicitly approved} - -## Step 3: Test Against Real Prompts -{Use realistic trigger and near-miss prompts to find confusion or gaps} - -## Step 4: Revise -{Improve the description, instructions, scripts, or references} - -## Step 5: Re-verify -{Confirm the revised skill is clearer, leaner, and less overfit} -``` diff --git a/.agents/skills/meta--skill-creator/references/skill-template.md b/.agents/skills/meta--skill-creator/references/skill-template.md deleted file mode 100644 index 9643bb9..0000000 --- a/.agents/skills/meta--skill-creator/references/skill-template.md +++ /dev/null @@ -1,105 +0,0 @@ -# Skill Template - -Copy this template when creating a new skill. Replace all `{PLACEHOLDER}` values. - ---- - -## SKILL.md Template - -```markdown ---- -name: {category}--{skill-name} -description: {What this skill does in one sentence}. Use when {specific trigger scenarios}. Do not use when {negative examples — when NOT to use this skill}. ---- - -# {Skill Title} - -{One-sentence summary of purpose.} - -## Step 1: {First Action} - -{Clear instructions. Use numbered sub-steps for complex procedures.} - -1. {Sub-step} -2. {Sub-step} - -## Step 2: {Next Action} - -{Instructions. Include exact commands where applicable:} - -```bash -{exact command the agent should run} -``` - -## Project-Local Customization - -Fill these `[CUSTOMIZE]` blocks collaboratively when the skill needs project-specific facts: - -- [CUSTOMIZE: project-local fact] -- [CUSTOMIZE: project-local fact] - -## Step 3: {Evaluation or Verification} - -Check against these criteria: - -- [ ] {Criterion 1} -- [ ] {Criterion 2} -- [ ] {Criterion 3} - -## Output - -{Describe what artifact this skill produces and where it goes.} - -{For auditors:} -Write the report to `.agents/reports/{skill-name}-audit.md` using the format defined in `docs/skill-development.md`. - -Ensure the report directory exists: `mkdir -p .agents/reports/completed && touch .agents/reports/.gitkeep .agents/reports/completed/.gitkeep` - -Ensure `.gitignore` ignores generated report contents while preserving the directories with their `.gitkeep` files. - -Include `Next Skill / Step`. - -{For creators:} -Read the audit report from `.agents/reports/{auditor-name}-audit.md`. After remediation, archive to `.agents/reports/completed/`. -Add approval checkpoints before destructive or hard-to-reverse actions. - -## Detailed Criteria - -Link to a real file under `references/` (for example `references/readiness-checklist.md`) for {description of what the reference contains}. Replace the filename with your actual reference; avoid placeholder links that break link checkers. -``` - -Create a minimal prompt test set alongside the skill: - -- Explicit invocation prompt -- Implicit trigger prompt -- Negative-control prompt - ---- - -## Directory Structure Template - -``` -.agents/skills/{category}--{skill-name}/ -├── SKILL.md -└── references/ # Include only if SKILL.md would exceed 500 lines - └── {descriptive-name}.md -``` - ---- - -## Description Examples - -**Auditor:** -```yaml -description: Audit whether a repository's environment variable configuration allows an agent to load all required .env variables from scratch. Use when evaluating a new repository's agent-readiness or when environment loading fails during agent setup. Do not use when .env files already load correctly and the goal is to add new individual variables. -``` - -**Creator:** -```yaml -description: Create the capacity for an agent to load all environment variables from scratch, based on the output of autonomy--env-auditor. Use when an env audit report exists and environment loading needs to be remediated. Do not use when no audit report exists (run autonomy--env-auditor first) or when the goal is debugging a single missing variable. -``` - -**Autonomy (operational investigation):** -```yaml -description: Structured root-cause analysis workflow for investigating active or historical infrastructure issues, runtime errors, and unexpected behavior. Use when encountering a runtime error, production incident, test failure, or investigating a bug report. Do not use when the issue is a known feature request or cosmetic change. -``` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 12be9c5..05d52ff 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,7 +25,7 @@ Thank you for your interest in improving code-mint. This document explains how t ## Skill Development -See `docs/skill-development.md` for the full guide on creating and maintaining skills, including the auditor/creator pattern, frontmatter format, and validation expectations. +See `docs/skill-development.md` for the canonical guide on creating and maintaining skills, including the auditor/creator pattern, frontmatter format, validation expectations, and how to revise existing skills without creating overlap. ## Documentation change checklist (maintainers) diff --git a/docs/README.md b/docs/README.md index 88afe00..e78fe7c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,6 +9,6 @@ These files support the code-mint onboarding framework. Read them in this order: | [`adoption-guide.md`](adoption-guide.md) | Detailed operator workflow | When you need step-by-step onboarding guidance | | [`framework.md`](framework.md) | Founding principles and mechanical standards | When you need the conceptual foundation | | [`skills-status.md`](skills-status.md) | Skill-to-outcome compatibility matrix | When you need a skill-level activity view | -| [`skill-development.md`](skill-development.md) | How to create and maintain skills | When contributing new skills | +| [`skill-development.md`](skill-development.md) | Canonical guide for creating and maintaining skills | When contributing new skills or revising existing ones | The root [`README.md`](../README.md) is the primary entry point. Start there if you have not read it yet. diff --git a/docs/skill-development.md b/docs/skill-development.md index f7691a9..a2371b2 100644 --- a/docs/skill-development.md +++ b/docs/skill-development.md @@ -87,6 +87,24 @@ Helps with environment variables. --- +## Drafting A Skill + +Before writing a new skill, infer as much as you can from the current conversation, repository state, and existing examples. Ask only for the project facts the codebase cannot reveal confidently. + +Capture these decisions before you draft: + +1. **Category:** which family the skill belongs to (`meta--`, `autonomy--`, `legibility--`, or `clarity--`) +2. **Purpose:** the concrete task the skill performs +3. **Trigger boundary:** when the skill should fire and what similar-looking situations should route elsewhere +4. **Output:** what artifact or change the skill is expected to produce +5. **Project-local facts:** what belongs in `[CUSTOMIZE]` blocks versus reusable instructions +6. **Validation:** what signal proves the skill worked, or what kind of human review is required +7. **Existing asset reuse:** whether this should improve an existing skill instead of creating a new overlapping one + +Prefer improving an existing skill over adding a near-duplicate. Stable skill IDs are easier for users and agents to learn, and they reduce routing drift. + +--- + ## Authoring Principles ### Conciseness @@ -278,6 +296,13 @@ Use a small set of 10-20 test prompts to catch regressions: - **Explicit invocation:** "Use the $skill-name skill to..." (confirms basic functionality) - **Implicit invocation:** Natural language that should trigger the skill without naming it - **Negative control:** Prompts that should NOT trigger the skill (catches false positives) +- **Edge case (optional):** Prompts that stress the fragile parts of the workflow + +Review those prompts for three failure modes: + +- the description is too vague to trigger reliably +- the instructions only handle tidy examples instead of realistic user phrasing +- the skill is overfit to one example instead of a reusable pattern For high-leverage skills such as onboarding, include scenario coverage: @@ -291,6 +316,20 @@ Track these test prompts alongside the skill. Every real-world failure becomes a --- +## Improving Existing Skills + +When revising a skill that already exists: + +1. Read the current `SKILL.md` and any linked `references/` files before editing. +2. Preserve the current skill name unless there is a strong compatibility reason to rename it. +3. Re-test the current description against realistic trigger prompts and near-miss prompts before rewriting it. +4. Prefer removing weak or duplicated instructions over adding more prose. +5. Re-verify that the revised skill is clearer, leaner, and less overfit than before. + +If repeated examples keep implying the same deterministic helper, promote that helper into `scripts/` or `references/` instead of asking the agent to reinvent it on each run. + +--- + ## Maintenance Skills rot when the underlying systems change and the instructions do not.