authoring skills

Security Community

Skill notes

Overview

Create, update, improve, and audit portable Agent Skills. The goal is to make agents reliably better at a repeatable job without bloating context or forcing unnecessary structure.

When To Use

Creating a new Agent Skill or SKILL.md Updating, refactoring, or improving an existing skill Designing a skill's name, description, trigger surface, or exclusions Organizing bundled skill files such as references/, assets/, scripts/, or evals/ Auditing a skill for structure, discovery, progressive disclosure, scripts, security, or eval coverage

Core Principle

Write the simplest and smallest skill that does the job. Add structure, examples, references, assets, scripts, or evals only when they improve the output quality or make the skill easier to discover, follow, verify, or maintain.

Workflow

For non-trivial work, track your progress with a checklist.

Phase 1 - Classify

Determine the path before editing: Creating a skill: run the full workflow. Updating a skill: inspect the existing skill and edit only the parts needed for the requested change. Improving a skill with vague goals: audit first, then fix the highest-value gaps. Auditing a skill: report findings first and stop unless the user asks for edits.

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Security
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@bastienlimbour · no license declared
Token usage
Lean
Setup complexity
Plug-and-play
External API key
Not required
Operating systems
Unspecified (assume cross-platform)
Runtime requirements
No explicit requirements detected
Detected file/system behavior
  • Read-only
  • Write / modify
Network behavior
Local-only
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

01
Phase 1 - Classify

Determine the path before editing: Creating a skill: run the full workflow. Updating a skill: inspect the existing skill and edit only the parts needed for the requested change. Improving a skill with vague goals: audit first, then fix the highest-value gaps. Auditing a skill: report findings first and stop unless the user asks for edits.

02
Phase 2 - Gather Evidence

Inspect existing skill files, source material, real workflows, examples, previous failures, and adjacent skills when available. Ask one targeted question at a time only when missing information would materially change the skill. For substantial new skills or major rewrites, summarize the intended files and ask to proceed unless the user already approved that exact work.

03
Phase 3 - Define The Boundary

Identify the repeatable job, users, inputs, outputs, constraints, non-goals, success criteria, and near-miss tasks that should not trigger the skill. Prefer one coherent job over a broad toolbox. If the proposed skill covers unrelated jobs, split it or narrow the first version.

04
Phase 4 - Design Discovery

Read discovery-and-descriptions.md. Choose a portable lowercase hyphenated `name` that matches the directory. Write a `description` that states what the skill does and when to use it. Front-load core trigger terms and include exclusions only when they prevent likely false positives.

05
Phase 5 - Shape The Package

Read spec-and-structure.md for required format. Start with only `SKILL.md`. Add bundled files only when they earn their keep. Need · Default action Core instructions every run · Keep in `SKILL.md` Rare, long, or conditional detail · Move to `references/`

06
Phase 6 - Write The Body

Read content-patterns.md. Write operational instructions for the agent, not explanatory documentation for humans. Use a scannable structure that fits the skill instead of copying a fixed template. Keep `Overview` to 1-2 sentences about what the skill does and why it matters. Keep `When To Use` focused on activation guidance. Use phase headings, tables, examples, red flags, rationalizations, or verification only when they improve behavior.

07
Phase 7 - Evaluate

Read evaluation.md. Every creation or material update must include a lightweight eval plan or a clear reason evals are unnecessary. Add full eval files for non-trivial skills, risky workflows, scripts, complex activation boundaries, or repeated future use.

08
Phase 8 - Review

Read audit-checklist.md. Fix checklist failures and re-check until the skill is valid, focused, and usable. If auditing only, return findings ordered by severity with concrete fixes.

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.