Guide · Agent skill
How to use the Skill Contract Reviewer agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
Skill Contract Reviewer is an agent skill that checks a proposed Agent Skill folder before it becomes a reusable skill. It is aimed at people who are packaging a repeated workflow into a SKILL.md file for Claude or another agent. After this guide you will know how to install it, how to ask an agent to review a skill folder, and how to read the report it produces.
Skill Contract Reviewerrohitg00/ai-engineering-from-scratch · MIT Download the skill Quick start
- 1Download and unzip. Download the ZIP from the directory page and unzip the skill-contract-reviewer folder.
- 2Place it where your agent looks. Put the folder in ~/.claude/skills/ for personal use, or in .claude/skills/ inside a project, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 3Confirm Python 3 is available. The checker script uses only the Python standard library, so a standard Python 3 install is enough.
- 4Ask for a review. Describe the proposed skill folder in plain language and ask the agent to validate it before you share it.
- 5Read the JSON report. Fix every error the checker reports before you act on the primitive recommendations.
- 6Check the primitive choices. Read the one-sentence reason for each selected primitive and keep only what the workflow needs.
What an agent skill is and what this skill makes the agent do
An agent skill is a folder containing a SKILL.md file. The file has a header with identity fields such as name and description, followed by a Markdown body that holds the procedure the agent should follow for a task.
This skill tells the agent to review that kind of folder before it is used. The agent reads two reference notes, runs a small read-only Python script that validates the SKILL.md header fields and structure, reads the JSON report, and then recommends the smallest set of building blocks for the job: instructions, capabilities, or lifecycle steps.
- Checks that the bundle contains a regular SKILL.md file and that frontmatter has a closing delimiter.
- Checks that name is lowercase, at most 64 characters, and matches the directory name.
- Checks that description is present, at most 1024 characters, and says when the skill is useful.
- Compares the proposed artifact with a set of task shapes and selects primitives such as a prompt, AGENTS.md, an MCP tool, a hook, ordinary code, or a subagent.
Install the skill-contract-reviewer folder
Download the ZIP from the directory page and unzip it. The folder you get should be named skill-contract-reviewer and contain SKILL.md, scripts/check_skill.py, references/contract.md, references/decision-model.md and assets/task-shapes.json.
For a personal install, place the folder in ~/.claude/skills/. For a project install, place it in the project's .claude/skills/ directory. In the Claude apps you can instead upload the skill under Settings → Capabilities → Skills.
- Personal: unzip into ~/.claude/skills/
- Project: unzip into .claude/skills/ inside the project
- Claude apps: Settings → Capabilities → Skills, then upload
Trigger the skill with a natural request
You do not need a special command. Ask the agent in plain language to review a skill you are about to create. The skill's description says it is for validating an Agent Skill package and choosing the right primitive before implementation, so requests that mention those ideas are the ones that should match.
Give the agent the location of the proposed skill folder. The skill asks the agent to resolve paths from the original workspace, so naming the folder relative to your project helps.
- "Review the skill folder at skills/release-notes before we share it."
- "Is this proposed SKILL.md well-formed? Check the header fields."
- "Should this repeated workflow be a skill, an MCP tool, or a hook?"
Read the validation report and selected primitives
The skill asks the agent to show the exact command it resolves before running it, then run the checker against the proposed skill directory. The agent should fix every error in the JSON report before discussing host-specific extensions.
The final answer should include the validation report, the selected primitives with one sentence each explaining the choice, and execution evidence: the resolved script path, resolved target path, working directory, exact argument vector and exit code. If the host cannot expose one of these, the agent should mark it unverified rather than guess.
- Errors must be fixed first; warnings do not block the review.
- Each primitive selection should come with a one-sentence reason.
- Missing evidence should appear as unverified.
python3 "$SKILL_ROOT/scripts/check_skill.py" "$TARGET_SKILL"Know what the validator does not check
A passing check makes a package structurally loadable. It does not show that the skill is safe. The script only checks core identity fields and file structure. It does not audit what the rest of the skill's instructions or scripts do.
The skill also says a valid skill is not permission to run scripts or access tools. Host-specific extensions are outside the portable contract, so the reviewer will not treat them as part of it.
- Not a security audit.
- Does not read or judge the body procedure for risky actions.
- Host-specific extension fields are handled separately and are not validated as portable.
What people use it for
- Checking a SKILL.md for a repeated release-notes workflow before sharing it with a team.
- Confirming that a skill's name matches its folder and that its description is within the length limit.
- Deciding whether a recurring task needs only instructions, or also an external tool or a scripted step.
- Reviewing a teammate's proposed skill in a pull request for structural problems.
Frequently asked questions
How do I install the skill-contract-reviewer agent skill?
Download the ZIP from the directory page and unzip the skill-contract-reviewer folder into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. In the Claude apps you can upload it under Settings → Capabilities → Skills instead.
What does Python 3 need to run this skill?
The script check_skill.py uses only the Python standard library, so you need Python 3 and an agent host that can read files and run shell commands. The skill also needs read access to the skill bundle and the target skill directory.
Is Skill Contract Reviewer free and what is its licence?
The skill is listed under the MIT licence. The source does not mention pricing, so check the directory page for any terms beyond the licence.
Does this skill do a security audit of my skill?
No. The script only checks the core identity fields and file structure. It does not check what the other instructions or scripts in the skill do, so you need a separate review for security.
Does it use the network or run scripts?
It runs one script, check_skill.py, and it does not use the network. The script is read-only, according to the skill's description.
What is the difference between an agent skill, an MCP tool and a hook?
According to the skill's decision model, an Agent Skill loads procedural knowledge for a reusable task, an MCP tool exposes a callable external capability with an input contract, and a hook runs at a host-defined lifecycle point. The reviewer recommends the smallest set that fits the job.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you are a developer or team writing SKILL.md packages and want a structural check plus a clear reason for each building block you choose. Skip it if you need a full security audit, if you are not writing skills, or if your skill depends on host-specific extensions that fall outside the portable contract.
Download the skill