Writing Skills

Writing skills

This is the meta-skill: it teaches an agent how to write other skills, and it ships a linter + admission-preview tool to catch errors before the admission gate does.

When to use

Trigger phrases:

• "Write a skill for X"
• "Create a skill that does Y"
• "Scaffold a new skill"
• "Help me author a skill"
• "How do I make a skill that …"
• Anywhere the operator asks for a new ~/.claude/skills// or

/.claude/skills//.

DO NOT use this for:

• Editing an existing skill (use the dashboard "Edit frontmatter" button

instead).

• Documenting facts (those go in references/ or zc_remember, not in

a skill).

• One-off tasks (if the procedure isn't worth running ≥3 times, don't

encode it as a skill).

Procedure

Step 1 — confirm the four invariants are satisfiable

Before writing a single line, talk to the operator and confirm:

1. Trigger — can you write a one-sentence "use this whenever X" rule?

If not, stop. The user's request is for a one-off, not a skill.

1. Procedural — does the work decompose into 3–7 ordered steps?

If not, the procedure is either too vague or too narrow.

1. Single-responsibility scripts — does each step map to one bundled

script (or one in-line Bash command)? If a step needs a script that does five things, split it.

1. Project-config-aware — does the procedure touch project-specific

values (paths, names, ports)? If yes, the script must read those from /.-config.json or zc_remember, never hardcoded.

If any of the four is shaky, stop and discuss with the operator before generating any files.

Step 2 — decide the scope (global vs project-local)

This decision matters. Get it wrong and the skill either pollutes the global namespace with project-specific assumptions, or it gets duplicated across N projects when one global skill + per-project config would have sufficed.

Decision matrix — answer these questions:

| Question | If YES → | If NO → | |---|---|---| | Does the procedure touch only standard files (package.json, CHANGELOG.md, README.md, pyproject.toml, *.test.js)? | Maybe global | Maybe project | | Does the procedure have ZERO hardcoded paths, project names, ports, DB IDs, internal URLs? | Maybe global | Project | | Has this exact pattern appeared in ≥2 distinct projects already? | Strong global | Project (for now) | | Does the procedure reference project-specific files (HANDOFF.md, STRATEGY.md, internal-policies.md)? | Project | Maybe global | | Does the procedure encode a team-specific convention (commit format, branch naming, deploy URL)? | Project | Maybe global | | Does the procedure only fire in one repo so far? | Project (promote later) | Maybe global |

Default tie-breaker: project-local. Promotion from project → global is cheap; the reverse is expensive (operators in other projects may have come to depend on a global skill that quietly made wrong assumptions).

The "global skill + per-project config" pattern: when a procedure is 95% generic with a 5% project-specific tail, make it global and read the 5% from /.-config.json (or zc_remember). One global skill, N project configs. See references/scope-decision.md for the full pattern + worked examples.

Concrete examples from the SecureContext repo:

| Skill | Scope | Why | |---|---|---| | publish-github-release | global | Touches only package.json + CHANGELOG.md + git + gh CLI. Zero project specifics. | | writing-skills (this one) | global | Meta-skill. Project-agnostic by definition. | | revclear-test-creds-injection | project | RevClear-specific credentials encoded in the procedure. | | cleancheck-rls-patch | project | CleanCheck's specific Supabase Row-Level-Security patch. | | readme-author | global | Generic; reads project metadata from package.json + zcprojectcard. |

When you scaffold, you MUST pass --scope-rationale "..." justifying the choice. The scaffolder refuses to proceed without one. This forces the decision to be conscious + auditable rather than reflexive.

Step 3 — generate the skill scaffold

Run the scaffolder:

python ~/.claude/skills/writing-skills/scripts/scaffold-skill.py \
    --name  \
    --scope  \
    --description "Use this whenever . The skill ." \
    --project  \
    [--with-script ] ...

The scaffolder creates:

• /SKILL.md with the four-invariant template filled in
• /scripts/.py skeletons (one per --with-script)
• /.-config.json (in the project root, if project-scoped)

Step 4 — fill in the procedure + scripts

The operator (or you, with the operator's guidance) edits:

• SKILL.md body — the 3–7 numbered procedural steps
• Each scripts/.py — single-responsibility, argparse-driven, stdout=answer

While editing, follow the script-writing rules in references/script-rules.md:

• No eval/exec/compile/pickle.loads/dynamic __import__
• No subprocess(shell=True) unless you declare shell_exec_ok: true
• Args via argparse, stdout=answer, stderr=diagnostics, exit-code 0=success

Step 5 — lint locally

Before admission, run the linter:

python ~/.claude/skills/writing-skills/scripts/lint-skill.py 

Reports:

• Frontmatter validation errors (matches admission gate's strict mode)
• Trigger sentence detection (regex for "use this whenever")
• Step-count check (3–7 steps required)
• Bundled-script presence check
• Hardcoded-path / project-name detection (warns; not blocking)

Exits non-zero on any error. Operator iterates until clean.

Step 6 — preview admission

Confirm the admission gate will admit:

python ~/.claude/skills/writing-skills/scripts/preview-admission.py 

This calls a dry-run mode against the live SecureContext API. Reports:

• Frontmatter validation result
• Per-script AST scan results (with violations, severities, line numbers)
• Whether the skill would be admitted or quarantined
• Suggested fixes for any blocking findings

Step 7 — install + verify

# Global skill:
cp -r  ~/.claude/skills//

# Project-local skill (operator runs from project root):
cp -r  .claude/skills//

# Trigger admission (if not at sc-api boot):
curl -s -X POST \
    -H "Authorization: Bearer $ZC_API_KEY" \
    "$ZC_API_URL/api/v1/skills/import-project?path=$(pwd)"

Confirm in the dashboard at http://localhost:3099/dashboard:

• Active skills panel lists the new skill with a 📁 filesystem badge
• Admission log shows an admitted event
• Chain banner stays green

Bundled scripts

• scripts/scaffold-skill.py — generates a new skill directory from arguments
• scripts/lint-skill.py — checks an existing skill against the four invariants

(matches the admission gate's strict mode + adds operator-friendly hints)

• scripts/preview-admission.py — calls the live API in dry-run mode to

preview what admission would do

Reference materials

• references/scope-decision.md — global-vs-project-local decision matrix
• references/script-rules.md — the AST-scanner's blocked-pattern list
• references/frontmatter-spec.md — Anthropic frontmatter + SecureContext extensions

Failure modes + recovery

| Symptom | Cause | Fix | |---|---|---| | lint-skill.py says "no trigger detected" | Description doesn't have "use this whenever" or "Use this whenever" | Rewrite description sentence one | | preview-admission.py says "block_severity: eval" | A scripts/*.py uses eval() or exec() | Refactor — never legitimate in a skill | | Skill imports but never fires | L1 description too vague | Make trigger more specific (literal words / phrases the user types) | | Admitted skill blocked at runtime | Script was edited after admission | Re-trigger admission via POST /api/v1/skills/import-project |

Reference

The full guide lives at docs/SKILL_AUTHORSHIP_GUIDE.md in the SecureContext repo. This skill's body is the operational summary; the doc is the rationale.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: iampantherr
• Source: iampantherr/SecureContext
• License: MIT

Install and usage instructions live in the source repository linked above.