writing-skills — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited writing-skills (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
Framework for creating quality skills for the Claude Code foundation, respecting the existing conventions and structure.
.claude/skills/<skill-name>/
└── SKILL.md---
name: my-skill
description: Clear description of the skill. Trigger when [activation context].
---
# Skill Title
## Objective
[Clear description of what the skill does]
## Instructions
[Detailed instructions, structured in steps]
## Expected output
[Expected output format]
## Rules
[Mandatory rules for the skill]All fields available in the YAML frontmatter of a skill:
| Field | Required | Description |
|---|---|---|
name | No | Skill name (default: folder name). Lowercase, digits, hyphens (max 64 chars) |
description | Recommended | What the skill does and when to use it. Claude uses this to decide when to load the skill |
allowed-tools | No | Tools pre-approved for the skill's turn (grants, never restricts). The foundation declares none: the project's permission settings decide; add one precise, reviewed rule such as Bash(npm test:*) only for a truly unattended need |
context | No | Omit it (default): the skill runs inline and sees the conversation. fork (the only value) runs it in a sub-agent that sees NONE of the conversation — only for a self-contained job such as a report or a batch over the repo |
background | No | With context: fork only. Since CC 2.1.218 forked skills run in the BACKGROUND by default (async result, narrower background tool set, edits bypass /rewind checkpoints). Set false to block in-turn — the foundation default for workflow skills |
model | No | Forked skills only in this foundation: the subagent's model (sonnet, opus, haiku, inherit). On an inline skill it switches the SESSION's model for the rest of the turn, so leave it out |
agent | No | Sub-agent type when context: fork (Explore, Plan, general-purpose, or custom agent) |
disable-model-invocation | No | true = manual invocation only (Claude cannot auto-load). Default: false |
user-invocable | No | false = invisible in the / menu (background skills). Default: true |
argument-hint | No | Autocompletion hint shown in the / menu. E.g.: [issue-number] or [filename] [format] |
hooks | No | Hooks scoped to the skill lifecycle (PreToolUse, PostToolUse, Stop) |
| Variable | Description |
|---|---|
$ARGUMENTS | All arguments passed to the skill |
$ARGUMENTS[N] | Argument by index (0-based) |
$N | Shortcut for $ARGUMENTS[N] |
${CLAUDE_SESSION_ID} | Current session ID |
Use the backtick-bang syntax to inject live data:
! followed by backtick then gh pr diff then backtickBash; a project that narrowed them allows the precise command in its own permission settings (e.g. Bash(gh pr diff:*)). Foundation skills still declare no allowed-toolsExample:
## PR Context
- Diff: !`gh pr diff`
- Files: !`gh pr diff --name-only`supporting files)SLASH_COMMAND_TOOL_CHAR_BUDGET)examples/, scripts/, reference.md in the skill folderdisable-model-invocation: true for skills that should only be launched manually (e.g.: commit, PR, plan)user-invocable: false for context/background skills that Claude loads automatically (state-management, api-mocking)model on an inline skill (it would switch the user's session model); on a forked skill, pick the subagent's tier by costargument-hint to guide the user on the expected parameters[ ] Valid YAML frontmatter (name, description)
[ ] kebab-case name
[ ] Description with trigger context
[ ] No `allowed-tools` (the foundation pre-approves nothing)
[ ] No `context` (inline) unless the skill is a self-contained job; forking is a review decision (the forked set is pinned in tests/skills-frontmatter.bats)
[ ] If forked: background: false (block in-turn; omit only for a deliberately detached skill)[ ] Clear objective in 1-2 sentences
[ ] Instructions structured as numbered steps
[ ] Relevant code examples
[ ] Expected output with template
[ ] Explicit rules and constraints
[ ] ASCII diagram if complex workflow[ ] Actionable (not just informative)
[ ] Specific (not generic)
[ ] Testable (verifiable results)
[ ] Standalone (no dependency on other skills)
[ ] Consistent with the foundation's conventions| Type | Convention | Examples |
|---|---|---|
| Dev skills | dev-* | dev-tdd, dev-debug, dev-api |
| QA skills | qa-* | qa-review, qa-security |
| Ops skills | ops-* | ops-docker, ops-ci |
| Doc skills | doc-* | doc-generate, doc-changelog |
| Growth skills | growth-* | growth-seo, growth-cro |
| Biz skills | biz-* | biz-model, biz-mvp |
| Legal skills | legal-* | legal-rgpd |
| Data skills | data-* | data-pipeline |
| Workflow skills | work-* | work-explore, work-plan |
| Meta skills | Descriptive name | parallel-agents, session-handoff |
1. ASCII workflow diagram (if applicable)
2. Numbered steps with subsections
3. Tables for quick references
4. Code blocks with specified language
5. "Expected output" section with template
6. "Rules" section with IMPORTANT/NEVER/YOU MUST| Skill type | Recommended tools |
|---|---|
| Read-only (audit, review) | Read, Glob, Grep |
| Development | Read, Write, Edit, Bash, Glob, Grep |
| Infrastructure | Read, Write, Edit, Bash, Glob, Grep |
| Documentation | Read, Write, Edit, Glob, Grep |
| Analysis | Read, Glob, Grep |
.claude/commands/<domain>/<name>.mdFormat: detailed prompt with $ARGUMENTS, workflow, expected output, related agents.
.claude/agents/<name>.mdFormat: YAML frontmatter with model, permissionMode, disallowedTools, skills, hooks.
.claude/rules/<name>.mdFormat: frontmatter with paths, contextual rules per file type.
1. IDENTIFY the need (which problem does this skill solve?)
2. NAME according to conventions (domain-action)
3. DEFINE nothing to pre-approve: `allowed-tools` grants, never restricts, and the foundation declares none
4. WRITE the SKILL.md with the template
5. CREATE the associated command if manual invocation is needed
6. CREATE the associated agent if isolated execution is needed
7. TEST the skill (invoke it and verify the result)
8. DOCUMENT in CLAUDE.md (skills table)context) unless the skill needs no conversation at all~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.