Skill: zenchantlive/writing-better-skills (version 1.0.0)

--- name: writing-better-skills description: Use when creating or improving a skill for an AI agent, especially when the skill needs strong trigger wording, project-local context, references, scripts, tests, self-healing rules, or a completion gate another agent could follow without guessing. license: Complete terms in LICENSE.txt --- # Writing Better Skills Create better skills for agents. A skill helps an agent do work. It is reusable operational guidance plus optional references, scripts, tests, and narrow remediation. It is **not** something that "turns an agent into a skill." This skill is the control plane for authoring other skills: - it tells the agent **when** to use the skill-creation framework - **what laws** must not be violated - **which references** to read for each decision - **when** scripts, tests, and self-healing are justified - **what completion means** ## When to Use Use this when authoring or revising a skill and you need to decide: - what belongs in `SKILL.md` - what should move into `references/` - when project-local context is needed - when to add scripts and tests - whether self-healing is justified - whether a fresh agent could use the skill without guessing ## The Iron Laws ```text NO PROJECT-SPECIFIC CONTEXT IN THE GLOBAL SKILL ``` If a path, command, constraint, or convention belongs to one repository, it goes in `project.skill.md`, not in the reusable skill. ```text NO SKILL IS COMPLETE UNTIL A FRESH AGENT COULD USE IT WITHOUT GUESSING CRITICAL FACTS ``` If another agent would have to invent project-local commands, output paths, trigger conditions, or completion criteria, the skill is incomplete. **Violating the letter of these laws is violating the spirit of the skill.** ## Project-Local Context Comes First The global skill must stay reusable. Before doing substantial work with a skill in a repository: 1. Look for `project.skill.md` in the **project root**. 2. If it exists, read it before taking action. 3. If it does not exist and local context is needed, create it from `project.skill.template.md`. 4. Put environment-specific paths, commands, constraints, and conventions in `project.skill.md`, not in the global skill. 5. Treat `project.skill.md` as overriding generic guidance in `SKILL.md` when local details differ. Read `references/project-skill-context.md` before defining or revising that contract. ## Skill Organization Model ### `SKILL.md` = the router `SKILL.md` is the main behavioral document. It should tell the agent: - when to use the skill - what laws and stop conditions apply - what order to follow - which references to read - which scripts to run - what completion requires ### `references/` = deep guidance References hold heavier, conditional, or decision-specific material. Use references for: - description-writing rules - project-local context rules - architecture-level decisions - script/test conventions - self-healing rules - behavioral validation - completion gates ### `scripts/` = deterministic helpers Use scripts for repeated deterministic work the agent should not keep re-deriving. ### `tests/` = proof Use tests to prove shipped scripts or promised behaviors work. ### `self-healing/` = narrow remediation Use self-healing only for safe, local, repeatable fixes. ## Architecture Levels Choose the smallest structure that reliably supports the work. ### Minimal skill ```text my-skill/ └── SKILL.md ``` ### Reference-backed skill ```text my-skill/ ├── SKILL.md ├── project.skill.template.md └── references/ ``` ### Operational skill ```text my-skill/ ├── SKILL.md ├── project.skill.template.md ├── references/ ├── scripts/ └── tests/ ``` ### Resilient operational skill ```text my-skill/ ├── SKILL.md ├── project.skill.template.md ├── references/ ├── scripts/ ├── tests/ └── self-healing/ ``` Read `references/skill-architecture-levels.md` before deciding how much structure to add. ## Authoring Phases You must complete each phase before moving on. ### Phase 1: Define the boundary Decide: - what problem the skill solves - what belongs in the reusable global skill - what must remain project-local - whether local context actually matters If local commands, paths, outputs, or constraints vary by project, plan for `project.skill.template.md`. ### Phase 2: Define trigger and routing Write the frontmatter and top of `SKILL.md`. Requirements: - description says **when to use** the skill - `SKILL.md` routes the agent to `project.skill.md` early when local context matters - `SKILL.md` tells the agent which references/scripts matter at which step Read `references/description-writing.md` before finalizing the description. ### Phase 3: Add only justified structure Add references, scripts, tests, and self-healing only when earned. Use these references: - `references/script-test-conventions.md` before shipping scripts - `references/self-healing-rules.md` before adding self-healing - `references/skill-testing.md` before deciding what to validate ### Phase 4: Validate fresh-agent usability Before calling the skill complete, test whether a fresh agent could: - identify when to use the skill - find the right local context file - choose the right reference or script - know what completion means Read `references/behavioral-validation-checklist.md`. ### Phase 5: Apply the completion gate Do not claim the skill is complete until it passes the completion gate. Read `references/completion-gate.md`. ## Routing Map Use this map while authoring: - Need to define project-local context? → `references/project-skill-context.md` - Need to choose architecture level? → `references/skill-architecture-levels.md` - Need to write a better trigger description? → `references/description-writing.md` - Need to add or test scripts? → `references/script-test-conventions.md` - Need to decide whether healing is allowed? → `references/self-healing-rules.md` - Need to validate fresh-agent usability? → `references/behavioral-validation-checklist.md` - Need to decide if the skill is complete? → `references/completion-gate.md` - Need general workflow or output guidance? → `references/workflows.md`, `references/output-patterns.md` ## Scripts in This Repo Use the shipped scripts when they reduce repeated, deterministic work: - `scripts/quick_validate.py` — fast validation of frontmatter and core structural promises If you find yourself manually re-checking the same structural conditions repeatedly, prefer strengthening this validator rather than rewriting the checks ad hoc. ## Reference Skill See `reference-skills/release-notes-generator/` for a canonical reference skill authored using this framework. Use it as a model implementation of: - a reusable global skill - a shipped `project.skill.template.md` - references routed from `SKILL.md` - a deterministic script with a paired test - narrow self-healing It is a specimen of the framework, not a substitute for the framework. ## Red Flags — STOP Stop and correct course if you are thinking: - "I’ll just put this command/path in SKILL.md" - "The agent can infer the local commands" - "This script is too small to test" - "I’ll add the test later" - "This self-healing is probably safe" - "The example will clarify the missing instructions" - "A fresh agent will figure it out" - "Close enough" All of these usually mean you are about to violate one of the iron laws. ## Common Rationalizations | Excuse | Reality | |--------|---------| | "It’s faster to put the path in SKILL.md" | That contaminates the global skill with local assumptions. Use `project.skill.md`. | | "Agents can infer the local commands" | Guessing local commands is exactly what project-local context is for. | | "This script is simple, it doesn’t need a test" | If it is worth shipping, it is usually worth validating. | | "Self-healing can just fix a bunch of stuff" | Broad auto-fixes are risk, not resilience. | | "The worked example will show the pattern" | The skill itself must be usable without depending on an example. | | "The structure looks right, so the skill is done" | Organization alone does not prove fresh-agent usability. | ## Completion Gate Before claiming a skill is complete, verify all of these: - the description says when to use the skill - the global skill contains no project-specific commands, paths, or constraints - `SKILL.md` routes the agent to `project.skill.md` early when local context matters - references are clearly named and linked from `SKILL.md` - shipped scripts are justified and paired with tests, or explicitly exempted with a reason - self-healing is narrow and safe - a fresh agent could use the skill without guessing critical facts ## Bottom Line A better skill is not just more elaborate. A better skill: - stays reusable at the global level - pushes local facts into `project.skill.md` - routes the agent clearly through references and scripts - validates what it ships - resists rationalization - is complete only when a fresh agent could use it without guessing

path: LICENSE.txt
content: MIT License

Copyright (c) 2026 zenchantlive

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


path: project.skill.template.md
content: # Project Skill Context

This file is the project-local companion to a reusable global skill.

Use it to capture environment-specific instructions for **this repository** without editing the global skill itself.

## Instructions for the setup agent

1. Replace placeholders with concrete local facts.
2. Prefer exact commands, paths, and output locations over prose.
3. Remove sections that do not apply.
4. Add at least 2 local usage examples.
5. Do **not** store secrets in this file.
6. Save the completed file in the project root as `project.skill.md`.

## 1. Purpose in This Project

- Skill name:
- Primary use in this project:
- Out of scope:
- Typical tasks this skill supports here:

## 2. Repository / Environment Context

- Repository name:
- Primary working directory:
- Relevant subdirectories:
- Main language(s):
- Framework(s):
- Package manager:
- Runtime / toolchain:

## 3. Required Commands

- Install:
- Dev:
- Test:
- Lint:
- Build:
- Format:
- Typecheck:
- Package / release:

## 4. Inputs and Outputs

- Input files usually come from:
- Generated outputs should go to:
- Temporary files should go to:
- Files or directories that must not be modified:

## 5. Project Conventions

- Naming conventions:
- File organization rules:
- Documentation conventions:
- Review expectations:

## 6. Constraints and Guardrails

- Never:
- Always:
- Ask before:
- Safe assumptions:
- Unsafe assumptions:

## 7. External Tools / Dependencies

- Required CLIs:
- Required environment variables (names only, no values):
- Services/APIs involved:
- Authentication expectations:
- What to do if a dependency is missing:

## 8. Validation Requirements

- Required tests:
- Required checks:
- Required output validation:
- Evidence needed before completion:

## 9. Local Usage Examples

### Example 1
- Goal:
- Files involved:
- Commands:
- Expected result:

### Example 2
- Goal:
- Files involved:
- Commands:
- Expected result:

## 10. Maintenance Notes

- Owner of this file:
- Last updated:
- Update this file when:
- Related project docs:


path: tests/test_project_workflow.py
content: #!/usr/bin/env python3
from __future__ import annotations

import shutil
import subprocess
import sys
from pathlib import Path


def run(cmd: list[str], cwd: Path) -> tuple[int, str, str]:
    result = subprocess.run(cmd, cwd=cwd, capture_output=True, text=True, check=False)
    return result.returncode, result.stdout, result.stderr


def main() -> int:
    root = Path(__file__).resolve().parents[1]
    project = root / "examples" / "release-notes-project"
    generate = root / "reference-skills" / "release-notes-generator" / "scripts" / "generate_release_notes.py"
    heal = root / "reference-skills" / "release-notes-generator" / "self-healing" / "heal_output_dir.py"

    out_dir = project / "dist"
    out_file = out_dir / "release-notes.md"
    if out_dir.exists():
        shutil.rmtree(out_dir)

    code, out, err = run([sys.executable, str(generate), "data/release-input.json", "dist/release-notes.md"], project)
    if code != 2:
        print(out, end="")
        print(err, end="")
        print(f"Expected initial failure code 2 for missing output directory, got {code}")
        return 1

    code, out, err = run([sys.executable, str(heal), "dist"], project)
    if code != 0:
        print(out, end="")
        print(err, end="")
        return code

    code, out, err = run([sys.executable, str(generate), "data/release-input.json", "dist/release-notes.md"], project)
    print(out, end="")
    if code != 0:
        print(err, end="")
        return code
    if not out_file.exists():
        print("Expected generated release notes file is missing")
        return 1
    return 0


if __name__ == "__main__":
    raise SystemExit(main())


path: tests/test_quick_validate.py
content: #!/usr/bin/env python3
from __future__ import annotations

import subprocess
import sys
from pathlib import Path


def main() -> int:
    root = Path(__file__).resolve().parents[1]
    validator = root / "scripts" / "quick_validate.py"

    result = subprocess.run(
        [sys.executable, str(validator), str(root)],
        capture_output=True,
        text=True,
        check=False,
    )
    print(result.stdout, end="")
    if result.returncode != 0:
        print(result.stderr, end="")
        return result.returncode
    return 0


if __name__ == "__main__":
    raise SystemExit(main())


path: tests/test_reference_skill.py
content: #!/usr/bin/env python3
from __future__ import annotations

import subprocess
import sys
from pathlib import Path


def run(cmd: list[str]) -> int:
    result = subprocess.run(cmd, capture_output=True, text=True, check=False)
    print(result.stdout, end="")
    if result.returncode != 0:
        print(result.stderr, end="")
    return result.returncode


def main() -> int:
    root = Path(__file__).resolve().parents[1]
    validator = root / "scripts" / "quick_validate.py"
    ref_skill = root / "reference-skills" / "release-notes-generator"
    ref_test = ref_skill / "tests" / "test_generate_release_notes.py"

    if run([sys.executable, str(validator), str(ref_skill)]) != 0:
        return 1
    if run([sys.executable, str(ref_test)]) != 0:
        return 1
    return 0


if __name__ == "__main__":
    raise SystemExit(main())


path: tests/test_root_skill_package.py
content: #!/usr/bin/env python3
from __future__ import annotations

import subprocess
import sys
from pathlib import Path


def main() -> int:
    root = Path(__file__).resolve().parents[1]
    validator = root / "scripts" / "quick_validate.py"

    result = subprocess.run(
        [sys.executable, str(validator), str(root)],
        capture_output=True,
        text=True,
        check=False,
    )
    print(result.stdout, end="")
    if result.returncode != 0:
        print(result.stderr, end="")
        return result.returncode
    return 0


if __name__ == "__main__":
    raise SystemExit(main())


path: references/behavioral-validation-checklist.md
content: # Behavioral Validation Checklist

Use this checklist before claiming a skill is complete.

## Fresh-agent usability

A fresh agent using only the skill should be able to answer:
- When should this skill be used?
- What file should be read first?
- What parts are global vs project-local?
- Which references matter for the current step?
- Which scripts should be used instead of re-implementing logic?
- What proves the skill is working?

## Required checks

### 1. Trigger clarity
- The frontmatter description says when to use the skill.
- The trigger conditions are concrete enough that another agent can identify applicability.

### 2. Local context routing
- `SKILL.md` tells the agent early to look for `project.skill.md` when local context matters.
- The skill does not require editing the global skill for project-specific setup.

### 3. Reference routing
- `SKILL.md` tells the agent which reference to read for which decision.
- References are modular, not a junk drawer.

### 4. Script routing
- `SKILL.md` tells the agent when to use shipped scripts.
- Deterministic repeated logic is not left as implicit reimplementation work.

### 5. Completion clarity
- The skill says what completion means.
- The agent can tell what must be verified before claiming success.

## Failure signs

The skill is not ready if a fresh agent would have to guess:
- project-specific commands
- output paths
- whether a script should exist
- whether a failure should trigger self-healing
- what "done" means


path: references/completion-gate.md
content: # Completion Gate

A skill is not complete just because it looks organized.

## Minimum completion standard

Before claiming a skill is complete, verify:

- the description says when to use the skill
- the global skill does not contain project-specific commands, paths, or constraints
- `SKILL.md` routes the agent to `project.skill.md` early when local context matters
- references are named clearly and linked from `SKILL.md`
- shipped scripts are justified
- shipped scripts are tested or explicitly exempted with a reason
- self-healing is narrow and safe
- a fresh agent could use the skill without guessing critical facts

## Completion claim rule

Do not claim a skill is complete based on structure alone.

Completion requires both:
1. structural coherence
2. fresh-agent usability

## Stronger standard for operational skills

If the skill ships scripts, completion should also include:
- passing script tests
- clear validation instructions
- clear routing to the correct script

## Stronger standard for resilient skills

If the skill ships self-healing, completion should also include:
- a clearly documented safe trigger condition
- a rerun step after healing
- a stop condition when healing does not resolve the issue


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)