m-hosseinpour/agent-skills

writing-skills

Use when creating, reviewing, or improving an agent skill; turning a repeatable workflow into a skill; investigating missed or unwanted skill loading; or changing a skill's SKILL.md, references, or helper scripts in ways that affect use.

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/m-hosseinpour/agent-skills --skill writing-skills

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

Writing Skills

A skill should help an agent make a better decision or produce a better result on a recurring task. Make it easy to select, useful when loaded alone, and no more demanding than the problem it addresses.

Loading this skill does not require a new skill, rewrite, test framework, subagent, or approval ceremony. For a review-only request, report findings and proposals without editing. Scale authoring and checks to the change.

1. Establish the Need and Scope

Read the current skill, relevant supporting files and project instructions, and nearby skill metadata before choosing a solution. Open neighboring bodies when ownership or boundaries need clarification, not as a full library sweep. When available, inspect actual missed loads, wrong outputs, or repeated user corrections. Do not invent a failure because a baseline happens to succeed.

Decide:

  • What improves? Name the recurring task, intended result, observed gap or explicit requirement, and important exceptions.
  • Where does it belong? Improve an existing skill when it already owns the trigger. Keep project-only rules in project instructions, session progress out of skills, and deterministic checks in existing automation when suitable. A separate skill needs a distinct selectable task, not just more detail within another workflow.
  • What is authorized? Separate an audit, a proposed design, and implementation. Ask only about unresolved choices that would materially change scope or behavior; do not reopen settled decisions.

For uncertain structure or portability choices, open authoring patterns and format notes. It distinguishes the open format from product-specific behavior; it is not a second mandatory checklist.

2. Design the Trigger Before the Body

Agents normally select from the name and description before seeing the body. A boundary mentioned only in the body cannot prevent the initial wrong selection.

  • Use a short, specific name. Match the folder name to frontmatter name; use lowercase letters, digits, and single hyphens, without a leading or trailing hyphen.
  • Start the description with Use when.... Name observable tasks, symptoms, and user intent, including implicit requests when they belong. Avoid a summary of the internal workflow or an exhaustive keyword list.
  • Add exclusions for plausible neighboring tasks, not obviously unrelated ones. An explicit request to create or audit a skill can be small; task size alone should not suppress it.
  • Define realistic prompts that should load it and near-misses that should not. Include wording that does not name the skill, and relevant user languages. Check selection using metadata alone, separately from application with the body loaded.

If loading is wrong, determine whether the runtime registered the skill and exposed current metadata before broadening the description. Installer discovery, metadata classification, an actual load, and useful execution are different evidence.

3. Write the Smallest Useful Guidance

State purpose and scope first, then the decisions or steps that change the result. Include needed inputs, meaningful exceptions, how to handle unavailable evidence/tools, and observable completion criteria. Use concrete examples only where they clarify a real choice; do not explain basics the agent already knows.

  • Keep essential guidance in SKILL.md. Put focused detail in references/ and runnable helpers in scripts/. Every supporting file needs a reachable entry point with when to open/run it and why, preferably beside the relevant decision rather than only in a closing file list.
  • Use relative Markdown links for reading and explicit commands for execution. Resolve resources from the loaded skill's directory, not the project's current directory or a hard-coded installation path. Optional details need not be read every time, but a required branch must make its required reference clear.
  • Keep one owner for each rule; references expand the body, not contradict it. Keep main references directly reachable from SKILL.md and give long guides a contents list or split them by decision.
  • Preserve user constraints and instruction priority. A skill cannot authorize deletion, installation, delegation, publication, or policy overrides. Other skills may help when available, but should not be an unconditional dependency unless the skill explicitly targets that environment.
  • Prefer a positive recipe or output shape. Use firm boundaries for real risks, not manufactured urgency or obedience rituals. When recurring bypasses need clearer discipline guidance, read discipline wording.

A diagram is optional. When branching is genuinely clearer visually, use the small Graphviz example. For SVG preview, run node <skill-dir>/scripts/render-graphs.mjs <target-skill-dir>; it requires Node.js and Graphviz dot, expects one graph per top-level dot fence (up to three leading spaces, not inside a list or blockquote), writes numbered SVGs to the target's diagrams/, and refuses existing output files. Use --output-dir <new-directory> to choose another destination. Unsupported indented/quoted fences fail explicitly instead of silently skipping diagrams. It renders diagrams separately; it does not combine independent graphs. Render only trusted DOT inputs; this helper does not sandbox Graphviz or sanitize SVG for publication.

4. Verify Selection, Usefulness, and the Package

Choose checks that could expose the changed behavior, using the project's existing practices. Do not add a framework or a fixed test campaign merely because this skill loaded.

  1. Selection: compare positive and near-miss prompts against metadata. When automatic-loading evidence matters, use a safe scoped request in the target runtime without naming the skill and inspect the actual load/read event. Fresh sessions avoid old metadata; repeated runs or additional models are useful when variability or deployment scope warrants them.
  2. Application: give a reader or fresh evaluator the body, relevant facts, and access to resources. Ask for a concrete decision or artifact, not a recital. Define expected outcomes independently of the wording being tested. Compare with no skill or the previous revision when practical; keep evaluator context and tools comparable. A successful baseline is evidence too.
  3. Package: validate frontmatter against the current format/target installer, confirm discovery, follow relative links from a standalone copied folder, and exercise changed scripts with representative success and failure inputs. Check dependencies, output locations, nonzero failure status, and preservation of existing data. Update README, moved-path references, and attribution notices when affected.

Open testing skills when designing behavior comparisons or diagnosing a failed evaluation. For testing always-loaded instructions that select skills, use the instruction-file experiment, not as a default instruction to browse every installed skill.

Keep raw results and session progress outside live guidance. Report the revision checked, checks run, concrete misses or regressions, and skipped checks. A read-through is not a behavior test; a simulation or installer listing is not proof of automatic loading, cross-model reliability, or real-world safety. Stop when agreed outcomes have adequate evidence or a named evidence/authorization gap blocks further checking—not when a skill seems “bulletproof.”

Evaluating This Skill

Maintainers can use evaluation scenarios to check this skill's own selection, useful application, and reference navigation. These are reusable cases, not completed results or steps for every authoring task.

Adapted supporting material retains a bundled license notice; consult it for provenance or redistribution, not as authoring guidance.

같은 저장소의 Skills

더 많은 Skills

모든 Skills
m-hosseinpour
커뮤니티

curating-global-instructions

Use when adding to, trimming or reorganizing the instruction file loaded into every session whatever the project — the global CLAUDE.md, AGENTS.md, or whatever plays that role — or when it has grown past what a session can hold.

1시간 설치 수
2
GitHub Stars
0
업데이트
11월 15일
m-hosseinpour
커뮤니티

designing-persian-rtl-web-ui

Use when building, changing, or checking a Persian (Farsi) web interface — including right-to-left layout, typography, UI copy, numerals, responsive behavior, or dark mode — and before calling Persian UI work done. Not for RTL-only work in non-Persian interfaces.

1시간 설치 수
2
GitHub Stars
0
업데이트
11월 15일
m-hosseinpour
커뮤니티

dispatching-parallel-agents

Use when delegation is available and allowed and a task has multiple substantial workstreams that may be independent, when parallel agent work is requested, or before running a subagent alongside your own work or other subagents. Not for small multi-step tasks, parallel tool calls, or one delegate you will simply wait for.

1시간 설치 수
2
GitHub Stars
0
업데이트
11월 15일
m-hosseinpour
커뮤니티

research-with-evidence

Use when researching a question across multiple sources, doing in-depth web research, comparing options using external evidence, investigating conflicting claims, or checking the substantive claims and sources of a research report. Not for a simple factual lookup, explanation from already-sufficient evidence, translation or editing without fact-checking, code-change review, or diagnosing a concrete software failure.

1시간 설치 수
2
GitHub Stars
0
업데이트
11월 15일